De vormgeving van een agent aanpassen

Note

Dit artikel beschrijft functies die worden gebruikt in agenten of agentstromen die gebruikmaken van het standard harness.

Het canvas van de agent bepaalt hoe de agent voor gebruikers wordt weergegeven. U kunt het canvas op twee manieren aanpassen:

  • Pas het standaardcanvas aan met behulp van JavaScript en CSS op uw website. Gebruik deze optie voor eenvoudige wijzigingen.

  • Gebruik een aangepast canvas op basis van het Bot Framework Webchat canvas. Deze optie vereist ontwikkelervaring en biedt ondersteuning voor volledige aanpassing.

U kunt het aangepaste canvas ook combineren met het configureren van een automatisch gesprek starten.

U kunt de naam en het pictogram van de agent wijzigen in de portal.

Nadat u een agent heeft gepubliceerd, kunnen gebruikers ermee interageren via het Webchat canvas.

Important

U kunt de voorbeeldcode in dit artikel alleen installeren en gebruiken voor gebruik met Copilot Studio. De voorbeeldcode wordt in de huidige staat in licentie gegeven en valt niet onder enige serviceovereenkomst of ondersteuningsservices. U draagt het risico om het te gebruiken.

Microsoft geeft geen expliciete garanties of voorwaarden en wijst uitdrukkelijk alle impliciete garanties af, waaronder garanties van verhandelbaarheid, geschiktheid voor een bepaald doel en niet-schending.

Wijzig de naam en het pictogram van de agent

Important

  • Nadat u het pictogram voor een agent hebt bijgewerkt, kan het tot 24 uur duren voordat het nieuwe pictogram overal wordt weergegeven.
  • Als uw agent is verbonden met Omnichannel voor klantenservice, definieert de eigenschap Display name in de Azure portalregistratie de naam.
  • Als uw agent is bedoeld om te worden gepubliceerd naar Teams, raadpleegt u de vereisten voor pictogrammen in de documentatie voor ontwikkelaars van Microsoft Teams.
  1. Ga naar de pagina Overzicht voor uw agent.

  2. Selecteer Bewerken naast Details.

  3. Wijzig de naam en het pictogram van de agent naar wens.

  4. Klik op Opslaan.

Het standaardcanvas aanpassen (eenvoudig)

Gebruik JavaScript en CSS om het standaardcanvas aan te passen.

