Platform XDocumentationWelcome to Success
Modifier

Javascript SDK

Commencer

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 commandes 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 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 chaîne utilisé pour sélectionner la méthode souhaitée.

Requis

options

Un objet JavaScript qui inclut 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 privacy banners.

Initialiser les paramètres globaux avec config

Utilisez la config commande pour initialiser et configurer les paramètres pour 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'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 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 attribué 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 le script de la bibliothèque JS SDK : https://cdn.tagcommander.com/events/sdk.js

Pour envoyer des données d'événement vers la plateforme Commanders Act côté serveur, 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"
});

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 la 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 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

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

API Stub (optionnel)

Pour un usage avancé, nous fournissons également un API stub qui peut être ajouté lorsque vous avez besoin d'interagir avec l'API avant que les containers ou les banners ne soient chargés. Ce stub est déjà inclus dans les containers et privacy banners, donc vous n'avez pas à l'ajouter dans la plupart des cas d'utilisation. Le stub est utilisé pour 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 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 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 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, assurant 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: Déclenché pour chaque container chargé.

  • container_<siteId>_<containerId>_ready: Déclenche un événement 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 banner 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 privacy banner est affichée.

  • banner-hide: Déclenché lorsque la privacy banner est masquée.

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

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

  • tag_trigger_form_submission: Déclenchement standard de formulaire.

  • tag_trigger_clicks: Déclenchement standard de clics.

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

  • track_all_events: Événement côté serveur 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 Trigger pour déclencher un tag sur consent-update événement

Écouter tous les événements

Vous pouvez écouter tous les événements en utilisant 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 lancement du trigger.

cact('emit', 'my_custom_event');

Vous pourrez utiliser cet événement comme trigger personnalisé 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 côté serveur 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 de tag personnalisé.

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)

Supprimer un écouteur d'événement.

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

trigger

Envoyer un événement côté serveur. Toute 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 custom trigger.

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 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' })">Accueil</a>

Pour plus d'exemples et une démo en direct, consultez les liens de documentation fournis.

Bonnes pratiques et conseils

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

Sur les sites multi-container, les é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 natif « Container Loaded ». Utilisez le nouveau container_ready custom trigger pour une résolution précise du site-id/source-key.

Événements liés à la vie privée

Vous pouvez utiliser divers événements liés à la vie privée comme triggers personnalisés :

  • consent_ready

  • consent_updated

  • consent_revoke

  • banner_show

  • banner_hide

  • privacy_center_show

  • privacy_center_hide

Suivi côté serveur comme triggers personnalisés

Besoin de suivre un événement envoyé en Server Side ?

Notre cact('trigger', ...) disparera 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 de tag personnalisé TMS, vous devrez préfixer le nom de l'événement par "track_*"\nExemple:\

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

Vous pouvez vous abonner à tout é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édentIDs TMS & bannières de consentementSuivantRendu server-side Next.js

Mis à jour

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