tock-vue-kit v0.3.9

Tock Vue Kit

A Vue 3 chat widget to easily embed Tock into web pages or web apps.

Demo

Try the Tock Vue Kit (and the Tock Vue Kit Editor) on the demo page

Prerequisites

Run a Tock Bot in API mode

Quick Start

Basic html page integration example

Include js and css files:

<script src="https://unpkg.com/vue@3.4/dist/vue.global.prod.js"></script>
<link
  rel="stylesheet"
  href="https://unpkg.com/tock-vue-kit@0.3.6/dist/style.css"
/>
<script
  crossorigin
  src="https://unpkg.com/tock-vue-kit@0.3.6/dist/tock-vue-kit.iife.js"
></script>

Display the chat widget in desired target:

<div id="chat-wrapper"></div>

<script>
  TockVueKit.renderChat(
    document.getElementById("chat-wrapper"),
    "<TOCK_BOT_API_URL>"
  );
</script>

Vue3 3.4.29 integration example

Install the dependency:

npm install tock-vue-kit

In the desired component:

<script setup lang="ts">
  import { onMounted, ref } from "vue";
  import "tock-vue-kit/dist/style.css";
  import { renderChat } from "tock-vue-kit";

  const chatTarget = ref<HTMLElement>();

  onMounted(() => {
    renderChat(chatTarget.value!, "<TOCK_BOT_API_URL>");
  });
</script>

<template>
  <div ref="chatTarget"></div>
</template>

<style scoped>
  /* Any scoped styling... */
</style>

<!-- Use unscoped styling to visualy customize the Tvk widget -->
<style>
  :root {
    --tvk_colors_brand-hue: 214;
    --tvk_colors_brand-lightness: 42%;
    --tvk_colors_brand-saturation: 40%;
    --tvk_colors_dark_neutral: white;
    --tvk_colors_dark_text1: white;
    --tvk_colors_dark_text2: white;
    --tvk_wrapper_height: calc(98vh - 6em);
  }
</style>

Angular 18.1.0 integration example

Install the dependency:

npm install tock-vue-kit

In the desired component:

import {
  Component,
  ElementRef,
  ViewChild,
  ViewEncapsulation,
} from "@angular/core";
import { renderChat } from "tock-vue-kit";
import "tock-vue-kit/dist/style.css";

@Component({
  selector: "app-my-component",
  standalone: true,
  template: `<div #chatTarget></div>`,
  styles: `
  :root {
    --tvk_colors_brand-hue: 214;
    --tvk_colors_brand-lightness: 42%;
    --tvk_colors_brand-saturation: 40%;
    --tvk_colors_light_background: hsl(var(--tvk_colors_brand-hue) 50% 90%);
    --tvk_colors_dark_neutral: white;
    --tvk_colors_dark_text1: white;
    --tvk_colors_dark_text2: white;
    --tvk_wrapper_height: calc(100vh - 5em);
    --tvk_wrapper_max-height: calc(100vh - 5em);
  }
  `,
  encapsulation: ViewEncapsulation.None,
})
export class MyComponentComponent {
  @ViewChild("chatTarget") chatTarget!: ElementRef<HTMLDivElement>;

  ngAfterViewInit() {
    renderChat(this.chatTarget.nativeElement, "<TOCK_BOT_API_URL>");
  }
}

React 18.3.1 integration example

Install the dependency:

npm install tock-vue-kit

In a css file, define your visual customizations of the widget (styles.css by example):

:root {
  --tvk_colors_brand-hue: 214;
  --tvk_colors_brand-lightness: 42%;
  --tvk_colors_brand-saturation: 40%;
  --tvk_colors_light_background: hsl(var(--tvk_colors_brand-hue) 50% 90%);
  --tvk_colors_dark_neutral: white;
  --tvk_colors_dark_text1: white;
  --tvk_colors_dark_text2: white;
  --tvk_wrapper_height: calc(100vh - 5em);
  --tvk_wrapper_max-height: calc(100vh - 5em);
}

Finally in the desired component:

import { useRef, useEffect } from "react";
import { renderChat } from "tock-vue-kit";
import "tock-vue-kit/dist/style.css";
import "./styles.css";

function App() {
  const chatTarget = useRef(null);

  useEffect(() => {
    renderChat(chatTarget.current, "<TOCK_BOT_API_URL>");
  });

  return <div ref={chatTarget}></div>;
}

export default App;

Svelte 4.2.7 integration example

Install the dependency:

npm install tock-vue-kit

In the desired component:

<style>
  :root {
    --tvk_colors_brand-hue: 214;
    --tvk_colors_brand-lightness: 42%;
    --tvk_colors_brand-saturation: 40%;
    --tvk_colors_light_background: hsl(var(--tvk_colors_brand-hue) 50% 90%);
    --tvk_colors_dark_neutral: white;
    --tvk_colors_dark_text1: white;
    --tvk_colors_dark_text2: white;
    --tvk_wrapper_height: calc(98vh - 6em);
  }