Stel eerst in waar je je agent canvas inzet.

  1. Een agent maken en publiceren.

  2. Kopieer de HTML-voorbeeldcode naar een bestand met de naam index.html. U kunt ook de HTML try-it-editor gebruiken.

    
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <meta name="description" content="Contoso Web Chat Assistant" />
        <title>Contoso Sample Web Chat Test</title>
        <script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>
        <script>
          let webChatInstance = null;
          let directLineUrl = null;
    
          // Replace with your token endpoint
          const tokenEndpoint = "<YOUR TOKEN ENDPOINT>";
          const styleOptions = {
            "accent": "#0078D4",
            "autoScrollSnapOnPage": true,
            "autoScrollSnapOnPageOffset": 0,
            "avatarBorderRadius": "7%",
            "avatarSize": 31,
            "backgroundColor": "#e8e9eb",
            "botAvatarBackgroundColor": "#ffffff00",
            "botAvatarImage": "https://powercatexternal.blob.core.windows.net/creatorkit/Assets/ChatbotLogoBlue.png",
            "botAvatarInitials": "B",
            "bubbleAttachmentMaxWidth": 480,
            "bubbleAttachmentMinWidth": 250,
            "bubbleBackground": "#f0eded",
            "bubbleBorderColor": "#f5f5f5",
            "bubbleBorderRadius": 41,
            "bubbleBorderStyle": "solid",
            "bubbleBorderWidth": 1,
            "bubbleFromUserBackground": "#ebefff",
            "bubbleFromUserBorderColor": "#f5f5f5",
            "bubbleFromUserBorderRadius": 41,
            "bubbleFromUserBorderStyle": "solid",
            "bubbleFromUserBorderWidth": 1,
            "bubbleFromUserNubOffset": 0,
            "bubbleFromUserNubSize": 0,
            "bubbleFromUserTextColor": "#242424",
            "bubbleImageHeight": 10,
            "bubbleImageMaxHeight": 240,
            "bubbleImageMinHeight": 240,
            "bubbleMessageMaxWidth": 480,
            "bubbleMessageMinWidth": 120,
            "bubbleMinHeight": 50,
            "bubbleNubOffset": 0,
            "bubbleTextColor": "#242424",
            "emojiSet": true,
            "fontSizeSmall": "70%",
            "hideUploadButton": false,
            "messageActivityWordBreak": "break-word",
            "monospaceFont": "Consolas",
            "paddingRegular": 10,
            "paddingWide": 10,
            "primaryFont": null,
            "sendBoxBackground": "#e8e9eb",
            "sendBoxBorderTop": "solid 1px #808080",
            "sendBoxButtonColor": "#0078d4",
            "sendBoxButtonColorOnHover": "#006cbe",
            "sendBoxButtonShadeBorderRadius": 40,
            "sendBoxButtonShadeColorOnHover": "",
            "sendBoxHeight": 60,
            "sendBoxPlaceholderColor": "#171616",
            "sendBoxTextColor": "#2e2d2d",
            "showAvatarInGroup": "status",
            "spinnerAnimationHeight": 16,
            "spinnerAnimationPadding": 12,
            "spinnerAnimationWidth": 16,
            "subtleColor": "#000000FF",
            "suggestedActionBackgroundColor": "#006FC4FF",
            "suggestedActionBackgroundColorOnHover": "#0078D4",
            "suggestedActionBorderColor": "",
            "suggestedActionBorderRadius": 10,
            "suggestedActionBorderWidth": 1,
            "suggestedActionLayout": "flow",
            "suggestedActionTextColor": "#FFFFFFFF",
            "typingAnimationBackgroundImage": "url('https://wpamelia.com/wp-content/uploads/2018/11/ezgif-2-6d0b072c3d3f.gif')",
            "typingAnimationDuration": 5000,
            "typingAnimationHeight": 20,
            "typingAnimationWidth": 64,
            "userAvatarBackgroundColor": "#222222",
            "userAvatarImage": "https://avatars.githubusercontent.com/u/8174072?v=4&size=64",
            "userAvatarInitials": "U"
          };
          const backgroundImage = "";
    
          document.addEventListener('DOMContentLoaded', () => {
            const root = document.documentElement;
            root.style.setProperty('--primary-color', createGradient(styleOptions.accent));
            root.style.setProperty('--header-textColor', styleOptions.suggestedActionTextColor);
    
            if (backgroundImage) {
              const webchatElement = document.getElementById('webchat');
              webchatElement.style.backgroundImage = `url(${backgroundImage})`;
              webchatElement.style.backgroundSize = 'cover';
              webchatElement.style.backgroundPosition = 'center';
              webchatElement.style.backgroundRepeat = 'no-repeat';
    
              const overlay = document.createElement('div');
              overlay.className = 'webchat-overlay';
              webchatElement.appendChild(overlay);
            }
          });
    
          function createGradient(baseColor) {
            const r = parseInt(baseColor.slice(1, 3), 16);
            const g = parseInt(baseColor.slice(3, 5), 16);
            const b = parseInt(baseColor.slice(5, 7), 16);
            const lighterColor = `#${Math.min(255, r + 30).toString(16).padStart(2, '0')}${Math.min(255, g + 30).toString(16).padStart(2, '0')}${Math.min(255, b + 30).toString(16).padStart(2, '0')}`;
            const darkerColor = `#${Math.max(0, r - 30).toString(16).padStart(2, '0')}${Math.max(0, g - 30).toString(16).padStart(2, '0')}${Math.max(0, b - 30).toString(16).padStart(2, '0')}`;
            return `linear-gradient(135deg, ${lighterColor}, ${baseColor}, ${darkerColor})`;
          }
    
          const environmentEndPoint = tokenEndpoint.slice(
            0,
            tokenEndpoint.indexOf("/powervirtualagents")
          );
          const apiVersion = tokenEndpoint
            .slice(tokenEndpoint.indexOf("api-version"))
            .split("=")[1];
          const regionalChannelSettingsURL = `${environmentEndPoint}/powervirtualagents/regionalchannelsettings?api-version=${apiVersion}`;
    
          function showChat() {
            const popup = document.getElementById("chatbot-popup");
            const openButton = document.getElementById("open-chat");
            popup.classList.add("visible");
            openButton.classList.add("hidden");
          }
    
          function hideChat() {
            const popup = document.getElementById("chatbot-popup");
            const openButton = document.getElementById("open-chat");
            popup.classList.remove("visible");
            openButton.classList.remove("hidden");
          }
    
          function createCustomStore() {
            return window.WebChat.createStore(
              {},
              ({ dispatch }) =>
                (next) =>
                (action) => {
                  if (action.type === "DIRECT_LINE/CONNECT_FULFILLED") {
                    dispatch({
                      type: "DIRECT_LINE/POST_ACTIVITY",
                      meta: { method: "keyboard" },
                      payload: {
                        activity: {
                          channelData: { postBack: true },
                          name: "startConversation",
                          type: "event",
                        },
                      },
                    });
                  }
                  return next(action);
                }
            );
          }
    
          async function restartConversation() {
            try {
              if (!directLineUrl) {
                console.error("DirectLine URL not initialized");
                return;
              }
    
              const response = await fetch(tokenEndpoint);
              const conversationInfo = await response.json();
    
              if (!conversationInfo.token) {
                throw new Error("Failed to get conversation token");
              }
    
              const newDirectLine = window.WebChat.createDirectLine({
                domain: `${directLineUrl}v3/directline`,
                token: conversationInfo.token,
              });
    
              const webchatElement = document.getElementById("webchat");
              webChatInstance = window.WebChat.renderWebChat(
                {
                  directLine: newDirectLine,
                  styleOptions,
                  store: createCustomStore(),
                },
                webchatElement
              );
            } catch (err) {
              console.error("Failed to restart conversation:", err);
            }
          }
    
          async function initializeChat() {
            try {
              const response = await fetch(regionalChannelSettingsURL);
              const data = await response.json();
              directLineUrl = data.channelUrlsById.directline;
    
              if (!directLineUrl) {
                throw new Error("Failed to get DirectLine URL");
              }
    
              const conversationResponse = await fetch(tokenEndpoint);
              const conversationInfo = await conversationResponse.json();
    
              if (!conversationInfo.token) {
                throw new Error("Failed to get conversation token");
              }
    
              const directLine = window.WebChat.createDirectLine({
                domain: `${directLineUrl}v3/directline`,
                token: conversationInfo.token,
              });
    
              webChatInstance = window.WebChat.renderWebChat(
                {
                  directLine,
                  styleOptions,
                  store: createCustomStore(),
                },
                document.getElementById("webchat")
              );
            } catch (err) {
              console.error("Failed to initialize chat:", err);
            }
          }
    
          initializeChat();
      </script>
      <style>
        :root {
          --primary-gradient: var(--primary-color);
          --chat-width: 450px;
          --chat-height: 520px;
          --header-height: 56px;
          --border-radius: 16px;
          --transition-speed: 0.3s;
        }
        * {
          margin: 0;
          padding: 0;
          box-sizing: border-box;
          font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
            Roboto, sans-serif;
        }
        body {
          min-height: 100vh;
          background-color: #f3f4f6;
        }
        #chatbot-popup {
          display: none;
          position: fixed;
          bottom: 32px;
          right: 32px;
          width: var(--chat-width);
          height: var(--chat-height);
          background: white;
          border-radius: var(--border-radius);
          box-shadow: 0 18px 40px -5px rgba(0, 0, 0, 0.2),
            0 15px 20px -5px rgba(0, 0, 0, 0.1);
          overflow: hidden;
          opacity: 0;
          transform-origin: bottom right;
          transform: scale(0.95);
          transition: all var(--transition-speed) ease-in-out;
          z-index: 999;
        }
        #chatbot-popup.visible {
          display: block;
          opacity: 1;
          transform: scale(1);
        }
        #chatbot-header {
          background: var(--primary-color);
          padding: 16px 20px;
          height: var(--header-height);
          display: flex;
          justify-content: space-between;
          align-items: center;
          color: var(--header-textColor);
        }
        .header-title {
          display: flex;
          align-items: center;
          gap: 12px;
          font-size: 16px;
          font-weight: 500;
        }
        .header-buttons {
          display: flex;
          gap: 12px;
          align-items: center;
        }
        .icon-button {
          background: none;
          border: none;
          color: var(--header-textColor);
          cursor: pointer;
          padding: 8px;
          border-radius: 8px;
          display: flex;
          align-items: center;
          justify-content: center;
          transition: all 0.2s ease;
        }
        .icon-button:hover {
          color: var(--header-textColor);
          background: rgba(255, 255, 255, 0.1);
        }
        .icon-button:focus {
          outline: 2px solid rgba(255, 255, 255, 0.5);
          outline-offset: 2px;
        }
        #webchat {
          height: calc(100% - var(--header-height));
          background-color: #f9fafb;
          position: relative;
        }
        .webchat-overlay {
          position: absolute;
          top: 0;
          left: 0;
          right: 0;
          bottom: 0;
          background: rgba(255, 255, 255, 0.85);
          pointer-events: none;
          z-index: 1;
        }
        #webchat > div {
          position: relative;
          z-index: 2;
        }
        #webchat .webchat__basic-transcript__content {
          white-space: pre-wrap !important;
          word-break: break-word !important;
        }
        #webchat .webchat__bubble__content {
          padding: 8px 12px !important;
        }
        #webchat .webchat__bubble {
          max-width: 85% !important;
          margin: 8px !important;
        }
        #webchat .webchat__basic-transcript__content ul,
        #webchat .webchat__basic-transcript__content ol,
        #webchat .webchat__bubble__content ul,
        #webchat .webchat__bubble__content ol {
          padding-left: 24px !important;
          margin: 8px 0 !important;
          list-style-position: outside !important;
        }
        #webchat .webchat__basic-transcript__content li,
        #webchat .webchat__bubble__content li {
          margin: 4px 0 !important;
          padding-left: 4px !important;
        }
        #open-chat {
          position: fixed;
          bottom: 32px;
          right: 32px;
          width: 64px;
          height: 64px;
          border-radius: 50%;
          background: var(--primary-gradient);
          border: none;
          cursor: pointer;
          display: flex;
          align-items: center;
          justify-content: center;
          box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
          transition: all var(--transition-speed) ease-in-out;
          z-index: 998;
        }
        #open-chat.hidden {
          opacity: 0;
          transform: scale(0.95) translateY(10px);
          pointer-events: none;
        }
        #open-chat:hover {
          transform: translateY(-4px);
          box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
        }
        #open-chat:focus {
          outline: 3px solid rgba(79, 70, 229, 0.5);
          outline-offset: 2px;
        }
        #open-chat svg {
          width: 28px;
          height: 28px;
          color: white;
          transition: transform 0.2s ease;
        }
        .main-content {
          max-width: 1200px;
          margin: 0 auto;
          padding: 48px 24px;
        }
        .main-content h1 {
          font-size: 36px;
          color: #111827;
          text-align: center;
        }
        .main-content p {
          font-size: 18px;
          color: #4b5563;
          line-height: 1.6;
          margin-bottom: 48px;
          text-align: center;
          max-width: 800px;
          margin-left: auto;
          margin-right: auto;
        }
        .content-grid {
          display: grid;
          grid-template-columns: repeat(2, 1fr);
          gap: 32px;
          margin-bottom: 32px;
        }
        .content-box {
          background: linear-gradient(135deg, #e6e6e6, #c4c4c4, #9f9f9f);
          padding: 32px;
          border-radius: 12px;
          box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1),
                      0 2px 4px -1px rgba(0, 0, 0, 0.06);
          min-height: 300px;
          display: flex;
          flex-direction: column;
          justify-content: center;
          align-items: center;
          text-align: center;
          position: relative;
          overflow: hidden;
        }
        .content-box::before {
          content: '';
          position: absolute;
          top: 0;
          left: 0;
          right: 0;
          height: 4px;
        }
        .content-box.featured {
          grid-column: span 2;
          min-height: 350px;
          background: linear-gradient(135deg, #e6e6e6, #c4c4c4, #9f9f9f);
          color: #000000;
        }
        .content-box h2 {
          font-size: 24px;
          margin-bottom: 16px;
          position: relative;
        }
        .content-box p {
          font-size: 16px;
          color: #6b7280;
          margin-bottom: 0;
        }
        .content-box.featured p {
          color: #000000;
        }
        @media (max-width: 768px) {
          .content-grid {
            grid-template-columns: 1fr;
          }
          .content-box.featured {
            grid-column: span 1;
          }
          .main-content {
            padding: 24px 16px;
          }
          .main-content h1 {
            font-size: 28px;
          }
          #chatbot-popup {
            width: 100%;
            height: 100%;
            bottom: 0;
            right: 0;
            border-radius: 0;
          }
        }
      </style>
    </head>
    <body>
      <div class="main-content">
        <h1>Header</h1>
        <p>Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat.</p>
        <div class="content-grid">
          <div class="content-box featured">
            <h2>Featured Content</h2>
            <p>Primary content area with custom styling and gradient background</p>
          </div>
          <div class="content-box">
            <h2>Section One</h2>
            <p>Content box with minimal design</p>
          </div>
          <div class="content-box">
            <h2>Section Two</h2>
            <p>Another content section with consistent styling</p>
          </div>
        </div>
      </div>
      <div id="chatbot-popup" role="complementary" aria-label="Chat Assistant">
        <div id="chatbot-header">
          <div class="header-title">
            <svg
              class="chat-icon"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
              aria-hidden="true"
            >
              <path
                d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"
              ></path>
            </svg>
            <span>Contoso Assistant</span>
          </div>
          <div class="header-buttons">
            <button
              class="icon-button"
              id="restart-button"
              onclick="restartConversation()"
              aria-label="Restart Conversation"
            >
              <svg
                width="20"
                height="20"
                viewBox="0 0 24 24"
                fill="none"
                stroke="currentColor"
                stroke-width="2"
                stroke-linecap="round"
                stroke-linejoin="round"
                aria-hidden="true"
              >
                <path
                  d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"
                ></path>
                <path d="M3 3v5h5"></path>
              </svg>
            </button>
            <button
              class="icon-button"
              id="close-button"
              onclick="hideChat()"
              aria-label="Close Chat"
            >
              <svg
                width="20"
                height="20"
                viewBox="0 0 24 24"
                fill="none"
                stroke="currentColor"
                stroke-width="2"
                stroke-linecap="round"
                stroke-linejoin="round"
                aria-hidden="true"
              >
                <line x1="18" y1="6" x2="6" y2="18"></line>
                <line x1="6" y1="6" x2="18" y2="18"></line>
              </svg>
            </button>
          </div>
        </div>
        <div id="webchat" role="main"></div>
      </div>
      <button
        id="open-chat"
        onclick="showChat()"
        aria-label="Open Chat Assistant"
      >
        <svg
          viewBox="0 0 24 24"
          fill="none"
          stroke="currentColor"
          stroke-width="2"
          stroke-linecap="round"
          stroke-linejoin="round"
          aria-hidden="true"
        >
          <path
            d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"
          ></path>
        </svg>
      </button>
    </body>
    </html>
    
    
  3. Haal het tokeneindpunt op.

  4. Vervang in index.html:

    const tokenEndpoint = "<YOUR TOKEN ENDPOINT>";
    

    met je tokeneindpunt.

  5. Open index.html in een moderne browser, zoals Microsoft Edge.

  6. Test de agent.

