SDK JavaScript

Premiers pas

L'Onsite API est utilisée pour interagir avec les fonctionnalités Commanders Act en JavaScript.

Il existe différentes commandes disponibles dans cact(): config est utilisée pour définir les options générales, trigger event est utilisé pour envoyer des données, et d'autres spécifiques get/update/revoke commands are used to interract with platform features (ex : get user consent)

Pour utiliser l'API, vous devez avoir soit un web container sur la page ou la bibliothèque JS SDK : https://cdn.tagcommander.com/events/sdk.js

Comment utiliser

L'Onsite API se compose d'une seule fonction, cact(), avec la signature stricte suivante :

cact(command, [options,], [config,], [callback])

Argument	Descriptions	Obligatoire
command	Un identifiant de chaîne utilisé pour sélectionner la méthode souhaitée.	Obligatoire
options	Un objet JavaScript qui inclut les données passées à la méthode.	Facultatif
config	Un objet JavaScript utilisé pour remplacer les paramètres par défaut comme siteId , collectionDomain , eventId, ou sourceKey	Facultatif
callback	Une fonction de rappel JavaScript utilisée pour recevoir des informations ou des événements depuis l'Onsite API.	Facultatif

L'Onsite API est incluse dans chaque container et chaque privacy banner.

Initialiser les paramètres globaux avec config

Utilisez la config commande pour initialiser et configurer les paramètres d'un workspace particulier.

Cette commande est facultative, vous pouvez aussi définir des paramètres personnalisés directement dans un trigger command, via le paramètre de l'objet config.

La commande config prend la forme suivante :

cact('config', {<config_object>});

L'objet config accepte 4 paramètres, ils sont facultatifs si vous utilisez un web container sur votre page :

• siteId : si ce n'est pas défini, la valeur par défaut est l'ID du site du dernier web container chargé (tC.id_site)

• sourceKey: si ce n'est pas défini, la valeur par défaut est dérivée de l'ID de votre web container. Si vous n'avez pas de web container, sourceKey est obligatoire et correspond à votre source JS SDK.

• collectionDomain: si ce n'est pas défini, la valeur par défaut est collect.commander1.com (ou votre domaine first party, si vous en configurez un et utilisez un web container)

• eventId: si ce n'est pas défini, un ID aléatoire est défini pour cet événement et sera placé dans context.event_id

Exemple :

cact('config', { siteId: 1234, sourceKey: 'abcd' });

Envoyer un événement

Pour utiliser l'API, vous devez avoir soit un web container sur la page ou la bibliothèque JS SDK : https://cdn.tagcommander.com/events/sdk.js

Pour envoyer des données d'événement à la plateforme Commanders Act server-side, utilisez cette commande :

cact('trigger', '<event_name>', {<event_params>});

Exemple : pour envoyer un événement d'achat :

