Service Desk Chat JS Integrations-Guide
Service Desk Chat (sdc/js) ist eine JavaScript-Bibliothek, welche die Chat-Funktionalität auf Ihrer Website und die Kommunikation zwischen Website-Nutzern und Agenten über einen dedizierten Relay-Server ermöglicht.
Funktionen
- init(initRequestOpts)
-
- Beschreibung: Initialisiert die SDC-Bibliothek mit Hilfe der Relay Server URL, Farbpaletten und der übergebenen Sprache.
- Parameter:
- initRequestOpts (InitChatRequest): Optionen zum Initialisieren der SDC-Bibliothek.
- Rückgabewert: (Promise<boolean>) Ein Promise, welches zu „true“ aufgelöst wird, wenn die Initialisierung erfolgreich ist, und zu „false“, wenn ein Fehler auftritt.
- openChatWindow(options)
-
- Beschreibung: Öffnet das Chat Fenster anhand der übergebenen Optionen. Bietet auch die Möglichkeit das Chat Fenster nach Minimierung wieder zu maximieren.
- Parameter:
- options (object): Beinhaltet die Informationen des Nutzers und ggf. die Ticket Nummer (optional).
- Rückgabewert: Promise<void>
- closeChatWindow()
-
- Beschreibung: Schließt das Chat Fenster und trennt die Verbindung zum Relay.
- Rückgabewert: Nichts
- logout()
-
- Beschreibung: Löscht alle gespeicherten Sitzungsdaten innerhalb der SDC-Bibliothek. Schließt das Chat Fenster und trennt die Verbindung zum Relay.
- Rückgabewert: Nichts
Events
Die nachfolgenden Events werden ohne weitere Daten ausgelöst.
- “ltg.sdc.OpenedChatWindow”: Dieses Event wird versendet, wenn das Chat Fenster geöffnet wurde und sichtbar ist.
- “ltg.sdc.MinimizeWindow”: Mit diesem Event wird verdeutlicht, dass das Fenster minimiert wurde. Bei Minimierung des Fensters wird die Verbindung zum Relay nicht unterbrochen.
- “ltg.sdc.CloseWindow”: Bei Schließung des Fensters wird dieses Event ausgelöst. Die Verbindung zum Relay wird bei Schließung des Fensters getrennt.
- “ltg.sdc.NewMessage”: Dieses Event wird durch einkommende Nachrichten ausgelöst und kann ggf. abgefangen werden.
Alle Events könnten wie folgt abgefangen werden.
1 2 3 4 5 | window.addEventListener( "{eventName}" , () => { // your logic }); |
InitChatRequest Objekt
Das initRequestOpts Objekt wird an die Funktion init(initRequestOpts) übergeben und initialisiert die SDC-Bibliothek.
- address (string): URL des Relay Servers.
- transportType (number | signalR.HttpTransportType): HTTP Transport Typ für die Hubverbindung. Nummer 1 ist für den Transport Typ WebSockets. Nummer 4 ist für LongPolling.
- headers (Headers): Optionale HTTP Header für die Hubverbindung. Die Header werden nur bei LongPolling erkannt und können bei WebSockets nicht genutzt werden.
- customPalettes (object): Farbpaletten zur Anpassung der Benutzeroberfläche. Sie können die Farbpaletten von Angular Material (Color – Style – Material Design) verwenden oder Ihre eigenen benutzerdefinierten Farbpaletten hinzufügen, wie im folgenden Beispiel.
- language (string): Sprache des Chats. (z.B. „en-GB“)
- keepAliveIntervalInMilliseconds (number): Dies ist das Zeitintervall, in dem der Client eine „Keep-Alive“-Nachricht an den Server sendet, um die Verbindung aktiv zu halten, auch wenn keine Daten ausgetauscht werden.
- serverTimeoutInMilliseconds (number): Dieses Intervall gibt an, wie lange der Client wartet, bevor er eine inaktive Server-Verbindung als abgebrochen betrachtet und sie schließt.
Beispiel:
1 2 3 4 5 6 7 8 9 | var initRequest = { transportType: 4, headers: headers, customPalettes: palettes, keepAliveIntervalInMilliseconds: 2000, serverTimeoutInMilliseconds: 10000 } const initialized = await ltgsdc.init(initRequest); |
Headers Objekt
Das headers Objekt ist ein Schlüssel-Wert-Paar.
Zum Beispiel:
1 2 3 4 5 | { "Custom-Header" : "test_header" } |
Options Objekt
Das options Objekt wird an die Funktion openChatWindow(options) übergeben und enthält verschiedene Eigenschaften, um Informationen zum Nutzer oder die Ticket Nummer an das Chat Fenster weiterzuleiten.
- firstName (string): Vorname des Nutzers.
- lastName (string): Nachname des Nutzers.
- emailAddress (string): Email Adresse des Nutzers.
- language (string): Spracheinstellung für den Chat (z.B. „en-GB“) (optional).
- ticketNumber (string): Ticket Nummer als Referenz zum Ticket im Matrix42 DWP System (optional).
Beispiel:
1 2 3 4 5 6 7 | var options = { firstName: "TEST" , lastName: "TEST" , emailAddress: "TEST@TEST.test" , language: "en-GB" , ticketNumber: "INC00058" }; |
Chat Button Implementation
Der im Guide dargestellte Chat-Button (#ltg-sdc-create-chat) gehört nicht zum Produkt der SDC-Bibliothek selbst. Er dient als Beispiel-HTML-Element zu Demonstrationszwecken. Sie müssen ihren eigenen Chat-Button oder ähnliches in ihre HTML-Struktur integrieren, um die Funktion ‚openChatWindow()‘ auszulösen.
Für eine effektive Integration sollten Sie ihren Chat-Button gemäß dem Design ihrer Website und den Benutzererfahrungspräferenzen anpassen und integrieren. Die bereitgestellte HTML-Struktur für den Chat-Button (#ltg-sdc-create-chat) sollte angepasst und mit der Funktion ‚openChatWindow(options)‘ verknüpft werden, um die Chat-Funktionalität zu initiieren, wenn der Nutzer daraufklickt.
Einfaches Beispiel
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 | < html > < head > < meta name = "viewport" content = "width=device-width, initial-scale=1.0" > < script src = "{relayServerUrl}/sdc/js" ></ script > </ head > < body > < p > TEST External Relay Website </ p > < button id = "ltg-sdc-create-chat" >Create Chat</ button > < button id = "ltg-sdc-close-chat" >Close Chat</ button > < button id = "ltg-sdc-logout" >Logout</ button > < script > document.addEventListener("DOMContentLoaded", async function () { var options = { firstName: "TEST", lastName: "TEST", emailAddress: "TEST@TEST.test", // language: "en-GB", // ticketNumber: "INC00058" }; var palettes = { isDark: false, primaryPalette: 'purple', accentPalette: 'indigo', warnPalette: 'red', backgroundPalette: 'grey' } var initRequest = { address: "http://localhost:5001", transportType: 1, customPalettes: palettes } const initialized = await ltgsdc.init(initRequest); console.log("initialized", initialized); document.getElementById("ltg-sdc-create-chat").addEventListener("click", () => { ltgsdc.openChatWindow(options); }); document.getElementById("ltg-sdc-close-chat").addEventListener("click", () => { ltgsdc.closeChatWindow(); }); document.getElementById("ltg-sdc-logout").addEventListener("click", () => { ltgsdc.logout(); }); }); </ script > </ body > </ html > |
Einfaches Beispiel mit benutzerdefinierten Farbpaletten
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 | < html > < head > < meta name = "viewport" content = "width=device-width, initial-scale=1.0" > < script src = "{relayServerUrl}/sdc/js" ></ script > < style > /* simple example with custom palettes and not many CSS changes */ .ltg-sdc-root .ltg-sdc-chat-message-system .ltg-sdc-chat-message { background-color: #717171 !important; color: #fff !important; } .ltg-sdc-root .ltg-sdc-chat-message-wrapper-them .ltg-sdc-chat-message { background-color: #1952AD !important; color: #fff !important; } </ style > </ head > < body > < p > TEST External Relay Website </ p > < button id = "ltg-sdc-create-chat" >Create Chat</ button > < button id = "ltg-sdc-close-chat" >Close Chat</ button > < button id = "ltg-sdc-logout" >Logout</ button > < script > document.addEventListener("DOMContentLoaded", async function () { var options = { firstName: "TEST", lastName: "TEST", emailAddress: "TEST@TEST.test", // language: "en-GB", // ticketNumber: "INC00058" }; // simple example with custom palettes var primaryPalette = { '50': 'e3eaf5', '100': 'bacbe6', '200': '8ca9d6', '300': '5e86c6', '400': '3c6cb9', '500': '1952ad', '600': '164ba6', '700': '12419c', '800': '0e3893', '900': '082883', 'A100': 'b2c2ff', 'A200': '7f99ff', 'A400': '4c71ff', 'A700': '325dff', 'contrastDefaultColor': 'light', 'contrastDarkColors': [ '50', '100', '200', '300', 'A100', 'A200' ], 'contrastLightColors': [ '400', '500', '600', '700', '800', '900', 'A400', 'A700' ] }; var accentPalette = { '50': '174b9e', '100': '174b9e', '200': '174b9e', '300': '174b9e', '400': '174b9e', '500': '174b9e', '600': '174b9e', '700': '174b9e', '800': '174b9e', '900': '174b9e', 'A100': '174b9e', 'A200': '174b9e', 'A400': '174b9e', 'A700': '174b9e', 'contrastDefaultColor': 'light', 'contrastDarkColors': [ '50', '100', '200', '300', '400', '500', '600', '700', '800', '900', 'A100', 'A200', 'A400', 'A700' ], 'contrastLightColors': [] }; var backgroundPalette = { '50': 'fdfdfd', '100': 'f9f9f9', '200': 'f5f5f5', '300': 'f1f1f1', '400': 'eeeeee', '500': 'ebebeb', '600': 'e9e9e9', '700': 'e5e5e5', '800': 'e2e2e2', '900': 'dddddd', 'A100': 'ffffff', 'A200': 'ffffff', 'A400': 'ffffff', 'A700': 'ffffff', 'contrastDefaultColor': 'light', 'contrastDarkColors': [ '50', '100', '200', '300', '400', '500', '600', '700', '800', '900', 'A100', 'A200', 'A400', 'A700' ], 'contrastLightColors': [] }; var palettes = { primaryPalette: primaryPalette, accentPalette: accentPalette, warnPalette: 'red', backgroundPalette: backgroundPalette } var initRequest = { address: "http://localhost:5001", transportType: 1, customPalettes: palettes } const initialized = await ltgsdc.init(initRequest); console.log("initialized", initialized); document.getElementById("ltg-sdc-create-chat").addEventListener("click", () => { ltgsdc.openChatWindow(options); }); document.getElementById("ltg-sdc-close-chat").addEventListener("click", () => { ltgsdc.closeChatWindow(); }); document.getElementById("ltg-sdc-logout").addEventListener("click", () => { ltgsdc.logout(); }); }); </ script > </ body > </ html > |
Komplexeres Beispiel mit benutzerdefinierten Farbpaletten
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 | < html > < head > < meta name = "viewport" content = "width=device-width, initial-scale=1.0" > < script src = "{relayServerUrl}/sdc/js" ></ script > < style > /* complex example with many CSS changes */ .ltg-sdc-root .ltg-sdc-relay-window { background-color: #EBEBEB !important; } .ltg-sdc-root .ltg-sdc-chat-footer { background-color: transparent !important; } .ltg-sdc-root .ltg-sdc-chat-footer svg { fill: #1952AD !important; } .ltg-sdc-root .ltg-sdc-chat-message-system .ltg-sdc-chat-message { background-color: #525252 !important; color: #fff !important; } .ltg-sdc-root .ltg-sdc-chat-message-wrapper-them .ltg-sdc-chat-message { background-color: #1952AD !important; color: #fff !important; } .ltg-sdc-root .ltg-sdc-chat-actions { background-color: #C4C4C4 !important; color: black !important; } .ltg-sdc-root .ltg-sdc-chat-actions-button svg { fill: black !important; } .ltg-sdc-root .ltg-sdc-close-wizard-header > md-content { background-color: transparent !important; } </ style > </ head > < body > < p > TEST External Relay Website </ p > < button id = "ltg-sdc-create-chat" >Create Chat</ button > < button id = "ltg-sdc-close-chat" >Close Chat</ button > < button id = "ltg-sdc-logout" >Logout</ button > < script > document.addEventListener("DOMContentLoaded", async function () { var options = { firstName: "TEST", lastName: "TEST", emailAddress: "TEST@TEST.test", // language: "en-GB", // ticketNumber: "INC00199" }; var primaryPalette = { '50': 'e3eaf5', '100': 'bacbe6', '200': '8ca9d6', '300': '5e86c6', '400': '3c6cb9', '500': '1952ad', '600': '164ba6', '700': '12419c', '800': '0e3893', '900': '082883', 'A100': 'b2c2ff', 'A200': '7f99ff', 'A400': '4c71ff', 'A700': '325dff', 'contrastDefaultColor': 'light', 'contrastDarkColors': [ '50', '100', '200', '300', 'A100', 'A200' ], 'contrastLightColors': [ '400', '500', '600', '700', '800', '900', 'A400', 'A700' ] }; var accentPalette = { '50': '174b9e', '100': '174b9e', '200': '174b9e', '300': '174b9e', '400': '174b9e', '500': '174b9e', '600': '174b9e', '700': '174b9e', '800': '174b9e', '900': '174b9e', 'A100': '174b9e', 'A200': '174b9e', 'A400': '174b9e', 'A700': '174b9e', 'contrastDefaultColor': 'light', 'contrastDarkColors': [ '50', '100', '200', '300', '400', '500', '600', '700', '800', '900', 'A100', 'A200', 'A400', 'A700' ], 'contrastLightColors': [] }; var backgroundPalette = { '50': 'fdfdfd', '100': 'f9f9f9', '200': 'f5f5f5', '300': 'f1f1f1', '400': 'eeeeee', '500': 'ebebeb', '600': 'e9e9e9', '700': 'e5e5e5', '800': 'e2e2e2', '900': 'dddddd', 'A100': 'ffffff', 'A200': 'ffffff', 'A400': 'ffffff', 'A700': 'ffffff', 'contrastDefaultColor': 'light', 'contrastDarkColors': [ '50', '100', '200', '300', '400', '500', '600', '700', '800', '900', 'A100', 'A200', 'A400', 'A700' ], 'contrastLightColors': [] }; var palettes = { primaryPalette: primaryPalette, accentPalette: accentPalette, warnPalette: 'red', backgroundPalette: backgroundPalette } var initRequest = { address: "http://localhost:5001", transportType: 1, customPalettes: palettes } const initialized = await ltgsdc.init(initRequest); console.log("initialized", initialized); document.getElementById("ltg-sdc-create-chat").addEventListener("click", () => { ltgsdc.openChatWindow(options); }); document.getElementById("ltg-sdc-close-chat").addEventListener("click", () => { ltgsdc.closeChatWindow(); }); document.getElementById("ltg-sdc-logout").addEventListener("click", () => { ltgsdc.logout(); }); }); </ script > </ body > </ html > |