Als de agent niet reageert:

  • Zorg ervoor dat de agent is gepubliceerd.
  • Controleer de eindpuntwaarde van het token.
  • Bevestig dat het tokeneindpunt wordt weergegeven na de =, tussen dubbele aanhalingstekens ".

Haal het token-eindpunt voor uw agent op

Als u uw canvas wilt aanpassen, of dit nu het standaardcanvas is of een aangepast canvas waarmee u verbinding maakt, hebt u het tokeneindpunt voor uw agent nodig.

  1. Selecteer Kanalen in Instellingen.

  2. Selecteer E-mail.

  3. Selecteer naast Tokeneindpunt de optie Kopiëren.

Het agentpictogram, de achtergrondkleur en de naam aanpassen

Gebruik het styleOptions object om vooraf gedefinieerde stijlen te configureren.

Zie defaultStyleOptions.js voor meer informatie over wat u kunt aanpassen en koppelingen naar het bestand .

Het agentpictogram wijzigen

  1. Werk het index.html bestand bij met de volgende voorbeeldcode:

    const styleOptions = {
      "accent": "#00809d",
      "botAvatarBackgroundColor": "#FFFFFF",
      "botAvatarImage": "https://learn.microsoft.com/azure/bot-service/v4sdk/media/logo_bot.svg",
      "botAvatarInitials": "BT",
      "userAvatarImage": "https://avatars.githubusercontent.com/u/661465",
      "userAvatarInitials": "U"
    };
    
  2. Vervang beide avatarafbeeldingen door je bedrijfsafbeeldingen. Als je geen afbeeldings-URL hebt, gebruik dan een Base64-gecodeerde afbeeldingsstring in plaats daarvan.

