> For the complete documentation index, see [llms.txt](https://doc.commandersact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.commandersact.com/fr/fonctionnalites/sources/sources-catalog/web/js-sdk.md). # Javascript SDK ## Démarrage The onsite API est utilisée pour interagir avec les fonctionnalités de Commanders Act avec JavaScript. Il existe différentes commandes disponibles dans `cact()`: `config` est utilisé pour définir les options générales, `trigger` event est utilisé pour envoyer des données, et d'autres commandes spécifiques `get/update/revoke` les commandes sont utilisées pour interagir avec les fonctionnalités de la plateforme (ex : obtenir le consentement de l'utilisateur) {% hint style="info" %} Pour utiliser l'API, vous devez avoir soit un web container sur la page **ou** le script de la bibliothèque JS SDK : {% endhint %} ## Comment utiliser The 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 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 tels que `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. ## Initialisez les paramètres globaux avec config Utilisez la `config` commande pour initialiser et configurer les paramètres d'un workspace particulier. {% hint style="info" %} Cette commande est facultative, vous pouvez également définir des paramètres personnalisés directement dans une[ `trigger` command](#send-event), via le paramètre d'objet config. {% endhint %} La commande config prend le format suivant : ```javascript cact('config', {}); ``` L'objet config accepte **4 paramètres**, ils sont facultatifs 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, 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 [web container](/fr/fonctionnalites/sources/sources-catalog/web/containers.md)) * `eventId`: si non défini, un ID aléatoire est défini pour cet event et sera placé dans `context.event_id` Exemple : ```javascript cact('config', { siteId: 1234, sourceKey: 'abcd' }); ``` ## Envoyer un event {% hint style="info" %} Pour utiliser l'API, vous devez avoir soit un web container sur la page **ou** le script de la bibliothèque JS SDK : {% endhint %} Pour envoyer les données d'event à la plateforme Commanders Act server-side, utilisez cette commande : ```javascript cact('trigger', '', {}); ``` Exemple : pour envoyer un event d'achat : ```javascript cact('trigger', 'purchase', { id:'1234', currency: 'EUR', //...}); ``` Exemple : pour envoyer un event d'achat, en remplaçant le tracking domain / workspace / sourcekey par défaut : ```javascript 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 pouvez avoir besoin d'envoyer des events sans consentement de l'utilisateur, par exemple lorsque vous utilisez une configuration d'analytics exemptée de consentement. Dans ce cas, vous pouvez activer l' `exemptMode` option. Lorsqu'il est activé, Commanders Act collectera l'event sans définir de cookies d'identifiant tels que `CAID`, `WID`, (ou `TCID` selon votre configuration). #### Configuration globale Vous pouvez activer `exemptMode` globalement à l'aide de la `config` commande. ```javascript cact('config', { exemptMode: true }); ``` Tous les events envoyés avec `cact('trigger', ...)` utiliseront ce comportement par défaut, sauf s'il est remplacé au niveau de l'event. #### Configuration par event Vous pouvez activer `exemptMode` uniquement pour certains events en utilisant le paramètre de configuration de `trigger` commande. ```javascript cact('trigger', 'page_view', { page_type: 'home' }, { exemptMode: true }); ``` Cela vous permet d'envoyer de manière sélective certains events 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 certains events. ```javascript cact('config', { exemptMode: true }); cact('trigger', 'purchase', { id: '1234' }, { exemptMode: false }); ``` Cela permet un contrôle total sur la manière dont chaque event est collecté. #### Quand utiliser cette option Utilisez `exemptMode` lorsque : * votre event est envoyé avant que l'utilisateur n'ait donné son consentement * ou vous utilisez une configuration d'analytics exemptée de consentement Cas d'utilisation typique : Un event est déclenché dès le chargement de la page, avant que l'utilisateur n'interagisse avec la bannière de consentement, 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 de 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 synchrones dans le `` 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") { // Consent 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](/fr/fonctionnalites/consent-management/knowledge-base/consent-object.md#meta-properties) ## Stub API (facultatif) Pour une utilisation avancée, nous fournissons également un stub d'API qui peut être ajouté lorsque vous avez besoin d'interagir avec l'API avant que les containers ou les privacy banners ne soient chargés. Ce stub est déjà inclus dans les containers et les privacy banners, donc vous n'avez 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 de 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 n'êtes pas certain que le stub a déjà été installé, il est possible d'installer le stub JavaScript plusieurs fois. ## Utilisez le JS SDK dans TMS *** Notre système inclut désormais plusieurs nouvelles fonctionnalités améliorées pour vous aider à gérer et mettre en œuvre 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 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 de `tC.event.XXX` des fonctions, garantissant une gestion des events plus sûre et plus fiable. Voici comment vous pouvez utiliser ces events : ```html ``` {% hint style="info" %} 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`. {% endhint %} ### **Events disponibles** * **container\_ready**: se déclenche pour chaque container chargé. * **container\_**`_`**\_ready:** Déclenche un event spécifique pour chaque container`container_ready` event (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 privacy banner est affichée. * **banner-hide**: se déclenche lorsque la privacy banner est masquée. * **privacy-center-show**: se déclenche lorsque le privacy center est affiché. * **privacy-center-hide**: se déclenche lorsque le privacy center est fermé. * **tag\_trigger\_form\_submission**: trigger de formulaire standard. * **tag\_trigger\_clicks**: trigger de clics standard. * **tag\_trigger\_scroll**: trigger de défilement standard. * **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és à 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. ```javascript 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'); ``` ### **Triggers 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. ```javascript cact('emit', 'my_custom_event'); ``` Vous pourrez utiliser cet event comme trigger personnalisé 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éfinissez diverses configurations du site web. ```javascript 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. ```javascript cact('setProperty', 'page_type', 'homepage'); cact('setProperty', 'user.email', 'user@example.com'); ``` **`emit` (Alias : `dispatchEvent`)** Déclenchez un event côté navigateur à utiliser comme trigger personnalisé de tag. ```javascript cact('emit', 'page_view', { page_type: 'homepage' }); ``` **`on` (Alias : `addEventListener`)** Abonnez-vous à un event côté navigateur. ```javascript 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 la fonction de rappel ne se déclenche qu'une seule fois. ```javascript cact('once', 'page_view', listener_callback); ``` **`off` (Alias : `removeEventListener`)** Supprimez un écouteur d'event. ```javascript 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. ```javascript 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", pensez à utiliser le `container_ready` trigger personnalisé. **`cact_container`** Contient des informations sur le container. ```javascript { id_container: , id_site: , sourceKey: } ``` **`cact_event`** L'event qui a déclenché le tag, avec une propriété `cact_event.type`. ```javascript cact('emit', 'page_view', {}); // cact_event.type will be 'page_view' ``` **`cact_event_vars`** Contient toutes les variables de l'event provenant du trigger. ```javascript 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 la `de` propriété dans `emit` ou `trigger` API. ```html Home ``` Pour plus d'exemples et une démo 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` trigger personnalisé pour une résolution précise de site-id/source-key. **Events liés à la confidentialité** Vous pouvez utiliser divers 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` **Tracking Server-Side comme Triggers personnalisés** Besoin de suivre un event envoyé en Server Side ? Notre `cact('trigger', ...)` déclenchera un `track_*` event, que vous pouvez utiliser comme trigger personnalisé. ```javascript cact('trigger', 'page_view', { value: 42, currency: 'EUR' }); ``` Pour utiliser cette fonctionnalité comme trigger personnalisé de tag TMS, vous devrez préfixer le nom de l'event avec "track\_\*"\nExemple :\\
**Utilisation de `cact('on')` pour l'abonnement aux events** Vous pouvez vous abonner à n'importe quel event envoyé à l'aide de `cact('emit')`. ```javascript cact('on', 'my_custom_event', function(event) { console.log('un event a été reçu', event.type); // "my_custom_event" console.log('données de l'event :', event.eventData); // { var: "value" } }); ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://doc.commandersact.com/fr/fonctionnalites/sources/sources-catalog/web/js-sdk.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.