giosg Transparency & Consent API

Notice

Features documented here are only available for giosg script v2. If you are using the giosg script v1, please contact giosg support for more details on how to upgrade.

Overview

In this documentation the implementation of Transparency & Consent (TC) has been documented for use with giosg products. Implementing this TC framework to your site will assure that giosg services continue to work in the future. If not stated otherwise by the site containing giosg products, we will assume that no consent is granted and start only those services that can comply with the given consent.

Implementation steps

giosg services provide compatibility layer for sites without the IAB TC Framework. With the compatibility JavaScript API the site can request required purposes and ask the proper consent from visitor. After getting either allowing or denying result, the site can pass that information to giosg.

For sites which are not using the framework there will be new giosgTCApi JavaScript API available in window scope.

giosgTCApi overview:

    type PurposeID = number

    interface TCPreferences {
        /* Defines how giosg can operate. */
        purpose: {
            consents: {[purposeID: PurposeID]: boolean};
            legitimateInterests: {[purposeID: PurposeID]: boolean};
        };
        /* Defines can giosg operate or not. */
        vendor: boolean;
    }

    interface IGiosgTCApi {
        /** 
         * Returns TC requirements for giosg, list of purpose IDs. 
         */
        getRequiredTC(): PurposeID[];
        /** 
         * When a user defines their TC preferences for the site, the site calls this function to notify giosg.
         * Defaults to false.
         */
        setVisitorConsent(consent: TCPreferences): void;
        /** 
         * Returns the visitorConsent value from the giosg.
         */
        getVisitorConsent(): TCPreferences;
        /** 
         * Registered callback function gets called if TC preference is changed by user interacting with giosg products.
         * Returns listener id.
         */
        addEventListener("tcChange", cb: (consent: TCPreferences) => void): number;
        /** 
         * Remove event listener for with given listenerID.
         * Return boolean based on the success of removal.
         */
        removeEventListener(listenerID: number): boolean;

    }

Basic usage

1. On page load, call window.giosgTCApi.getRequiredTC() to get a list of purpose IDs. These IDs are the same that are used by the IAB TC Framework and the more detail explanation for each id can be found from IAB Europe Transparency Consent Framework Policies.
2. Ask TC preferences from the visitor or get the previously given TC preferences.
3. Call window.giosgTCApi.setVisitorConsent() with an object as an parameter containing the purposeID as a key and boolean as a value based on the visitors answers.
   1. giosg will now start services that comply with the given TC preferences.
4. Register event listener by calling window.giosgTCApi.addEventListener() with the tcChange as a event type and callback function as a second.
   1. This callback gets called if visitor has denied the consent but by using giosg services giving the consent to use giosg services.
5. if visitor changes TC preferences, call window.giosgTCApi.setVisitorConsent() with updated values.
   1. giosg will check which services are complying with the given TC preferences.

Information on required purposes and their usage can be found here.

Purpose IDs used by the API are compatible with ones used by IAB TC Framework. More detailed information regarding Purpose IDs can be found from IAB Europe Transparency Consent Framework Policies.

Behavior of the giosg TC API

The giosg TC API respects the signals sent to the API but with one exception. If the visitor does not give consent or has forbidden all/some of them but interacts with the giosg products (for example opens chat or other service) all consents required by giosg will be granted to provide the service which the visitor is requesting.

Example use cases

giosg will check the domain room consent setting and use the cookies accordingly. In the domain room consent settings you can set the default value to be used if giosgTCApi is used on site. By default this setting is set to true which means that on page load the giosgTCApi is granted with all the consents. This setting affects only for the initial behavior of the giosgTCApi on the page load and can be altered on any given time through the giosg TC JS Api documented in this page.

User declines cookie usage completely or only mandatory cookies enabled

• Chat button can be shown but when user wants to chat, giosg updates the visitor consent preferences accordingly to enable chat purposes needed by chat. Please note that when chat starts, giosg visitor analytics is started by default.

Notice

If you prefer not to gather visitor analytics during the chat, catch the sent tcChange event and set the consent for purpose IDs 8 and 10 to false immediately. This assures that visitor analytics will not be started at all. If you want to start the visitor analytics at some point, set the needed purpose IDs to true.

• Interactions work like usual but when the visitor interacts with it, it will adjust the visitor cookie preference and enable required purposes based on the interactions.
• Majority of rules are working without any issue, only ones which are affected are ones which save data to user browser. This kind of rules are for example ones which checks and keeps count the visitor page visits/loads and are acting based on those.

If some of the cookies were granted:

    const visitorConsent = window.giosgTCApi.getVisitorConsent();
    visitorConsent.vendor = <boolean> // Set based on did visitor give consent for giosg to work.
    for (const purposeID in consentGivenByVisitor) { 
        // Loop through the purposes given by visitor and set them in giosgTCApi.
        // Example variable "consentGivenByVisitor" is an object containing purposeIDs as key and boolean as a value.
        visitorConsent.purpose.consents[purposeID] = consentGivenByVisitor[purposeID];
    }
    window.giosgTCApi.setVisitorConsent(visitorConsent);

Note if visitor declined all cookie usage you don't need to anything if no purposes are enabled in giosgTCApi.

All cookies are granted

• Everything works as normal.

    const visitorConsent = window.giosgTCApi.getVisitorConsent();
    visitorConsent.vendor = true
    for (const purposeID in visitorConsent.purpose.consents) {
        visitorConsent.purpose.consents[purposeID] = true;
    }
    window.giosgTCApi.setVisitorConsent(visitorConsent);

Permissions are first granted but visitor forbids all or some of them

• giosg will respect all received signals and act accordingly. Immediately after receiving the signal, giosg will stop accessing and processing the data related to the signal. This means that there might be some cookies and/or data left to the visitors browser local-/sessionStorage.

    const visitorConsent = window.giosgTCApi.getVisitorConsent();
    visitorConsent.vendor = <boolean> // Set based on did visitor give consent for giosg to work.
    for (const purposeID in consentGivenByVisitor) { 
        // Loop through the purposes given by visitor and set them in giosgTCApi.
        // Example variable "consentGivenByVisitor" is an object containing purposeIDs as key and boolean as a value.
        visitorConsent.purpose.consents[purposeID] = consentGivenByVisitor[purposeID];
    }
    window.giosgTCApi.setVisitorConsent(visitorConsent);