SDK JavaScript

Prise en main

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

Différentes commandes sont disponibles dans cact(): config sert à définir les options générales, trigger event sert à envoyer des données, et d'autres commandes spécifiques get/update/revoke sont utilisées pour interagir avec les fonctionnalités de la plateforme (ex : obtenir le consentement utilisateur)

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

Comment l'utiliser

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

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

Argument	Descriptions	Obligatoire
command	Un identifiant sous forme de chaîne utilisé pour sélectionner la méthode souhaitée.	Obligatoire
options	Un objet JavaScript qui inclut les données transmises à 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 de l'API onsite.	Facultatif

L'API onsite est incluse dans chaque conteneur et bannière de confidentialité.

Initialiser les paramètres globaux avec config

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

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

La commande config prend le format suivant :

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

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

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

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

• collectionDomain: si non défini, la valeur par défaut est collect.commander1.com (ou votre domaine First party, si vous en configurez un et utilisez un conteneur web)

• eventId: si non 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 conteneur web sur la page ou le script de 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 / l'espace de travail / sourceKey par défaut :

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

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

Dans certaines configurations, vous devrez peut-être envoyer des événements sans consentement utilisateur, par exemple lors de l'utilisation d'une configuration analytique exemptée de consentement.

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

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 via la config commande.

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

Tous les événements suivants envoyés 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 sélectivement 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 toujours être désactivé pour des événements spécifiques.

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

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

Cela vous permet de contrôler entièrement la manière dont chaque événement est collecté.

Quand utiliser cette option

Utilisez exemptMode quand :

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

• ou vous utilisez une configuration analytique exemptée de consentement

Cas d'utilisation typique :

Un événement est déclenché dès le chargement de la page, avant que l'utilisateur n'interagisse avec la bannière de consentement, et doit tout de même être envoyé à des fins d'analyse 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") {                // Consentement disponible pour toutes les catégories.            }});

Les méthodes de l'API onsite 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 rappel. Exemple :

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

Propriétés Meta

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

Stub API (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 conteneurs ou les bannières soient chargés. Ce stub est déjà inclus dans les conteneurs et les bannières de confidentialité, donc vous n'avez pas besoin de l'ajouter dans la plupart des cas d'utilisation. Le stub sert à mettre en mémoire tampon toutes les méthodes dans un tableau JavaScript jusqu'à ce que le JavaScript de Commanders Act soit chargé et prêt à traiter les méthodes. Cela permet par exemple d'utiliser l'API onsite 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 mémoire tampon les interactions avec l'API. window.cact est une fonction JavaScript utilisée pour interagir avec l'API onsite.

Si vous travaillez dans une grande équipe et 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 JS SDK dans le 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 événements côté navigateur, les références de commandes et les variables de contexte de tag.

---

Événements côté navigateur

Introduction

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

Voici comment vous pouvez utiliser ces événements :

<!-- Ancienne méthode (peut causer des problèmes si l'événement 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'événements 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 conteneur chargé.

• container_<siteId>_<containerId>_ready: Déclenche un événement spécifique pour chaquecontainer_ready événement (ex : container_1234_1_ready)

• consent-ready: Se déclenche lorsque le cookie de consentement est défini ou que la bannière 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 bannière de confidentialité est affichée.

• banner-hide: Se déclenche lorsque la bannière de confidentialité est masquée.

• privacy-center-show: Se déclenche lorsque le centre de confidentialité est affiché.

• privacy-center-hide: Se déclenche lorsque le centre de confidentialité est fermé.

• tag_trigger_form_submission: Déclencheur standard de formulaire.

• tag_trigger_clicks: Déclencheur standard de clics.

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

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

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

• privacy-module-loaded: Événement interne déclenché lorsque tC.privacy est initialisé.

• Événements personnalisés: Envoyés en utilisant cact('emit').

Exemple de déclenchement pour faire apparaître un tag sur consent-updated événement

Écouter tous les événements

Vous pouvez écouter tous les événements en utilisant 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 déclencheur personnalisé, utilisez la cact('emit', 'my_custom_event') commande. Notez que les tirets seront convertis en underscores lors du lancement du déclencheur.

cact('emit', 'my_custom_event');

Vous pourrez utiliser cet événement comme déclencheur personnalisé TMS :

---

Référence des commandes

Le conteneur fournit un ensemble de commandes, dont certaines déclenchent des événements côté navigateur. Pour voir toutes les commandes, tapez tC.cact dans votre console.

config

Définir 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 événements 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 événement côté navigateur à utiliser comme déclencheur de tag personnalisé.

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

on (Alias : addEventListener)

Abonnez-vous à un événement côté navigateur.

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 événement server-side. Tout appel à cact('trigger', ...) déclenchera également un track_all_events événement générique.

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

---

Variables de contexte de tag

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 conteneur.

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

cact_event

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

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

cact_event_vars

Contient toutes les variables d'événement du déclencheur.

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

cact_event_attrs

Contient les attributs de l'événement, définis à l'aide de la depuis propriété dans 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émo en direct, consultez les liens de documentation fournis.

---

Bonnes pratiques et conseils

Résoudre les conflits Site-ID/Source-Key

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

Événements liés à la confidentialité

Vous pouvez utiliser divers événements liés à la confidentialité comme déclencheurs personnalisés :

• consent_ready

• consent_updated

• consent_revoke

• banner_show

• banner_hide

• privacy_center_show

• privacy_center_hide

Suivi server-side comme déclencheurs personnalisés

Vous avez besoin de suivre un événement envoyé en server-side ?

Notre cact('trigger', ...) déclenchera un track_* événement correspondant, 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'événement avec "track_*" Exemple :\

Utiliser cact('on') pour l'abonnement aux événements

Vous pouvez vous abonner à n'importe quel événement envoyé en utilisant cact('emit').

cact('on', 'my_custom_event', function(event) {
  console.log('événement reçu', event.type); // "my_custom_event"
  console.log('données de l'événement :', event.eventData); // { var: "value" }
});