当管理员在管理中心配置消息传送Web Widget ，且开发者将其添加到您的网站后，你们可以合作进一步自定义小组件的行为和体验。本指南概述了消息传送Web Widget的功能，并包含配方。有关实施详细信息和其他代码示例，请参阅我们的开发者文档中的 Web Widget。

已验证人工智能概要 ◀▼

自定义消息传送Web Widget ，以增强客户在您的网站上的互动。配置小组件语言、多对话和颜色主题等选项。控制小组件的可见度、位置和嵌入模式，以实现无缝整合。与开发者协作，使用 JavaScript API 实施更改，确保小组件满足您的特定需求，并改善不同页面和设备的用户体验。

当管理员在管理中心配置消息传送Web Widget ，且开发者将其添加到您的网站后，你们可以合作进一步自定义小组件的行为和体验。本指南概述了消息传送Web Widget的功能，并包含配方。有关实施详细信息和更多代码示例，请参阅我们开发者文档中的Web Widget 。

注意：本文章适用于使用消息传送 Web Widget 的帐户。如果您使用的是Web Widget（经典），请参阅Web Widget（经典）的高级自定义。

本文章包含以下主题：

  • 规划自定义消息传送Web Widget
  • 打开和关闭小组件
  • 以不同的语言显示小组件
  • 配置多对话
  • 重新定位启动器
  • 自定义小组件元素的颜色
  • 更改小组件中的可见顺序
  • 以嵌入模式显示小组件

规划自定义消息传送Web Widget

大多数 Zendesk 管理员都不是 Web 开发者，他们会配合开发者来实现消息传送Web Widget 的自定义。通常，管理员在管理中心配置消息传送设置，而开发者则使用消息传送Web Widget JavaScript API 更新网站代码以控制小组件行为。例如，API 可能会更改小组件的显示或打开时间。

即使开发者负责实施，管理员仍然发挥着重要作用，他们需要了解什么是可能的，并清楚地传达所需的体验。

自定义消息传送Web Widget通常涉及以下步骤：

  1. 查看此指南以了解哪些自定义选项可用。
  2. 与利益相关者会面，明确小组件体验的要求。例如，它应出现的时间、位置、是否使用自定义启动器，以及是否对用户进行身份验证。
  3. 创建所需更改的特定列表，并包含指向开发者可引用的任何相关开发者文档的链接。
  4. 让开发者通过更新网站的 HTML 和 JavaScript（以及用于定位启动器或设置任意自定义启动器按钮样式的 CSS）来实施更改，然后在关键页面和设备中测试体验。消息传送Web Widget在已添加到页面的 iFrame 内呈现，因此网站 CSS 可帮助定位，但无法设置小组件 UI 本身的样式。
注意：本文章包含几个 JavaScript 示例。将它们放在消息传送Web Widget代码之后，以便zE可用。 
<!-- Messaging Web Widget -->
<script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=YOUR_KEY"></script>

<!-- After the Web Widget code -->
<script>
  zE("messenger:set", "locale", "es");
</script>
如果您的网站在后台加载小组件（例如，在初始呈现后加载脚本的单页面应用），请确保在调用zE(...).

打开和关闭小组件

您可以控制消息传送窗口和启动器的可用和打开时间。如果您希望启动器仅在某些页面上可见，或者如果您想打开消息传送以响应用户操作（例如单击“帮助”按钮），此功能非常有用。启动器是一个小按钮（通常位于底角），用户单击该按钮开始发送消息。消息传送窗口是用户单击启动器后打开的展开的在线交谈界面。可用的 API 属性：
  • show 和hide控制启动器是否可见。
  • open 和close控制是否展开消息传送窗口。

隐藏启动器不会阻止您使用 打开消息传送窗口zE("messenger", "open").

控制启动器的可见度：
zE("messenger", "show"); // show launcher
zE("messenger", "hide"); // hide launcher
控制消息传送窗口状态：
zE("messenger", "open");  // open messaging window
zE("messenger", "close"); // close messaging window
显示启动器并打开消息传送窗口的自定义“帮助”按钮示例：
<button id="help-button" type="button">Help</button>
<script>
  document.getElementById("help-button").onclick = function () {
    zE("messenger", "show"); // ensure launcher is available
    zE("messenger", "open"); // open messaging window
  };
