Skip to content

giosg - How does the giosg script work?

Warning

Note that this documentation is for deprecated leagcy version of the script, you can find the newer V2 version documentation 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 + "/live/";
    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, 1);
</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/live/. 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/live/ 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.
  • An isolated version of the jQuery library, available at giosg.$. It is independent of any jQuery that might be included in the example.com website. jQuery is used for DOM manipulation and AJAX requests.
  • An isolated version of the Lodash library, available at giosg._. It is independent of any Lodash/Underscore that might be included in the example.com website. Lodash is used to ensure cross-browser compatibility and to support older browsers.
  • 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/v2/visitor/settings/<organizationId>?url=<currentUrl>.

For example: https://service.giosg.com/api/v2/visitor/settings/1/?url=https%3A%2F%2Fwww.giosg.com%2F

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:

  • The URL of the actual client script to be loaded (see the next section)
  • 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

The client configuration is stored to attributes of the global giosg namespace object for later use.

Client script

Once the client configuration is loaded, another script tag is injected to the DOM, loading the JavaScript from https://service.giosg.com/static/visitor.<scriptVersion>.js. For example: https://service.giosg.com/static/visitor.4e1f047cd8c52f96.js

About performance: This script is separated from the core loader script because this file will be cached for a very long time (about a year). This way, browsers will load this only on their first page load and then again only whenever the contents of the script file are updated, changing the version number in the URL.

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
  • Managing the the chat button
  • Managing the visual state of chat windows
  • Managing any custom elements
  • Managing the visual state of lead forms
  • Sending track events
  • Managing of Giosg Basket (shopping carts)
  • Implementation of the JavaScript APIs
  • 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 from 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.
  • Avoids issues with any cross-origin requests. Some old browsers have limited cross-origin request support, and they would therefore have difficulties with integrating to Giosg platform. Using the iframe avoids these issues.
  • 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.

About performance: The scripts and stylesheets loaded by the iframe are cached for a very long time (about a year). This way, browsers will load these only on their first page load.