Skip to content

How the giosg script works

Info

giosg script V2 has been enabled as a default for all customers signing up for giosg after Dec. 16th - 2021. If you are have been an existing customer and have not upgraded to giosg script v2, you can find the version one documentation here.

Info

If you are an existing customer and would like to upgrade to the more performant giosg script v2, you can contact us at support@giosg.com. V1/V2 differences are described here.

Let's assume that there is a giosg account for the organization "Example Ltd." They integrate Giosg script to their website example.com. This page describes how the Giosg script would work on the visitor's browser when they visit a web page on example.com.

Script tag

The Giosg script is integrated to a website by adding the HTML script snippet to the <head> tag of every HTML page on the website. Depending on the way the website is implemented, it is usually enough to add this script once to the base HTML layout.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<!-- giosg tag -->
<script>
  (function (w, t, f) {
    var s = "script",
      o = "_giosg",
      h = "https://service.giosg.com",
      e,
      n;
    e = t.createElement(s);
    e.async = 1;
    e.src = h + "/live2/" + f;
    w[o] =
      w[o] ||
      function () {
        (w[o]._e = w[o]._e || []).push(arguments);
      };
    w[o]._c = f;
    w[o]._h = h;
    n = t.getElementsByTagName(s)[0];
    n.parentNode.insertBefore(e, n);
  })(window, document, '826100fd-b473-49b0-bafd-d7332622bae8');
</script>
<!-- giosg tag -->

The script looks similar to every organization account, but each organization will have a different ID included in the script.

The actual script for the organization, with the correct ID, can be found at the Company script tag page after signing in to Giosg.

When the HTML page is loaded, the script tag is executed with the following effects:

  • A global JavaScript variable _giosg is created. This is a function that is used to execute JavaScript API commands. At this point, the _giosg function is very lightweight, including just the organization ID and a "queue" for API calls that will be executed once the Giosg script is loaded.
  • Another script tag is inserted to page DOM that loads a JavaScript file from https://service.giosg.com/live2/.... The script load is done asyncronously, meaning that loading this script will not block the website from loading its own assets.

Core loader component

The script loaded from https://service.giosg.com/live2/ will contain a core loader component for the Giosg client functionality.

About performance: The core loader script is served with a 24 hour cache expiration time, meaning that browsers will load this only on their first page load and then again after 24 hours. The script is minimized and compressed for the optimal loading.

This core loader script contains the following things:

  • Creation of a global variable giosg that acts as a namespace for the Giosg-related components and configuration.
  • A very short loader script, that will immediately perform an AJAX request for the dynamic configuration for the client, see the next section.

Loading client configuration

As soon as core loader component is loaded, it will make an AJAX request for the configuration from https://service.giosg.com/api/v5/orgs/<organizationId>/client-settings/?url=<currentUrl>.

Note that for security reasons, the script requires a correct Referer HTTP header. Otherwise it returns an error. This ensures that no other organization is able to add other organization's script tags to their website.

The request is asynchronous so it won't block the website from loading its own assets. The response will contain all the required information to set up the client script, including:

  • Configuration for the chat, e.g. button and chat window styling
  • Configuration for the Giosg Basket (shopping carts), if in use
  • Rules that can be used on the current page
  • Settings for the event tracking
  • Information about the visitor for the rule condition matching logic

Client script

While the client configuration is loaded, the client script is loaded in parellel.

The client script contains the actual logic that is executed in the example.com page environment. This includes:

  • The matching of rule conditions and performing their actions
  • Sending track events
  • Implementation of the JavaScript APIs
  • Managing of Giosg Basket (shopping carts)

The following features will be loaded in separate scripts only if needed.

  • Managing the the chat button
  • Managing the visual state of chat windows
  • Managing any custom elements
  • Injection of the client iframe (see the next section)

Client iframe

The client script will add an iframe element to the DOM.

The most important function of the iframe is to contain the chat conversation. The iframe will be served from the different origin than example.com. It will be always served from the https://service.giosg.com origin. This enables the following important features:

  • The chat conversation is protected: the code at example.com has a very limited access to its contents. This will, for example, protect from any malicious user from doing a cross-site scripting attack to example.com. Also, this also helps to protect the conversation in cases where other organizations are networked together, where visitors are chatting to other organization's websites.
  • Enables realtime communication. The iframe creates a WebSocket connection to the Giosg's real-time messaging service, hosted at messagerouter.giosg.com. This enables, for example, receiving chat messages in real time. The socket connection is done inside the iframe in order to avoid any cross-origin and browser-related issues.
  • Enables identifying the visitor across other websites owned by the same organization. This allows the visitor to continue chatting from one website to another, if that website contains the same Giosg script tag.

When the iframe is created, some information about the current page and the current environment (such as the page URL and the organization ID) is passed in the iframe URL. The HTML page loaded in the iframe will load the required script and stylesheets for the chat conversation logic.

V1/V2 differences

V2 script is much smaller/faster and has significantly less dependencies to third party js libraries!

V2 has the same technical browser requirements as V1, so for example Supported Browsers and CSP documentation is the same for both script versions.

New features only supported by V2:

Feature Description
Consent management V2 script has full support for consent management
Giosg Video Giosg Video functionality is only supported by V2
Interactions / CSS click condition Configuration added to the “show interaction” Rule-action.

Features deprecated from V2:

Feature Description
Lead Forms Should be replaced with Interactions
Pipeline This feature has been deprecated, please use the Visitor Variable API: https://docs.giosg.com/api_reference/giosg_live/giosg_js_api/#submit-visitor-variables
Basket Configuration with CSS selectors is deprecated
CSS and HTML chat window customization Fully customized chat windows are no longer supported. Instead brands can be used to easily customize chat windows.
Unused chat window entrance and exit animations Removed
Chat button customizations are limited to using an image or an interaction Custom button CSS selectors removed
jQuery library at window.jGiosg removed from V2 script jGiosg was Giosg version of the jQuery library that was sometimes used by customers in some of the run javascript Rule-actions. Alternatively to jQuery, you can still use Sizzle selectors or Vanilla JavaScript
Lodash and giosg._ removed Lodash might be used by some of our customers in custom run javascript Rule-actions