</script>

有关更多信息，请参阅显示消息传送Web Widget 。

以不同的语言显示小组件

消息传送Web Widget默认使用终端用户的浏览器语言。要覆盖此行为（例如，匹配您网站上的语言选择器），请将此代码放在紧跟在Web Widget嵌入脚本之后的运行时设置区域设置。如果您的网站以异步方式加载小组件（例如，在单页面应用程序中），请尽快运行zE可用，并且在您调用其他消息传送Web Widget命令之前。

<!-- Messaging Web Widget snippet -->
<script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=YOUR_KEY"></script>

<!-- Immediately after the snippet -->
<script>
  zE("messenger:set", "locale", "es");
</script>

有关受支持的区域设置和区域设置代码的列表，请参阅https://support.zendesk.com/api/v2/locales/public.json 。有关设置区域设置的更多信息，请参阅设置区域设置。

配置多对话

多方对话允许终端用户同时与您的组织进行多个活跃的对话（例如，不同的问题使用单独的讨论串）。要使用多对话，Zendesk 管理员必须启用它，并且您的帐户必须可访问Sunshine Conversations。有关信息，请参阅配置多对话。

如果您使用身份验证，请在显示启动器之前对用户进行身份验证。延迟身份验证可能导致匿名对话，并使用户难以访问以前的对话。例如：

zE("messenger", "hide");

zE("messenger", "loginUser", function (callback) {
  callback("new-jwt-for-user");
}, function (error) {
  if (error) return;
  zE("messenger", "show");
});

如果您可访问Sunshine ConversationsUpdateConversation端点，您可以为每个对话设置一个自定义标题和头像。更新不会立即反映在用户当前的消息传送屏幕中；它们将在用户下次重新加载消息传送 UI 时显示。

{
  "displayName": "My conversation",
  "iconUrl": "https://www.someplace.com/image.jpg"
}

用户可以使用对话列表屏幕在讨论串之间切换。如果您想显示单个对话界面， Sunshine Conversations支持canUserSeeConversationList设置以隐藏对话列表并仅显示最近更新的对话。

{
  "canUserSeeConversationList": false
}

重新定位启动器

消息传送Web Widget启动器默认显示在浏览器的右下角。要移动启动器，请使用以下方法之一：

  • CSS 定位（推荐用于简单移动）：通过针对小组件元素（通常是 iFrame）并更新left，right ，和bottom偏移量。使用浏览器 DevTools 检查小组件的 iFrame 和容器，并根据需要调整选择器。
  • 自定义启动器按钮（建议用于完全控制）：隐藏默认启动器，将您自己的“帮助”按钮放在布局中的任意位置，然后以编程方式打开小组件。

例如：使用 CSS 移动默认启动器

此示例使用 CSS 将默认启动器移动到左下角。
/* Move the Zendesk messaging Web Widget launcher to the bottom left */
/* Use your browser's DevTools to find the widget iframe and adjust the selector as needed */
iframe[title*="Zendesk"],
iframe[aria-label*="Zendesk"] {
  right: auto !important;
  left: 24px !important;
  bottom: 24px !important;
}
注意：消息传送Web Widget可能会向页面添加多个 iFrame。例如，启动器和对话窗口。如果您的 CSS 影响的不仅仅是启动器，请将选择器缩小到您要重新定位的特定 iframe 或容器。

例如：隐藏默认启动器并使用自定义“帮助”按钮

此示例说明如何使用自己的“帮助”按钮作为消息传送的唯一入口点。在管理中心配置自定义启动器，这样就不会显示默认启动器。在您的网站代码中，调用zE("messenger","hide")以确保默认启动器保持隐藏状态。如果您使用的是已通过身份验证的消息传送 (JWT)，请在调用之前对用户进行身份验证open().

zE("messenger","hide")

document.getElementById("help-button").onclick = function () {
  zE("messenger", "open");
};

例如：使用自定义“帮助”按钮并使默认启动器可用

此示例说明如何使用“帮助”按钮打开消息传送，同时在身份验证成功后仍显示默认启动器（例如，使用户稍后可以重新打开消息传送，而无需返回到“帮助”按钮）。如果身份验证失败，“帮助”按钮可匿名打开小组件。

zE("messenger", "hide");

let authSucceeded = false;

