Javascript SDK

Prise en main

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

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

Pour utiliser l'API, vous devez disposer soit d'un web container sur la page ou le script de la librairie JS SDK : https://cdn.tagcommander.com/events/sdk.js

Comment utiliser

L'API onsite consiste en 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 passées à la méthode.

Optionnel

config

Un objet javascript utilisé pour remplacer les paramètres par défaut comme siteId , collectionDomain , eventId, ou sourceKey

Optionnel

callback

Une fonction de rappel JavaScript utilisée pour recevoir des informations ou des événements de l'API onsite.

Optionnel

L'API onsite est incluse dans chaque containers et bannières de confidentialité.

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 optionnelle, vous pouvez aussi définir des paramètres personnalisés directement à l'intérieur d'un trigger command, via le paramètre d'objet config.

La commande config prend le format suivant :

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

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

siteId : si non défini, la valeur par défaut est l'identifiant du site du dernier web container chargé (tC.id_site)
sourceKey : si non défini, la valeur par défaut est dérivée de votre id de web container. Si vous n'avez pas de web container, le sourceKey est obligatoire et correspond à votre source JS SDK.
collectionDomain : si non défini, la valeur par défaut est collect.commander1.com (ou votre domaine 1st party, si vous en avez configuré un et utilisez un web container)
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 disposer soit d'un web container sur la page ou le script de la librairie JS SDK : https://cdn.tagcommander.com/events/sdk.js

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

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

Exemple : pour envoyer un événement purchase :

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

Exemple : pour envoyer un événement purchase, 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"
});

Obtenir des informations

Pour obtenir diverses valeurs depuis Commanders Act, utilisez cette commande :

cact(get command, [callback])

Exemple : pour obtenir le consentement depuis TrustCommander, vous pouvez appeler l'API consent.get 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 façon asynchrone. Dans le cas où, par exemple, vous avez besoin d'informations de façon synchrone dans le <head> du document, il est recommandé de mettre en cache et 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") {                // Consentement disponible pour toutes les catégories.            }});

Propriétés Meta

La meta la propriété inclut des méta-données et le contexte du consentement fourni dans un navigateur. Vous pouvez voir la liste des propriétés Meta ici

API Stub (optionnel)

Pour un usage avancé, nous fournissons aussi un API stub qui peut être ajouté lorsque vous devez interagir avec l'API avant que les containers ou les bannières ne soient chargés. Ce stub est déjà inclus dans les containers et les bannières de confidentialité, vous n'avez donc pas à l'ajouter dans la plupart des cas. Le stub sert à mettre en buffer 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 buffer 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 Javascript SDK dans le TMS

Notre système inclut maintenant plusieurs fonctionnalités nouvelles et améliorées pour vous aider à gérer et implémenter efficacement les tags sur votre site. 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 des tags.

Événements côté navigateur

Introduction

Notre nouveau cact('emit') API est une nouvelle approche des tC.event.XXX fonctions, assurant une gestion d'événements plus sûre et 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 container chargé.
container_<siteId>_<containerId>_ready : Déclenche un événement spécifique pour chaque containercontainer_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 scroll.
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').

Écoute de tous les événements

Vous pouvez écouter tous les événements en utilisant la cact('on', '*') API.

fonction 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 lancement du trigger.

cact('emit', 'my_custom_event');

Vous pourrez utiliser cet événement comme trigger personnalisé dans le TMS :

Référence des commandes

Le container 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éfinir 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', '[email protected]');

emit (Alias : dispatchEvent)

Déclencher un événement côté navigateur pour l'utiliser comme trigger personnalisé de tag.

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

on (Alias : addEventListener)

S'abonner à un événement côté navigateur.

cact('on', 'page_view', function(event) {
  console.log('événement reçu de type', event.type); // 'page_view'
  console.log('les données de l'événement sont :', event.eventData); // { page_type: 'homepage' }
});

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

once

Similaire à on, mais le callback ne s'exécute qu'une seule fois.

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

off (Alias : removeEventListener)

Enlever un écouteur d'événement.

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

trigger

Envoyer 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' });

Tag Context Variables

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 trigger personnalisé.

cact_container

Contient des informations sur le container.

{
  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 provenant du trigger.

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

cact_event_attrs

Contient les attributs de l'événement, définis en utilisant la from 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, référez-vous aux liens de documentation fournis.

Bonnes pratiques et conseils

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

Sur les sites multi-containers, des événements étaient parfois envoyés avec un site-id ou source-key incorrect. Ce problème est corrigé pour les tags utilisant des triggers autres que le native « Container Loaded ». Utilisez le nouveau container_ready trigger personnalisé pour une résolution précise du site-id/source-key.

Événements liés à la confidentialité

Vous pouvez utiliser différents événements liés à la confidentialité comme triggers personnalisés :

consent_ready
consent_updated
consent_revoke
banner_show
banner_hide
privacy_center_show
privacy_center_hide

Tracking server-side comme triggers personnalisés

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 trigger personnalisé.

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

Pour utiliser cette fonctionnalité comme trigger personnalisé TMS, vous devrez préfixer le nom de l'événement par "track_*" Exemple :\

Utilisation de 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" }
});

PrécédentGeoloc API SuivantRendu serveur Next.js

Mis à jour il y a 1 an

Ce contenu vous a-t-il été utile ?

Prise en main

Comment utiliser

Initialiser les paramètres globaux avec config

Envoyer un événement

Obtenir des informations

Gestion des erreurs

Propriétés Meta

API Stub (optionnel)

Utiliser le Javascript SDK dans le TMS

Événements côté navigateur

Événements disponibles

Exemple de Trigger pour déclencher un tag sur consent-update événement

Écoute de tous les événements

Déclencheurs de tag personnalisés

Référence des commandes

Tag Context Variables

Bonnes pratiques et conseils

Exemple de Trigger pour déclencher un tag sur `consent-update` événement