> 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

## Premiers pas

L’API onsite permet d’interagir avec les fonctionnalités de Commanders Act à l’aide de JavaScript.

Plusieurs commandes sont disponibles dans `cact()`: `config` permet de définir les options générales, `trigger` permet d’envoyer des données, et d’autres commandes spécifiques `get/update/revoke` permettent d’interagir avec les fonctionnalités de la plateforme (ex. : récupérer le consentement de l’utilisateur)

{% hint style="info" %}
Pour utiliser l’API, vous devez disposer soit d’un conteneur web sur la page **ou** du script de la bibliothèque JS SDK : <https://cdn.tagcommander.com/events/sdk.js>
{% endhint %}

## Mode d’emploi <a href="#how-to-use" id="how-to-use"></a>

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 de chaîne utilisé pour sélectionner la méthode souhaitée.                                                                 | Obligatoire |
| `options`  | Un objet JavaScript qui contient 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 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 <a href="#config" id="config"></a>

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 une[ `trigger` commande](#send-event), via le paramètre objet de configuration.
{% endhint %}

La commande de configuration s’écrit au format suivant :

```javascript
cact('config', {<config_object>});
```

L’objet de configuration accepte **4 paramètres**, qui sont facultatifs si vous utilisez un conteneur web sur votre page :

* `siteId`  : si cette valeur n’est pas définie, la valeur par défaut correspond à l’ID du dernier conteneur web chargé (`tC.id_site`)
* `sourceKey` : si cette valeur n’est pas définie, la valeur par défaut est dérivée de l’ID de votre conteneur web. Si vous n’avez pas de conteneur web, le sourceKey est obligatoire et correspond à la source de votre SDK JS.
* `collectionDomain` : si cette valeur n’est pas définie, la valeur par défaut est `collect.commander1.com`  (ou votre domaine First party, si vous en avez configuré un et utilisez un [conteneur web](https://doc.commandersact.com/fr/fonctionnalites/sources/sources-catalog/web/containers.md))
* `eventId` : si cette valeur n’est pas définie, un ID aléatoire est attribué à cet événement et sera placé dans `context.event_id`

Exemple :

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

## Envoyer un événement <a href="#send-event" id="send-event"></a>

{% hint style="info" %}
Pour utiliser l’API, vous devez avoir sur la page soit un conteneur web **soit** le script de la bibliothèque JS SDK : <https://cdn.tagcommander.com/events/sdk.js>
{% endhint %}

Pour envoyer des données d’événement à la plateforme Commanders Act server-side, utilisez cette commande :

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

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, le workspace et la 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’identification)

Dans certaines configurations, vous devrez peut-être envoyer des événements sans consentement de l’utilisateur, par exemple si vous utilisez une configuration d’analytics exemptée de consentement.

Dans ce cas, vous pouvez activer l’option `exemptMode` .

Lorsqu’il est activé, Commanders Act collecte l’événement sans définir de cookies d’identification tels que `CAID`, `WID`, (ou `TCID` selon votre configuration).

#### Configuration globale

Vous pouvez activer `exemptMode` globalement à l’aide de la commande `config` .

```javascript
cact('config', {
  exemptMode: true
});
```

Tous les événements suivants envoyés avec `cact('trigger', ...)` utiliseront ce comportement par défaut, sauf si celui-ci est remplacé au niveau de l’événement.

#### Configuration par événement

Vous pouvez activer `exemptMode` uniquement pour certains événements en utilisant le paramètre de configuration de la commande `trigger` .

```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 conservant les autres en mode standard.

#### Remplacer la configuration globale

Si `exemptMode` est activé globalement, il peut tout de même être désactivé pour certains événements.

```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` lorsque :

* votre événement est envoyé avant que l’utilisateur ait donné son consentement
* ou que vous utilisiez une configuration d’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 interagisse avec la bannière de consentement, et doit tout de même être envoyé à des fins d’analytics sans définir de cookies d’identification.

***

## Obtenir des informations <a href="#get-information" id="get-information"></a>

Pour obtenir différentes valeurs de Commanders Act, utilisez cette commande :

```
cact(get command, [callback])
```

Par exemple, pour obtenir le consentement de TrustCommander, vous pouvez appeler l’API `consent.get` 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 de manière synchrone dans le `<head>` du document, il est recommandé de mettre en cache le résultat de l’API et de le récupérer depuis `localStorage`.

## Gestion des erreurs <a href="#error-handling" id="error-handling"></a>

Vous pouvez gérer les erreurs à l’aide de la propriété error de l’objet de rappel. Exemple :

```
cact('consent.get', function(result) {​    if (result.error) {            // Manage the error        }    else if (result.consent.status === "all-on") {                // Consent available for all categories.            }});
```

## Propriétés Meta

La `meta` propriété contient des métadonnées et le contexte du consentement donné dans un navigateur. Vous pouvez consulter la liste des propriétés Meta [ici](https://doc.commandersact.com/fr/fonctionnalites/consent-management/knowledge-base/consent-object.md#meta-properties)

## Stub API (facultatif) <a href="#api-stub-optional" id="api-stub-optional"></a>

Pour les usages avancés, nous proposons également un stub API que vous pouvez ajouter lorsque vous devez interagir avec l’API avant le chargement des conteneurs ou des bannières. Ce stub est déjà inclus dans les conteneurs et les bannières de confidentialité ; dans la plupart des cas, vous n’avez donc pas besoin de l’ajouter. Il 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 à les traiter. 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 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 que vous ne savez pas si le stub a déjà été installé, vous pouvez l’installer plusieurs fois.

## Utiliser le SDK JavaScript dans le TMS

***

Notre système comprend désormais plusieurs fonctionnalités nouvelles et améliorées pour vous aider à gérer et à déployer efficacement les tags sur votre site web. Ce guide fournit des informations complètes sur l’utilisation de nos webcontainers TMS et du SDK JavaScript, notamment sur les événements côté navigateur, les références des commandes et les variables de contexte des tags.

***

### Événements côté navigateur

**Introduction**

Notre nouvelle  `cact('emit')` API est une nouvelle approche des fonctions  `tC.event.XXX` , qui garantit une gestion des événements plus sûre et plus fiable.

Voici comment utiliser ces événements :

```html
<!-- Ancienne méthode (peut poser problème 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' });">
```

{% hint style="info" %}
Notez que les traits d’union (`-`) dans les noms d’événements sont remplacés par des traits de soulignement (`_`). 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\_**`<siteId>_<containerId>`**\_ready :** Déclenche un événement spécifique pour chaque container, nommé `container_ready`  (ex. :  `container_1234_1_ready`)
* **consent-ready**: Se déclenche lorsque le cookie de consentement est défini ou lorsque 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é s’affiche.
* **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é s’affiche.
* **privacy-center-hide**: Se déclenche lorsque le centre de confidentialité 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 de défilement standard.
* **track\_all\_events** : Événement server-side envoyé avec `cact('trigger')` API.
* **track\_\* :** Similaire à `track_all_events` mais avec des noms d’événement spécifiques (par exemple, `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 avec `cact('emit')`.

#### Exemple de déclencheur pour déclencher un tag sur l’événement `consent-updated` event

<figure><img src="https://3282103337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-d9fbe65f339913425cf5a080525b31160285f0a3%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### **Écouter tous les événements**

Vous pouvez écouter tous les événements à l’aide de l’ `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 commande `cact('emit', 'my_custom_event')` . Notez que les tirets sont convertis en tirets bas lors du lancement du déclencheur.

```javascript
cact('emit', 'my_custom_event');
```

Vous pourrez utiliser cet événement comme déclencheur personnalisé du TMS :

<figure><img src="https://3282103337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-88376617e6021e0b080894f905067efef9847458%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

***

### Référence des commandes

Le conteneur fournit un ensemble de commandes, dont certaines déclenchent des événements côté navigateur. Pour afficher toutes les commandes, saisissez `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éfinir les propriétés à fusionner avec les événements server-side envoyés via l’API de déclenchement.

```javascript
cact('setProperty', 'page_type', 'homepage');
cact('setProperty', 'user.email', 'user@example.com');
```

**`emit` (Alias : `dispatchEvent`)**

Déclenche un événement côté navigateur à utiliser comme déclencheur de tag personnalisé.

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

**`on` (Alias : `addEventListener`)**

S’abonner à 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 le callback n’est exécuté 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 server-side. Tout appel à `cact('trigger', ...)` déclenchera également un événement générique `track_all_events` .

```javascript
cact('trigger', 'add_to_cart', { value: 42, currency: 'EUR' });
```

***

### Variables de contexte du tag

Le contexte du tag fournit des variables utilisées au sein d’un tag. Si vous avez besoin d’un contexte de tag similaire à « Container Loaded », envisagez d’utiliser le `container_ready` déclencheur personnalisé.

**`cact_container`**

Contient des informations sur le conteneur.

```javascript
{
  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`.

```javascript
cact('emit', 'page_view', {});
// cact_event.type will be '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 will be { hello: 'world' }
```

**`cact_event_attrs`**

Contient les attributs de l’événement, définis à l’aide de la propriété `from` dans `emit` ou `trigger` API.

```html
<a href="/home" onclick="cact('emit', 'page_view', { from: this, hello: 'world' })">Accueil</a>
```

Pour plus d’exemples et une démonstration en direct, consultez les liens vers la documentation fournis.

***

### Bonnes pratiques et conseils

**Résolution des conflits entre les ID de site et les clés source**

Sur les sites Web comportant plusieurs conteneurs, des événements étaient parfois envoyés avec un ID de site ou une clé source incorrects. Ce problème est résolu pour les tags utilisant des déclencheurs autres que le déclencheur natif « Container Loaded ». Utilisez le nouveau `container_ready` déclencheur personnalisé pour résoudre correctement l’ID de site et la clé source.

**Événements liés à la confidentialité**

Vous pouvez utiliser différents é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éclencheur personnalisé**

Vous devez suivre un événement envoyé en server-side ?

Notre `cact('trigger', ...)` déclenchera un événement `track_*` 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é dans le TMS, vous devez faire précéder le nom de l’événement de « track\_\* »\
Exemple :\\

<figure><img src="https://3282103337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-42110d9b602a5abced906ab159827db3465d2a3e%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

**Utilisation de `cact('on')` pour s’abonner aux événements**

Vous pouvez vous abonner à tout événement envoyé avec `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
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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.commandersact.com/fr/fonctionnalites/sources/sources-catalog/web/js-sdk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
