本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 為託管於 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`  | Boolean  | 一個標誌，用於啟用/禁用自動啟動小工具，而無需使用者按一下頁面加載。 | 未定義 | 
|  `alwaysHideWidgetButton`  | Boolean  | 用於啟用/禁用渲染小工具圖標按鈕的標誌 (除非有正在進行的聊天會話)。 | 未定義 | 
|  `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
   ```