Skip to content

Sending visitor variables(Javascript)

Notice

If you have Transparency&Consent feature implemented, see how it affects the behavior from Transparency&Consent documentation

Overview

You can attach key value pairs to visitor with giosg JavaScript API. This data is then available to operators in giosg and also in reporting. Data can also be signed so that you can trust that the submitted data originated from you and was not tampered by visitor.

Prerequisites

To use giosg visitor JavaScript API you need to be using latest version of giosg script tag on the site.

JavaScript API can be used in two ways. Asynchronously with _giosg object or calling API method’s directly. _giosg object is available right after giosg script tag so you don’t need to wait for giosg to be fully loaded before calling API.

Sometimes it is however useful to know when the API calls complete. For that reason you can also call giosg API methods directly and receive jQuery promise as return value. When you want to call API methods directly it is important to wrap your code inside _giosg(function () { ... }); to make sure that giosg client is fully loaded before the call is made.

Following API calls are identical:

1
2
3
_giosg('visitor', 'submit', <visitor_data>, <signing_algorithm>, <replace_existing>, <room_information>);
//is the same as:
_giosg(function () { giosg.api.visitor.submit({ username: 'John Doe' }).then(success, error); });

This documentation uses only asynchronous versions of API’s as examples from this point on. To “convert” asynchronous call to normal API call use following pattern:

1
_giosg('module', 'method', arg1, arg2, ..) translates to giosg.api.<module>.<method>(arg1, arg2, ..);

Use following helper script for all the submits, this way you don't need to hardcode the room id to every call because without including the room info the variables are only submitted to the domain room and is not visible in the chats if you use custom rooms. The roomlistarray will be passed as a paramameter in the actual submit call.

1
2
//PLAIN HELPER FOOR ROOM JS
const roomList = giosg.rooms.map(i => ({"id": i}))

Available parameters

_giosg('visitor', 'submit', <variables>, <signing_algorithm>, <replace_existing>, <room_information>);

Attribute Type Required Description
variables object required JSON serializable object containing key value pairs. Object can contain attributes of any names. username and avatar attributes have special meaning. The username is displayed as visitor’s name in chat dialog and reports. Example: { username: 'John Doe' }. The avatar variable contains url for image that is then displayed in giosg with the visitor’s username. Example
signing_algorithm string optional String identifying which algorithm is used for signing. Default is ‘plain’ which means no signing. See full list of supported algorithms below.
replace_existing boolean optional If set to true will replace existing data that was attached to visitor. Otherwise existing data will be extended with new values. Default is false.
room_information array optional Array of room information objects. This parameter controls the room where the data will be connected. If not set, it will default to domain room. Room info object has to contain either id or name attribute. Example: [{ name: 'My custom room' }]. Our recommendation is to use the helper script provided in the beginning of this document so you don't need to hardoce these values.

Supported signing algorithms

Algorithm Type Description
HS256 JWT HMAC using SHA-256 hash algorithm (recommended)
HS384 JWT HMAC using SHA-384 hash algorithm
HS512 JWT HMAC using SHA-512 hash algorithm
RS256 JWT RSASSA-PKCS1-v1_5 signature algorithm using SHA-256 hash algorithm
RS384 JWT RSASSA-PKCS1-v1_5 signature algorithm using SHA-384 hash algorithm
RS512 JWT RSASSA-PKCS1-v1_5 signature algorithm using SHA-512 hash algorithm
sha1 hash SHA-1 (Secure Hash Algorithm 1)
md5 hash MD5 message-digest algorithm

* use of md5 is not recommended

Submitting variables to the chat

You can bind for example the login information about the user to the visitor variables and send them to the chat. You should bind the values from your page and send them to the chat, below is an example how the whole submit function can look:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
//example variables from the page or backend to use for submitting the login information
const firstName = "Bill"
const lastName = "Giosg"
const eMail = "tester@test.com"


//PLAIN HELPER FOOR ROOM JS
const roomList = giosg.rooms.map(i => ({"id": i}))

