How the giosg script works
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.
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.
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
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:
_giosgfunction is very lightweight, including just the organization ID and a "queue" for API calls that will be executed once the Giosg script is loaded.
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
giosgthat 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
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
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
- 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)
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
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.
V2 script is much smaller/faster and has significantly less dependencies to third party js libraries!
New features only supported by V2:
|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:
|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|