cact('trigger', 'purchase', {   id:'1234',  currency: 'EUR',  //...});

Exemple : pour envoyer un événement d'achat, en remplaçant le domaine de tracking / workspace / sourcekey par défaut :

cact('trigger', 'purchase', {   id:'1234',  currency: 'EUR',  //...},{
    collectionDomain: "my.firstdomain.com",
    siteId: "1234", 
    sourceKey: "abcd"
});

Envoyer des events en mode exempté (sans cookies d'identifiant)

Dans certaines configurations, vous devrez peut-être envoyer des events sans consentement utilisateur, par exemple avec une configuration analytics exemptée de consentement.

Dans ce cas, vous pouvez activer l' exemptMode option.

Lorsqu'elle est activée, Commanders Act collectera l'événement sans définir de cookies d'identifiant tels que CAID, WID, (ou TCID selon votre configuration).

Configuration globale

Vous pouvez activer exemptMode globalement avec la config commande.

cact('config', {
  exemptMode: true
});

Tous les events envoyés ensuite avec cact('trigger', ...) utiliseront ce comportement par défaut, sauf s'il est remplacé au niveau de l'événement.

Configuration par événement

Vous pouvez activer exemptMode uniquement pour des événements spécifiques en utilisant le paramètre de configuration de trigger commande.

cact('trigger', 'page_view', {
  page_type: 'home'
}, {
  exemptMode: true
});

Cela vous permet d'envoyer de manière sélective certains événements en mode exempté tout en gardant les autres en mode standard.

Remplacer la configuration globale

Si exemptMode est activé globalement, il peut quand même être désactivé pour des événements spécifiques.

cact('config', {
  exemptMode: true
});

cact('trigger', 'purchase', {
  id: '1234'
}, {
  exemptMode: false
});

Cela permet un contrôle total sur la manière dont chaque événement est collecté.

Quand utiliser cette option

Utilisez exemptMode lorsque :

• votre événement est envoyé avant que l'utilisateur n'ait donné son consentement

• ou que vous utilisez une configuration analytics exemptée de consentement

Cas d'utilisation typique :

Un événement est déclenché dès que la page se charge, avant que l'utilisateur n'interagisse avec la privacy banner, et doit néanmoins être envoyé à des fins d'analytics sans définir de cookies d'identifiant.

---

Obtenir des informations

Pour obtenir différentes valeurs depuis Commanders Act, utilisez cette commande :

cact(get command, [callback])

Exemple : pour obtenir le consentement de TrustCommander, vous pouvez appeler l' consent.get API comme ceci :

cact('consent.get', function(result) {    if (result.consent.status === "all-on") {                // Consent disponible pour toutes les catégories.            }});

Les méthodes de l'Onsite API sont appelées de manière asynchrone. Si, par exemple, vous avez besoin d'informations de manière synchrone dans le <head> du document, il est recommandé de mettre en cache et de récupérer le résultat de l'API dans localStorage.

Gestion des erreurs

Vous pouvez gérer les erreurs via la propriété error dans l'objet de callback. Exemple :

cact('consent.get', function(result) {​    if (result.error) {            // Gérer l'erreur        }    else if (result.consent.status === "all-on") {                // Consent disponible pour toutes les catégories.            }});

Propriétés Meta

Le meta la propriété inclut les métadonnées et le contexte du consentement qui a été fourni dans un navigateur. Vous pouvez voir la liste des propriétés Meta ici

API Stub (facultatif)

Pour une utilisation avancée, nous fournissons également un stub API qui peut être ajouté lorsque vous devez interagir avec l'API avant que les containers ou privacy banners ne soient chargés. Ce stub est déjà inclus dans les containers et privacy banners, vous n'avez donc pas besoin de l'ajouter dans la plupart des cas d'utilisation. Le stub est utilisé pour mettre en tampon toutes les méthodes dans un tableau JavaScript jusqu'à ce que le JavaScript Commanders Act soit chargé et prêt à traiter les méthodes. Cela permet par exemple d'utiliser l'Onsite API avant que le JavaScript de TrustCommander ne soit chargé.

window.caReady = window.caReady || []; window.cact = function() { window.caReady.push(arguments); };

window.caReady est un tableau JavaScript qui met en tampon les interactions avec l'API. window.cact est une fonction JavaScript utilisée pour interagir avec l'Onsite API.

Si vous travaillez dans une grande équipe et que vous n'êtes pas sûr que le stub ait déjà été installé, il est acceptable d'installer le stub JavaScript plusieurs fois.

Utiliser le JavaScript SDK dans TMS

---

Notre système inclut désormais plusieurs nouvelles fonctionnalités améliorées pour vous aider à gérer et implémenter efficacement des tags sur votre site web. Ce guide fournit des informations complètes sur l'utilisation de nos webcontainers TMS et du JavaScript SDK, y compris les events browser-side, les références de commandes et les variables de contexte tag.

---

Events Browser-Side

Introduction

Notre nouveau cact('emit') API est une nouvelle approche de tC.event.XXX des fonctions, garantissant une gestion des événements plus sûre et plus fiable.

Voici comment vous pouvez utiliser ces events :

<!-- Ancienne méthode (peut poser des problèmes si l'event n'existe pas) -->
<a href="mysite.com" onclick="tC.event.my_custom_event(this, { my_event_variable: 'some_value' });">

<!-- Nouvelle méthode (sûre) -->
<a href="mysite.com" onclick="cact('emit', 'my_custom_event', { from: this, my_event_variable: 'some_value' });">

Notez que les tirets (-) dans les noms d'event seront convertis en underscores (_). Par exemple, cact('emit', 'my-custom-event') appellera en réalité tC.event.my_custom_event.

Événements disponibles

• container_ready: se déclenche pour chaque container chargé.

• container_<siteId>_<containerId>_ready: Déclenche un event spécifique pour chaque containercontainer_ready event (ex : container_1234_1_ready)

• consent-ready: se déclenche lorsque le cookie de consentement est défini ou que la banner est acceptée/refusée.

• consent-updated: se déclenche lorsque le consentement est mis à jour.

• consent-revoke: se déclenche lorsque le consentement est révoqué.

• consent-signal-ready: utilisé pour les configurations Google Consent Mode.

• banner-show: se déclenche lorsque la privacy banner s'affiche.

• banner-hide: se déclenche lorsque la privacy banner est masquée.

• privacy-center-show: se déclenche lorsque le privacy center s'affiche.

• privacy-center-hide: se déclenche lorsque le privacy center est fermé.

• tag_trigger_form_submission: déclencheur de formulaire standard.

• tag_trigger_clicks: déclencheur standard de clics.

• tag_trigger_scroll: déclencheur standard de défilement.

• track_all_events: event server-side envoyé avec cact('trigger') API.

• track_*: Similaire à track_all_events mais avec des noms d'event spécifiques (par ex., track_page_view, track_add_to_cart).

• privacy-module-loaded: event interne déclenché lorsque tC.privacy est initialisé.

• Events personnalisés: envoyé à l'aide de cact('emit').

Exemple de trigger pour déclencher un tag sur consent-updated événement

Écouter tous les events

Vous pouvez écouter tous les events à l'aide de la cact('on', '*') API.

function listen_all_events(event) {
  console.log(event.type); // '*'
  console.log(event.originalEvent.type); // 'page_view'
}

cact('on', '*', listen_all_events);
cact('emit', 'page_view');

Déclencheurs de tag personnalisés

Pour déclencher un trigger personnalisé, utilisez la cact('emit', 'my_custom_event') commande. Notez que les tirets seront convertis en underscores lors du déclenchement du trigger.

cact('emit', 'my_custom_event');

Vous pourrez utiliser cet event comme déclencheur personnalisé TMS :

---

Référence des commandes

Le container fournit un ensemble de commandes, dont certaines déclenchent des events browser-side. Pour voir toutes les commandes, tapez tC.cact dans votre console.

config

Définissez diverses configurations du site web.

cact('config', { siteId: 4242, collectionDomain: 'example.com', sourceKey: 'ABCD-1234-EFGH' });

setProperty

Définissez des propriétés à fusionner avec les events server-side envoyés via l'API trigger.

cact('setProperty', 'page_type', 'homepage');
cact('setProperty', 'user.email', '[e-mail]');

emit (Alias : dispatchEvent)

Déclenchez un event browser-side à utiliser comme déclencheur de tag personnalisé.

cact('emit', 'page_view', { page_type: 'homepage' });

on (Alias : addEventListener)

Abonnez-vous à un event browser-side.

cact('on', 'page_view', function(event) {
  console.log('event received of type', event.type); // 'page_view'
  console.log('event data is:', event.eventData); // { page_type: 'homepage' }
});

cact('emit', 'page_view', { page_type: 'homepage' });

once

Similaire à on, mais la fonction de rappel ne s'exécute qu'une seule fois.

cact('once', 'page_view', listener_callback);

off (Alias : removeEventListener)

Supprimez un écouteur d'événement.

cact('off', 'page_view', listener_callback);

trigger

Envoyez un event server-side. Tout appel à cact('trigger', ...) déclenchera également un track_all_events event générique.

cact('trigger', 'add_to_cart', { value: 42, currency: 'EUR' });

---

Variables de contexte des tags

Le Tag Context fournit des variables utilisées dans un tag. Si vous avez besoin d'un Tag Context similaire à "Container Loaded", envisagez d'utiliser le container_ready déclencheur personnalisé.

cact_container

Contient des informations sur le container.

{
  id_container: <containerId>,
  id_site: <siteId>,
  sourceKey: <sourceKey>
}

cact_event

L'event qui a déclenché le tag, avec une propriété cact_event.type.

cact('emit', 'page_view', {});
// cact_event.type will be 'page_view'

cact_event_vars

Contient toutes les variables de l'event provenant du trigger.

cact('emit', 'page_view', { hello: 'world' });
// cact_event_vars will be { hello: 'world' }

cact_event_attrs

Contient les attributs de l'event, définis à l'aide de from property in emit ou trigger API.

<a href="/home" onclick="cact('emit', 'page_view', { from: this, hello: 'world' })">Home</a>

Pour plus d'exemples et une démonstration en direct, reportez-vous aux liens de documentation fournis.

---

Bonnes pratiques et conseils

Résolution des conflits Site-ID/Source-Key

Dans les sites web multi-container, les events étaient parfois envoyés avec un site-id ou un source-key incorrect. Ce problème est corrigé pour les tags utilisant des triggers autres que le natif « Container Loaded ». Utilisez le nouveau container_ready déclencheur personnalisé pour une résolution précise de site-id/source-key.

Events liés à la privacy

Vous pouvez utiliser divers events liés à la privacy comme déclencheurs personnalisés :

• consent_ready

• consent_updated

• consent_revoke

• banner_show

• banner_hide

• privacy_center_show

• privacy_center_hide

Tracking server-side comme déclencheurs personnalisés

Besoin de suivre un event envoyé en Server Side ?

Notre cact('trigger', ...) déclenchera un event correspondant track_* event, que vous pouvez utiliser comme déclencheur personnalisé.

cact('trigger', 'page_view', { value: 42, currency: 'EUR' });

Pour utiliser cette fonctionnalité comme déclencheur de tag personnalisé TMS, vous devrez préfixer le nom de l'event avec "track_*"\nExemple:\\

Utiliser cact('on') pour l'abonnement aux events

Vous pouvez vous abonner à n'importe quel event envoyé à l'aide de cact('emit').

cact('on', 'my_custom_event', function(event) {
  console.log('received an event', event.type); // "my_custom_event"
  console.log('event data:', event.eventData); // { var: "value" }
});