zE("messenger", "loginUser", function (callback) {
  // Fetch or provide a JWT for the signed-in user
  callback("new-jwt-for-user");
}, function (error) {
  if (error) {
    // Auth failed — user can still open messaging anonymously via the Help button
    return;
  }
  authSucceeded = true;
  zE("messenger", "show"); // show launcher after successful auth
});

document.getElementById("help-button").onclick = function () {
  // If auth didn't succeed (or hasn't completed yet), open anonymously
  if (!authSucceeded) {
    zE("messenger", "show");
  }
  zE("messenger", "open");
};

自定义小组件元素的颜色

您可以从管理中心配置消息传送Web Widget的总体颜色方案，包括启动器样式和品牌颜色。请参阅配置Web Widget的名称和外观。

如果您需要对各个 UI 元素进行更多控制，可以使用 JavaScript 在运行时自定义小组件的颜色。消息传送Web Widget自定义 API 可让您通过调用设置特定的主题颜色（例如启动器和标头颜色、终端用户和专员消息气泡颜色、操作按钮颜色以及背景颜色）
zE("messenger:set", "customization", { theme: ... })

这些基于 JavaScript 的覆盖：

  • 小组件加载后立即应用
  • 仅应用于运行脚本的页面
  • 当脚本被移除或用户访问没有脚本的页面时，恢复为管理中心颜色
有关更多信息，请参阅自定义Web Widget颜色。以下是使用 JavaScript 更新主题颜色的示例：
zE("messenger:set", "customization", {
  theme: {
    primary: "#0B5FFF",
    onPrimary: "#FFFFFF",
    message: "#F1F8FF",
    onMessage: "#003366",
    action: "#0B5FFF",
    onAction: "#FFFFFF"
  }
});
的theme对象支持的属性例如：
  • primary 和onPrimary用于启动器和关键 UI 元素
  • message 和onMessage用于终端用户的气泡图
  • businessMessage 和onBusinessMessage适用于专员和智能机器人的气泡图
  • action 和onAction用于操作按钮
  • background 和onBackground用于小组件的背景以及默认文本和图标颜色

更改小组件中的可见顺序

消息传送Web Widget支持zIndex应用于小组件的 iFrame 的设置，允许您控制启动器和小组件 UI 是显示在您页面上其他固定元素（例如 Cookie 横幅、置顶页首或浮动按钮）的上方还是下方。增加值会使小组件前进；增加该值会使小组件前进。减小该值将小组件推到其他元素的后面。

// Set the z-index for the messaging Web Widget iframes (default is typically 999999)
zE("messenger:set", "zIndex", 1000000);

有关更多信息，请参阅我们开发者文档中的设置 zIndex 。

以嵌入模式显示小组件

在嵌入模式下，您可以在页面中创建一个容器元素，并将消息传送Web Widget呈现到该容器中。通常会禁用浮动启动器，以便仅显示嵌入体验。当您希望消息传送显示在页面布局内（例如，在专门的“联系支持”页面上），而不是角落里的浮动启动器时，此功能很有用。这有助于避免与其他固定 UI 元素重叠，并使您可以更好地控制消息传送的显示位置。

通过设置禁用自动呈现window.zEMessenger.autorender = false在加载小组件代码段之前。

<script>
  window.zEMessenger = {
    autorender: false
  };
</script>

然后拨打电话render加载代码段后。

<!-- Container where the embedded messaging Web Widget will render -->
<div id="embedded-messaging"></div>

<script>
  // Render the widget in embedded mode into the container
  zE("messenger:set", "render", {
    mode: "embedded",
    widget: {
      target: "#embedded-messaging"
    }
  });
</script>
在嵌入模式下，消息传送直接在您的目标元素（而不是浮动启动器）内呈现，因此它不使用相同的打开或关闭行为。确保容器可见，并有足够的空间（例如，设置min-height或放置在规定高度的布局区域中），否则嵌入体验可能会被剪裁或太小。例如：
#embedded-messaging { min-height: 520px; }

有关更多信息，请参阅Web Widget嵌入模式。

翻译免责声明：本文章使用自动翻译软件翻译，以便您了解基本内容。 我们已采取合理措施提供准确翻译，但不保证翻译准确性

如对翻译准确性有任何疑问，请以文章的英语版本为准。

由 Zendesk 提供技术支持