</style>

<script>
  import { onMount } from "svelte";
  import { renderChat } from "tock-vue-kit";
  import "tock-vue-kit/dist/style.css";

  /** @type {HTMLDivElement} */
  let chatTarget;

  onMount(() => {
    renderChat(chatTarget, "<TOCK_BOT_API_URL>");
  });
</script>

<div bind:this="{chatTarget}"></div>

Render method arguments

TockVueKit.renderChat(element,tockBotApiUrl,customizationOptions)

element

The first argument of TockVueKit.renderChat method is the element where to render the widget. The element must be present in the document and provided as a HTMLElement reference.

tockBotApiUrl

The second argument is the url of the Tock instance to communicate with. This can be found in Tock Studio in Settings > Configurations, Relative REST path field (add the hosting domain of the Tock instance before the given path).

customizationOptions

The third argument hosts the widget's customization options. See below.

Customization options

Customization options are functional options of the widget. For visual widget customization, see Visual customization below. Customization options are provided in the form of an object that can contain the following optional attributes:

• LocalStorage;
• Initialization;
• Preferences;
• Wording;

Tock Vue Kit Editor offers an easy way to define customization options (See demo page, click Editor switch then see Preferences and Wording tabs)

LocalStorage

Options relating to the persistence in localStorage of messages exchanged by the user with the Tock instance :

Example :

TockVueKit.renderChat(
  document.getElementById("<TARGET_ELEMENT_ID>"),
  "<TOCK_BOT_API_URL>",
  {
    localStorage : {
      enabled : true,
      prefix : 'myprefix',
      maxNumberMessages : 15
    }
  }
);

Initialization

Example :

TockVueKit.renderChat(
  document.getElementById("<TARGET_ELEMENT_ID>"),
  "<TOCK_BOT_API_URL>",
  {
    "initialization": {
      "extraHeaders": {
        "my-header-name": "My header value",
        "other-header-name": "other header value"
      },
      "welcomeMessage": "Hi, how can i help you today ?"
    }
  }
)

Preferences

Messages

Message

Header

Avatar

Label

FootNotes

Footnotes can optionally be added to Rag messages.

QuestionBar

clearHistory

submit

ImageDef

Option object for providing images references.

Example :

TockVueKit.renderChat(
  document.getElementById("<TARGET_ELEMENT_ID>"),
  "<TOCK_BOT_API_URL>",
  {
    "preferences": {
      "messages": {
        "hideIfNoMessages": false,
        "message": {
          "header": {
            "avatar": {
              "userImage": {
                "src": "https://my-url.com/my-file.png",
                "width": "1em",
                "height": "1em"
              }
            },
            "label": {
              "display": false
            }
          }
        },
        "footNotes": {
          "requireSourcesContent": true,
          "clampSourceContentNbLines": "4"
        }
      },
      "questionBar": {
        "submit": {
          "icon": "bi bi-arrow-right-circle-fill"
        }
      }
    }
  }
)

Wording

The Wording customization option lets you redefine all or part of the text displayed by the widget.

Messages

Message

Header

Footnotes

QuestionBar

Input

Example :

TockVueKit.renderChat(
  document.getElementById("<TARGET_ELEMENT_ID>"),
  "<TOCK_BOT_API_URL>",
  {
    "wording": {
      "messages": {
        "message": {
          "header": {
            "labelUser": "Vous"
          },
          "footnotes": {
            "sources": "Sources :",
            "showMoreLink": "> Voir plus"
          }
        }
      },
      "questionBar": {
        "clearHistoryAriaLabel": "Effacer la discussion et l'historique",
        "input": {
          "placeholder": "Posez moi une question..."
        },
        "submitAriaLabel": "Bouton d'envoi"
      },
      "connectionErrorMessage": "Une erreur est survenue. Merci de réessayer dans quelques instants."
    }
  }
)

Visual customization

Most of the css rules that shape the widget are defined by css variables.

Each of these variables has a default value, which you are free to redefine according to your needs. Use your DevTools to identify the variables to overload or take a look at the Tock Vue Kit Editor via its demo page. The css variables are prefixed with the string “--tvk” so as not to unintentionally impact the page hosting the widget.

Tock Vue Kit Editor offers an easy way to define and export css variables customization (See demo page, click Editor switch then see Styling and Output tabs)

You can redefine the desired css variables in a number of ways:

Visual customization in source

Redefine desired css variables in the source of the page hosting the widget, anywhere after inclusion of the css file.

