> 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). # 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) {% hint style="info" %} Pour utiliser l'API, vous devez avoir soit un conteneur web sur la page **ou** le script de la bibliothèque JS SDK : {% endhint %} ## 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. {% hint style="info" %} Cette commande est facultative, vous pouvez également définir des paramètres personnalisés directement dans un[ `trigger` command](#send-event), via le paramètre de l'objet de configuration. {% endhint %} La commande config prend le format suivant : ```javascript cact('config', {}); ``` 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](/fr/fonctionnalites/sources/sources-catalog/web/containers.md)) * `eventId`: si non défini, un ID aléatoire est défini pour cet événement et sera placé dans `context.event_id` Exemple : ```javascript cact('config', { siteId: 1234, sourceKey: 'abcd' }); ``` ## Envoyer un événement {% hint style="info" %} Pour utiliser l'API, vous devez avoir soit un conteneur web sur la page **ou** le script de la bibliothèque JS SDK : {% endhint %} Pour envoyer des données d'événement à la plateforme Commanders Act server-side, utilisez cette commande : ```javascript cact('trigger', '', {}); ``` Exemple : pour envoyer un événement d'achat : ```javascript 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 : ```javascript 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. ```javascript 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. ```javascript 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. ```javascript 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 `` 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](/fr/fonctionnalites/consent-management/knowledge-base/consent-object.md#meta-properties) ## 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 : ```html ``` {% hint style="info" %} 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`. {% endhint %} ### **Événements disponibles** * **container\_ready**: Se déclenche pour chaque conteneur chargé. * **container\_**`_`**\_ready:** Déclenche un événement spécifique pour chaque`container_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. ```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'); ``` ### **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. ```javascript 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. ```javascript 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. ```javascript cact('setProperty', 'page_type', 'homepage'); cact('setProperty', 'user.email', 'user@example.com'); ``` **`emit` (Alias : `dispatchEvent`)** Déclenchez un événement côté navigateur à utiliser comme déclencheur de tag personnalisé. ```javascript cact('emit', 'page_view', { page_type: 'homepage' }); ``` **`on` (Alias : `addEventListener`)** Abonnez-vous à un événement côté navigateur. ```javascript 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. ```javascript cact('once', 'page_view', listener_callback); ``` **`off` (Alias : `removeEventListener`)** Supprimez un écouteur d'événement. ```javascript 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. ```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 », envisagez d'utiliser le `container_ready` déclencheur personnalisé. **`cact_container`** Contient des informations sur le conteneur. ```javascript { id_container: , id_site: , sourceKey: } ``` **`cact_event`** L'événement qui a déclenché le tag, avec une propriété `cact_event.type`. ```javascript cact('emit', 'page_view', {}); // cact_event.type sera 'page_view' ``` **`cact_event_vars`** Contient toutes les variables d'événement du déclencheur. ```javascript 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. ```html Home ``` 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é. ```javascript 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')`. ```javascript 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" } }); ``` --- # 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, and the optional `goal` query parameter: ``` GET https://doc.commandersact.com/fr/fonctionnalites/sources/sources-catalog/web/js-sdk.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.