# Javascript SDK ## Premiers pas L’API onsite est utilisée pour interagir avec les fonctionnalités de Commanders Act en JavaScript. Il existe différentes commandes disponibles dans `cact()`: `config` est utilisée pour définir les options générales, `trigger` event est utilisée 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 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 l’utiliser L’API onsite se compose d’une seule fonction, `cact()`, avec la signature stricte suivante : ``` cact(command, [options,], [config,], [callback]) ``` | Argument | Descriptions | Requis | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------- | | `command` | Une chaîne d’identification utilisée 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 comme `siteId` , `collectionDomain` , `eventId`, ou `sourceKey` | Optionnel | | `callback` | Une fonction de rappel JavaScript utilisée pour recevoir des informations ou des événements depuis 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. {% hint style="info" %} Cette commande est facultative, vous pouvez aussi définir des paramètres personnalisés directement dans un[ `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’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 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 avez configuré 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 é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 web container sur la page **ou** le script de la bibliothèque JS SDK : {% endhint %} Pour envoyer des données d’événements à la plateforme serverside Commanders Act, 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 / workspace / 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 analytics exemptée de consentement. Dans ce cas, vous pouvez activer l’option `exemptMode` . Lorsqu’il est activé, 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 en utilisant 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 remplacement 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 de manière sélective 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 permet un contrôle total sur la manière dont chaque événement est collecté. #### Quand utiliser cette option Utilisez `exemptMode` lorsque : * votre événement est envoyé avant que l’utilisateur ait donné son consentement * ou vous utilisez une configuration analytics 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 quand même être envoyé à des fins d’analytics 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 depuis TrustCommander, vous pouvez appeler l’ `consent.get` API comme ceci : ``` cact('consent.get', function(result) { if (result.consent.status === "all-on") { // Consent available for all categories. }}); ``` Les méthodes de l’API onsite 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 available for all categories. }}); ``` ## Propriétés Meta Le `meta` property inclut les métadonnées et le contexte du consentement qui a été 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) ## API Stub (optionnel) Pour une utilisation avancée, nous fournissons également un API stub qui peut être ajouté lorsque vous devez interagir avec l’API avant que les containers ou banners ne soient chargés. Ce stub est déjà inclus dans les containers et privacy banners, donc vous n’avez généralement pas besoin de l’ajouter. Le stub sert à 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’API onsite avant le chargement du JavaScript de TrustCommander. ``` 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’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 stub JavaScript plusieurs fois. ## Utiliser le JS SDK dans le 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 JS SDK, y compris les événements browser-side, les références de commandes et les variables de contexte de tag. *** ### Événements Browser-Side **Introduction** Notre nouvelle `cact('emit')` API est une nouvelle approche de `tC.event.XXX` fonctions, garantissant une gestion des événements plus sûre et plus fiable. Voici comment 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 container chargé. * **container\_**`_`**\_ready:** Déclenche un événement spécifique pour chaque`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**: déclencheur standard de soumission de formulaire. * **tag\_trigger\_clicks**: déclencheur standard de clics. * **tag\_trigger\_scroll**: déclencheur standard de scroll. * **track\_all\_events**: événement serverside 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. ```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 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 événement comme un trigger personnalisé TMS :
*** ### Référence des commandes Le container fournit un ensemble de commandes, dont certaines déclenchent des événements browser-side. 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éfinir des propriétés à fusionner avec les événements serverside envoyés via l’API trigger. ```javascript cact('setProperty', 'page_type', 'homepage'); cact('setProperty', 'user.email', 'user@example.com'); ``` **`emit` (Alias : `dispatchEvent`)** Déclencher un événement browser-side à utiliser comme trigger de tag personnalisé. ```javascript cact('emit', 'page_view', { page_type: 'homepage' }); ``` **`on` (Alias : `addEventListener`)** S’abonner à un événement browser-side. ```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 le rappel ne s’exécute qu’une seule fois. ```javascript cact('once', 'page_view', listener_callback); ``` **`off` (Alias : `removeEventListener`)** Supprimer un écouteur d’événement. ```javascript cact('off', 'page_view', listener_callback); ``` **`trigger`** Envoyer un événement serverside. 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 du 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. ```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 provenant du trigger. ```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 `from` 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 multi-containers, 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 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. **É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` **Server-Side Tracking 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é. ```javascript 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 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('received an event', event.type); // "my_custom_event" console.log('event data:', event.eventData); // { var: "value" } }); ``` --- # Agent Instructions: 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.