Example :

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>My Website</title>
    <script src="https://unpkg.com/vue@3.4"></script>
    <link href="node_modules/tock-vue-kit/dist/style.css" rel="stylesheet" />
    <script src="node_modules/tock-vue-kit/dist/tock-vue-kit.umd.cjs"></script>
    <style>
      :root {
        --tvk_colors_brand-hue: 214;
        --tvk_colors_brand-lightness: 42%;
        --tvk_colors_brand-saturation: 40%;
        --tvk_colors_dark_neutral: white;
        --tvk_colors_dark_text1: white;
        --tvk_colors_dark_text2: white;
        --tvk_wrapper_height: calc(98vh - 6em);
      }
    </style>
  </head>
  <body>
    <main>
      <h1>Welcome to My Website</h1>
      <div id="chat-wrapper"></div>
    </main>

    <script>
      TockVueKit.renderChat(
        document.getElementById("chat-wrapper"),
        "<TOCK_BOT_API_URL>"
      );
    </script>
  </body>
</html>

Visual customization in a separate css file

Create a separate css file where you redefine css variables and include this file in source, after inclusion of main css file.

Example :

Main html page

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>My Website</title>
    <script src="https://unpkg.com/vue@3.4"></script>
    <link href="node_modules/tock-vue-kit/dist/style.css" rel="stylesheet" />
    <script src="node_modules/tock-vue-kit/dist/tock-vue-kit.umd.cjs"></script>
    <link href="my-visual-customization.css" rel="stylesheet" />
  </head>
  <body>
    <main>
      <h1>Welcome to My Website</h1>
      <div id="chat-wrapper"></div>
    </main>

    <script>
      TockVueKit.renderChat(
        document.getElementById("chat-wrapper"),
        "<TOCK_BOT_API_URL>"
      );
    </script>
  </body>
</html>

Separate customization file (my-visual-customization.css in this example)

:root {
  --tvk_colors_brand-hue: 214;
  --tvk_colors_brand-lightness: 42%;
  --tvk_colors_brand-saturation: 40%;
  --tvk_colors_dark_neutral: white;
  --tvk_colors_dark_text1: white;
  --tvk_colors_dark_text2: white;
  --tvk_wrapper_height: calc(98vh - 6em);
}

Visual customization with javascript

If necessary, you can inject css variable overloads with javascript at runtime.

Example :

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>My Website</title>
    <script src="https://unpkg.com/vue@3.4"></script>
    <link href="node_modules/tock-vue-kit/dist/style.css" rel="stylesheet" />
    <script src="node_modules/tock-vue-kit/dist/tock-vue-kit.umd.cjs"></script>
  </head>
  <body>
    <main>
      <h1>Welcome to My Website</h1>
      <div id="chat-wrapper"></div>
    </main>

    <script>
      TockVueKit.renderChat(
        document.getElementById("chat-wrapper"),
        "<TOCK_BOT_API_URL>"
      );

      const styling = {
        "--tvk_colors_brand-hue": "214",
        "--tvk_colors_brand-lightness": "42%",
        "--tvk_colors_brand-saturation": "40%",
        "--tvk_colors_dark_background":
          "hsl(var(--tvk_colors_brand-hue) 50% 20%)",
        "--tvk_colors_dark_neutral": "white",
        "--tvk_colors_dark_text1": "white",
        "--tvk_colors_dark_text2": "white",
        "--tvk_colors_light_background":
          "hsl(var(--tvk_colors_brand-hue) 50% 90%)",
        "--tvk_wrapper_height": "calc(98vh - 6em)",
      };

      let root = document.documentElement;
      Object.entries(styling).forEach((style) => {
        root.style.setProperty(style[0], style[1]);
      });
    </script>
  </body>
</html>

More advanced visual customization

If you need to modify the widget's appearance in greater depth, use your own version of the "dist/style.css" file, which you can then customize as you see fit.

About colors

The Tock Vue Kit supports light and dark modes out of the box. Based on the three HSL variables (--tvk_colors_brand-hue, --tvk_colors_brand-lightness and --tvk_colors_brand-saturation), two sets of color variables (light and dark) are defined. The variables in each of these two sets contain the discriminants light or dark in their names, enabling the colors for each mode to be defined easily and independently (--tvk_colors_light_text1 | --tvk_colors_dark_text1, --tvk_colors_light_surface1 | --tvk_colors_dark_surface1, etc.). These are automatically mapped to their non-discriminating equivalent (--tvk_colors_text1, --tvk_colors_surface1, etc.) according to the state of the “data-theme” (or “data-bs-theme”) html tag attribute. Wherever color variables are referenced, the non-discriminant versions are used. This makes it possible to switch seamlessly between light and dark modes. Take a look at the demo page of the Tock Vue Kit Editor to better understand this mechanism.