De kleur van de achtergrond wijzigen

  1. Voeg index.html een backgroundColor element toe aan je styleOptions definitie:

    const styleOptions = {
      "backgroundColor": "lightgray",
      // ...
    };
    
  2. Verander backgroundColor naar welke kleur je maar wilt. Gebruik standaard CSS-kleurnamen, RGB-waarden of HEX.

De agentnaam wijzigen

  1. Werk de <h1> headertekst in het index.html bestand bij met de volgende code:

    <body>
      <div id="banner">
        <h1><img src="contoso-agent.png"> Contoso agent name</h1>
      </div>
      <!-- ... -->
    
  2. Wijzig de tekst in hoe u de agent wilt noemen. Je kunt ook een afbeelding invoegen, maar je moet het misschien opmaken zodat het binnen de kopsectie past.

Uw chatcanvas aanpassen en hosten (geavanceerd)

U kunt uw Copilot Studio-agent verbinden met een aangepast canvas dat u host als een zelfstandige web-app. Deze optie werkt het beste als je een aangepaste iFrame over meerdere webpagina's wilt inembeden.

Note

Het hosten van een aangepast canvas vereist softwareontwikkeling. Deze richtlijnen zijn bedoeld voor ervaren IT-professionals, zoals IT-beheerders of ontwikkelaars die een goed begrip hebben van ontwikkelhulpprogramma's, hulpprogramma's en geïntegreerde ontwikkelomgevingen (IDE's).

Begin met een van deze voorbeelden die speciaal zijn gebouwd om met Copilot Studio te werken:

  • Full bundle is een aangepast canvas waarmee alle inhoud met opmaak uit Copilot Studio kan worden weergegeven. Voorbeeld:

    Volledige bundel aangepast canvas.

  • Locatie en bestand uploaden is een aangepast canvas waarmee de locatie van een gebruiker kan worden opgeslagen en naar een Copilot Studio-agent kan worden verzonden. Voorbeeld:

    Aangepast canvas voor locatie- en bestandsupload.

U kunt ook andere sample Webchat canvassen van Bot Framework proberen.

Net als bij het standaardcanvas kun je het aangepaste canvas met styleSetOptions bewerken. Alle aanpasbare eigenschappen worden vermeld in defaultStyleOptions.js. Zie Webchat aanpassing voor meer informatie over wat u kunt aanpassen.

Ondersteuning voor het opzetten van een verbinding in een aangepast canvas

Wanneer een agent die gebruikmaakt van de standaard-harness een gebruikersverbinding nodig heeft, ontvangt het chatcanvas een verbindingsvereiste Adaptive Card. Je aangepaste canvas moet de Action.OpenUrlDialog actie van de kaart afhandelen. Zonder deze afhandeling opent het selecteren van Connect het venster van de verbinding met focus niet.

Open het verbindingsvenster

  1. Registreer Action.OpenUrlDialog in je Adaptieve kaarten-renderer en lees de url eigenschap ervan. Accepteer alleen een absolute http:// of https:// URL.
  2. Bepaal of de oorsprong van de bestemming betrouwbaar is voordat je deze opent. Vertrouw alleen op de oorsprong die jij controleert of die je beveiligingsteam heeft beoordeeld en op de allowlist heeft geplaatst.
  3. Open de URL direct vanuit de gebruikersselectie met window.open(url, "_blank", "popup"). Het openen van het venster via de gebruikersactie verkleint de kans dat de browser het blokkeert.
  4. Voor een vertrouwde doellocatie, in het windowFeatures argument van window.open, laat noopener en noreferrer weg zodat het verbindingsvenster een resultaat kan teruggeven aan window.opener. Voor elke andere bestemming gebruik noopener,noreferrer en accepteer geen retourbericht.
  5. Behoud de teruggegeven Window referentie en de activiteits-ID van de kaart waarvoor een verbinding is vereist. Als de popup wordt geblokkeerd, of als de gebruiker deze sluit zonder geldig resultaat, houd dan Doorgaan of een andere herstelactie beschikbaar. Interpreteer het sluiten van het venster niet als een succesvolle verbindingsopzet.

De Adaptieve kaarten JavaScript SDK implementeert Action.OpenUrlDialog standaard niet. Registreer de actie via SerializationContext.actionRegistry, of behandel de actie direct in een renderer die je beheert. Een Action.OpenUrl fallback kan de bestemming openen in clients die de dialoogactie niet ondersteunen, maar de fallback kan geen popup-resultaat teruggeven.

Important

Een verbindingsvenster met toegang tot window.opener kan navigeren of anderszins de chatpagina beïnvloeden. Bekijk de bestemming en de doorverwijzingen met je webbeveiligingsteam. Sta niet toe dat een vertrouwde bestemming doorstuurt naar een niet-vertrouwde site terwijl je openertoegang behoudt.

Als je Bot Framework Webchat insluit, opent de Action.OpenUrlDialog-afhandeling het verbindingsvenster. Vensters van dezelfde oorsprong zijn standaard vertrouwd. Voor een beoordeelde cross-origin bestemming, stel styleOptions.callURLActionTrustedOrigin in op de exact toegestane oorsprong. Gebruik komma’s om meerdere oorsprongen te scheiden. Je kunt ook callURLActionPopupWindowWidthcallURLActionPopupWindowHeight instellen. Voeg geen bron toe die je niet hebt beoordeeld.

Doorgaan na het instellen van de verbinding (preview)

[Deze sectie maakt deel uit van de voorlopige documentatie en kan nog veranderen.]

Important

Dit artikel bevat Microsoft Copilot Studio preview-documentatie en kan worden gewijzigd.

Preview-functies zijn niet bedoeld voor productiegebruik en bieden mogelijk beperkte functionaliteit. Deze functies zijn beschikbaar voor een officiële release zodat u vroeg toegang kunt krijgen en feedback kunt geven.

Als u een productieklare agent bouwt, raadpleegt u Microsoft Copilot Studio Overview.

Het vertrouwde verbindingsvenster kan een voltooiingsresultaat naar de chatpagina sturen met window.opener.postMessage. Gebruik de exacte oorsprong van de chatpagina als doeloorsprong, niet *.

In de chatpagina:

  1. Als window.opennull retourneerde, accepteer dan geen bericht voor die poging. Anders accepteer een bericht alleen wanneer event.source overeenkomt met de behouden pop-upreferentie en event.origin overeenkomt met de verwachte oorsprong.

  2. Valideer dat de berichtgegevens type: "postback" en een waarde bevatten in de vorm die je agent of runtime verwacht.

    Het volgende voorbeeld stuurt een bericht met de tekst "hello-world" naar de agent. Het is niet zichtbaar in de chatinterface.

    { "type": "postback", "value": { hello: "World!" } }
    

    Het volgende voorbeeld stuurt een bericht met JSON { hello: "World!" } naar de agent.

    { "type": "postback", "value": { hello: "World!" } }
    
  3. Stuur de geaccepteerde waarde via het Bot Framework postback-mechanisme. Gebruik de behouden activiteits-ID als replyToId; accepteer geen antwoordactiviteits-ID uit de pop-up.

  4. Accepteer maximaal één resultaat per pop-up. Verwijder de event listener en wis de timer nadat je een resultaat hebt geaccepteerd, een verkeerd gevormd bericht van de vertrouwde pop-up hebt afgewezen, hebt gedetecteerd dat de pop-up is gesloten, of de tijdslimiet is bereikt. Webchat hanteert een limiet van vijf minuten.

  5. Coördineer met de agent of runtime om de postback te correleren met de oorspronkelijke interactie waarvoor een verbinding vereist was en hervat die gespreksstap precies één keer.

Browserberichten worden naar beste vermogen bezorgd. Popupblokkers, navigatie, cross-origin openerbeleid of een gesloten venster kunnen automatische voortzetting voorkomen. Houd Doorgaan of een ander herstelpad beschikbaar, en interpreteer een ontbrekend bericht niet als succes.

Uw aangepaste canvas implementeren

Als u uw aangepaste canvas wilt hosten, implementeert u alle bestanden in een web-app.