_giosg('visitor','submit',{
  Firstname: firstName,
  Lastname: lastName,
  Email: eMail
},'plain',true, roomList)

Signing visitor variables

Signing is used for validating that variables are not altered by web page’s visitor. If signing is required for domain and checksum is not set or it’s wrong, then giosg will reject the variables and HTTP status 400 will be returned.

Singing of the variables are done through JSON Web Token specification (JWT). JSON Web Token specification is recommended with HMAC SHA-256 hash algorithm.

Please note that signed variables can be still seen by visitor but cannot be modifed anyway without giosg being able to recognize that and then reject the variables.

Setup in giosg account for signing

To enable the feature to only accept signed variables in your giosg room navigate to: Settings->Rooms->{room_name}-> Security and Encryption-> tick the checkbox below the text: "Always require signatures for visitor data and chat URLs" Screenshot

API signing key

The API signing key for signing the visitorvariables needs to be created in your giosg account. This can be created under Settings->Company->"API Signing Keys". On this page click the "Generate new signing Key" button to create a new key.

Remember to store this key safely and not expose the key to your front-end so that it can't be used to alter the submitted data

Generating the payload

Below is an example how to create the jwt-signed payload in python and nodejs, the data we are sending in the example is: Email: tester@giosg.com

1
2
3
4
5
6
7
8
9
# 1. Install PyJWT
import jwt
import time

signing_key = "<the signing key created in your account>"
exp = int(time.time() + 3000) #Give expiration time, here 30s in the future, If this expire the server will return 400 - {"detail":"Expired signature"}
payload = {"Email": "tester@giosg.com", "exp": exp}
chat_payload = jwt.encode(payload, signing_key, "HS256")
print(chat_payload)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
//For jwt encoding you need a jwt package e.g jwt-encode, https://www.npmjs.com/package/jwt-encode
const sign = require('jwt-encode');
const secret = "<the signing key created in your account>"
let expTime = Math.round((new Date()).getTime() / 1000) + 1000; // time now + 1000s If this expire the server will return 400 - {"detail":"Expired signature"}

const visitorData = {"Email": "tester@giosg.com", "exp": expTime}

const signedData = sign(visitorData, secret);

console.log(signedData)

Submitting the jwt payload to the chat with javascript

1
2
3
4
5
6
7
8
//Helperfunction to submit to correct rooms
const roomList = giosg.rooms.map(i => ({"id": i}))

//Submit the visitor data with javascript:
jwt_payload = "<chat_payload from the signedData variable>"
var algorithm = 'HS256';

_giosg('visitor', 'submit', jwt_payload, algorithm, true, roomList);

This is how it looks in the chat window, pleas note that when the lock icon is blue it means that the data is signed correctly:

Screenshot

Remove submitted variables and end the chat-session on logout

Usually the visitor variables are set when user logs in on your page, it is strongly recommended to also remove these variables when the user logs out. For removing the varables from all of your room please use below javascript call. For this call you need to have a list of all of your room id's(this list can be skipped if you are only using the domain room)

Hint: If there is situations that the removing of variables doesn't work it might be that the request didn't go through before there was a redirect so you can add a small delay before the redirect or use the asynchronous version that returns a promise and then perform the rediregt after log out.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
//list of the rooms in your account, use the legacy id that can be found in your room setting under the header: "Legacy Room ID"

const customRooms = [{
    id:'asdasdasdsv3mqh3gjjadiaafp2xwinhxxir5g2hcascvqiqacam', clearHistory: true
    },{
    id:'asdfasdasdabuxturlkbxaaaeplnmh5knwqr5gchqascvqiqahym', clearHistory: true
  }
];

roomInfo.forEach(el => {
    //this closes the chat and clears the history in the chat-window on visitor side
    _giosg('chat', 'close', el);
    //this removes the visitor data
    _giosg('visitor', 'removeAll', {id: el.id});
});

Conclusion

In this tutorial we went through the process of submitting extra info about the visitor to the chat and the optional(still recommended) parts of signing the data and removing the submitted information after the chat. If your you would like to do this same process through rest-api's please follow the tutorial Sending visitor variables(REST-API).