本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 为托管在 Amazon Connect 的网站自定义小部件启动行为和按钮图标
<a name="customize-widget-launch"></a>

要进一步自定义网站显示和启动托管小部件图标的方式，您可以配置启动行为并隐藏默认图标。例如，您可以通过编程方式从网站上显示的**与我们聊天**按钮元素启动小部件。

**Topics**
+ [如何为小组件配置自定义启动行为](#config-widget-launch)
+ [支持的选项和限制](#launch-options-constraints)
+ [为自定义用例配置小组件启动](#launch-usage)
+ [启用跨选项卡的聊天会话持久化](#chat-persistence-across-tabs)

## 如何为小组件配置自定义启动行为
<a name="config-widget-launch"></a>

要传递自定义启动行为，请使用以下示例代码块并将其嵌入到小部件中。以下示例中显示的所有字段均为可选字段，可以任意组合使用。

```
amazon_connect('customLaunchBehavior', {
    skipIconButtonAndAutoLaunch: true,
    alwaysHideWidgetButton: true,
    programmaticLaunch: (function(launchCallback) {
        var launchWidgetBtn = document.getElementById('launch-widget-btn');
        if (launchWidgetBtn) {
            launchWidgetBtn.addEventListener('click', launchCallback);
            window.onunload = function() {
            launchWidgetBtn.removeEventListener('click', launchCallback);
            return;
            }
        }
    })
});
```

## 支持的选项和限制
<a name="launch-options-constraints"></a>

下表列出了支持的自定义启动行为选项。均为可选字段，可任意组合使用。


| 选项名称 | Type | 说明 | 默认 值 | 
| --- | --- | --- | --- | 
|  `skipIconButtonAndAutoLaunch`  | 布尔值  | 一个标志 enable/disable ，表示无需用户点击页面加载即可自动启动小组件。 | 未定义 | 
|  `alwaysHideWidgetButton`  | 布尔值  | 用于 enable/disable 渲染控件图标按钮的标志（除非有正在进行的聊天会话）。 | 未定义 | 
|  `programmaticLaunch`  | 函数  |  | 未定义 | 

## 为自定义用例配置小组件启动
<a name="launch-usage"></a>

### 自定义小组件启动按钮
<a name="custom-launch-button"></a>

以下示例显示了您需要在小部件中做出的更改，以便将编程启动配置为仅在用户选择网站上任意位置显示的自定义按钮元素时才打开。例如，他们可以选择名为**联系我们**或**与我们聊天**的按钮。或者，您可以隐藏默认 Amazon Connect 小部件图标，直到该小部件打开为止。

```
<button id="launch-widget-btn">Chat With Us</button>
```

```
<script type="text/javascript">
 (function(w, d, x, id){
    s=d.createElement("script");
    s.src="./amazon-connect-chat-interface-client.js"
    s.async=1;
    s.id=id;
    d.getElementsByTagName("head")[0].appendChild(s);
    w[x] =  w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };
  })(window, document, 'amazon_connect', 'asfd-asdf-asfd-asdf-asdf');
  amazon_connect('styles', { openChat: { color: '#000', backgroundColor: '#3498fe'}, closeChat: { color: '#fff', backgroundColor: '#123456'} });
  amazon_connect('snippetId', "QVFJREFsdafsdfsadfsdafasdfasdfsdafasdfz0=")
  amazon_connect('customLaunchBehavior', {
        skipIconButtonAndAutoLaunch: true,
        alwaysHideWidgetButton: true,
        programmaticLaunch: (function(launchCallback) {
            var launchWidgetBtn = document.getElementById('launch-widget-btn');
            if (launchWidgetBtn) {
                launchWidgetBtn.addEventListener('click', launchCallback);
                window.onunload = function() {
                launchWidgetBtn.removeEventListener('click', launchCallback);
                return;
                }
            }
        }),
    });
</script>
```

### 支持超链接
<a name="hyperlink-support"></a>

以下示例显示了您需要在小部件配置 `auto-launch` 中做出的更改，这样无需等待用户点击即可打开小部件。您可以部署到由网站托管的页面，创建可共享的超链接。

```
https://example.com/contact-us?autoLaunchMyWidget=true
```

```
<script type="text/javascript">
 (function(w, d, x, id){
    s=d.createElement("script");
    s.src="./amazon-connect-chat-interface-client.js"
    s.async=1;
    s.id=id;
    d.getElementsByTagName("head")[0].appendChild(s);
    w[x] =  w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };
  })(window, document, 'amazon_connect', 'asfd-asdf-asfd-asdf-asdf');
  amazon_connect('styles', { openChat: { color: '#000', backgroundColor: '#3498fe'}, closeChat: { color: '#fff', backgroundColor: '#123456'} });
  amazon_connect('snippetId', "QVFJREFsdafsdfsadfsdafasdfasdfsdafasdfz0=")
  amazon_connect('customLaunchBehavior', {
        skipIconButtonAndAutoLaunch: true
    });
</script>
```

### 点击按钮时加载小组件资产
<a name="load-assets"></a>

以下示例显示了您需要在小部件中做出的更改，以便在用户单击**与我们聊天**按钮时通过获取小部件的静态资产来加快网站页面的加载速度。通常，只有一小部分访问**联系我们**页面的客户会打开 Amazon Connect 小部件。尽管客户从未打开过小部件，该小部件也可能会通过从 CDN 获取文件来增加页面加载的延迟。

另一种解决方案是在单击按钮时不同步（或从不）运行代码片段。

```
<button id="launch-widget-btn">Chat With Us</button>
```

```
var buttonElem = document.getElementById('launch-widget-btn');

buttonElem.addEventListener('click', function() {
    (function(w, d, x, id){
        s=d.createElement("script");
        s.src="./amazon-connect-chat-interface-client.js"
        s.async=1;
        s.id=id;
        d.getElementsByTagName("head")[0].appendChild(s);
        w[x] =  w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };
    })(window, document, 'amazon_connect', 'asfd-asdf-asfd-asdf-asdf');
    amazon_connect('styles', { openChat: { color: '#000', backgroundColor: '#3498fe'}, closeChat: { color: '#fff', backgroundColor: '#123456'} });
    amazon_connect('snippetId', "QVFJREFsdafsdfsadfsdafasdfasdfsdafasdfz0=")
    amazon_connect('customLaunchBehavior', {
        skipIconButtonAndAutoLaunch: true
    });
});
```

### 在浏览器窗口中启动新聊天
<a name="new-chat-browser-window"></a>

以下示例显示了您需要在小部件中做出的更改，以启动一个新的浏览器窗口并在全屏模式下自动启动聊天。

```
<button id="openChatWindowButton">Launch a Chat</button>
```

```
<script> // Function to open a new browser window with specified URL and dimensions
    function openNewWindow() {
        var url = 'https://mycompany.com/support?autoLaunchChat=true';

        // Define the width and height
        var width = 300;
        var height = 540;

        // Calculate the left and top position to center the window
        var left = (window.innerWidth - width) / 2;
        var top = (window.innerHeight - height) / 2;

        // Open the new window with the specified URL, dimensions, and position
        var newWindow = window.open(url, '', 'width=${width}, height=${height}, left=${left}, top=${top}');
    }

    // Attach a click event listener to the button
    document.getElementById('openChatWindowButton').addEventListener('click', openNewWindow);
</script>
```

## 启用跨选项卡的聊天会话持久化
<a name="chat-persistence-across-tabs"></a>

默认情况下，如果用户在一个选项卡中有一个打开的聊天，然后打开一个新的选项卡并开始另一个聊天，则新聊天将开始，取代与现有聊天的连接。如果您希望用户连接在初始选项卡中启动的现有聊天，则可以启用跨选项卡的聊天会话持久化。

聊天会话被存储在浏览器上会话存储中的变量 `persistedChatSession` 内。首次初始化该小部件时，需要将此值复制到新选项卡的会话存储中。以下是操作说明。

要在用户导航到不同的子域时连接到同一个聊天会话，您可以设置 Cookie 的域属性。例如，您拥有两个子域：`domain1.example.com` 和 `domain2.example.com`。您可以添加属性 `domain=.example.com` 以便可以从所有子域访问该 Cookie。

1. 将以下代码复制到托管小部件代码段中其他 amazon\$1connect 函数旁边。这将使用 `registerCallback` 事件处理程序将 `persistedChatSession` 存储为 Cookie，以便可以在新选项卡中访问它。聊天结束时，它还会清理 Cookie。

   

   ```
   amazon_connect('registerCallback', {
   'CONNECTION_ESTABLISHED': (eventName, { chatDetails, data }) => {
    document.cookie = `activeChat=${sessionStorage.getItem("persistedChatSession")}; SameSite=None; Secure`;
   }, 
   'CHAT_ENDED': () => {
     document.cookie = "activeChat=; SameSite=None; Secure";
   }
   });
   ```

1. 检索 Cookie 值（如果存在），并在新选项卡中设置会话存储值。

   ```
   const cookie = document.cookie.split('; ').find(c => c.startsWith('activeChat='));
   if (cookie) {
     const activeChatValue = cookie.split('=')[1];
     sessionStorage.setItem('persistedChatSession', activeChatValue);
   }
   
   //Your hosted widget snippet should be on this page
   ```