Platform XDocumentationWelcome to Success
Modifier

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 au sein de cact(): config est utilisée pour définir des options générales, trigger event est utilisée 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 bibliothèque 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
Requis

command

Un identifiant de type chaîne utilisé pour sélectionner la méthode souhaitée.

Requis

options

Un objet JavaScript contenant les données transmises à la méthode.

Optionnel

config

Un objet javascript utilisé pour remplacer les paramètres par défaut tels que 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 dans les bannières de confidentialité.

Initialiser les paramètres globaux avec config

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

Cette commande est optionnelle, vous pouvez également 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'id 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 l'id de votre 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 First-party, si vous en configurez un et utilisez un web container)

  • eventId : si non défini, un id aléatoire est attribué à cet événement et sera placé dans context.event_id

Exemple :

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

Envoyer un event

Pour utiliser l'API, vous devez disposer soit d'un web container 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 côté server-side, utilisez cette commande :

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

Exemple : pour envoyer un event purchase :

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

Exemple : pour envoyer un event 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 différentes 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 manière asynchrone. Dans le cas où, 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") {                // Consentement disponible pour toutes les catégories.            }});

Meta Properties

La méthode meta property inclut des métadonnées et le contexte du consentement fourni sur un navigateur. Vous pouvez consulter la liste des Meta properties ici

API Stub (optionnel)

Pour un usage avancé, nous fournissons également 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 à bufferiser 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 bufferise 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 a déjà été installé, il est acceptable d'installer le JavaScript stub plusieurs fois.

Utiliser Javascript SDK dans TMS

Notre système inclut désormais 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 events côté navigateur, les références de commandes et les variables de contexte de tag.

Events côté navigateur

Introduction

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

Voici comment vous pouvez utiliser ces events :

<!-- Ancienne méthode (peut causer 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 fait tC.event.my_custom_event.

Events disponibles

  • container_ready : Déclenché 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 : Déclenché lorsque le cookie de consentement est défini ou que la bannière est acceptée/refusée.

  • consent-updated : Déclenché lorsque le consentement est mis à jour.

  • consent-revoke : Déclenché lorsque le consentement est révoqué.

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

  • banner-show : Déclenché lorsque la bannière de confidentialité est affichée.

  • banner-hide : Déclenché lorsque la bannière de confidentialité est masquée.

  • privacy-center-show : Déclenché lorsque le centre de confidentialité est affiché.

  • privacy-center-hide : Déclenché lorsque le centre de confidentialité est fermé.

  • tag_trigger_form_submission : Déclencheur standard pour les formulaires.

  • tag_trigger_clicks : Déclencheur standard pour les clics.

  • tag_trigger_scroll : Déclencheur standard pour le scroll.

  • track_all_events : Event côté server-side envoyé avec cact('trigger') API.

  • track_* : Similaire à track_all_events mais avec des noms d'events 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és en utilisant cact('emit').

Exemple de trigger pour lancer un tag sur consent-update event

Écouter tous les Events

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

cact('emit', 'my_custom_event');

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

Référence des commandes

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

config

Définir diverses configurations du site.

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

setProperty

Définir des propriétés à fusionner avec les events côté 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 event côté navigateur pour l'utiliser comme trigger personnalisé de tag.

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

on (Alias : addEventListener)

S'abonner à un event côté navigateur.

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

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

once

Similaire à on, mais le callback ne se déclenche qu'une seule fois.

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

off (Alias : removeEventListener)

Retirer un écouteur d'event.

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

trigger

Envoyer un event côté 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 de tag

Le Tag Context fournit des variables utilisées au sein d'un tag. Si vous avez besoin d'un Tag Context similaire à « Container Loaded », envisagez d'utiliser le container_ready custom trigger.

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 sera 'page_view'

cact_event_vars

Contient toutes les variables d'event du trigger.

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

cact_event_attrs

Contient les attributs de l'event, définis en utilisant la propriété from 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-container, des 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 native « Container Loaded ». Utilisez le nouveau container_ready custom trigger pour une résolution précise du site-id/source-key.

Events liés à la confidentialité

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

  • consent_ready

  • consent_updated

  • consent_revoke

  • banner_show

  • banner_hide

  • privacy_center_show

  • privacy_center_hide

Suivi Server-Side en tant que triggers personnalisés

Besoin de suivre un event envoyé côté Server Side ?

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

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

Pour utiliser cette fonctionnalité comme trigger de tag personnalisé dans le TMS, vous devrez préfixer le nom de l'event par « track_* » Exemple :

Utilisation de cact('on') pour l'abonnement aux Events

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

cact('on', 'my_custom_event', function(event) {
  console.log('a reçu un event', event.type); // "my_custom_event"
  console.log('données de l'event :', event.eventData); // { var: "value" }
});
PrécédentTMS & Consent banners IDsSuivantNext.js serverside rendering

Mis à jour

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