# Javascript SDK

## Prise en main

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` 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 disposer soit d'un web container sur la page **ou** le script de la librairie JS SDK : <https://cdn.tagcommander.com/events/sdk.js>
{% endhint %}

## Comment utiliser <a href="#how-to-use" id="how-to-use"></a>

L'API onsite consiste en 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 passées à 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 de l'API onsite.                         | Optionnel   |

L'API onsite est incluse dans chaque containers et bannières 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 workspace particulier.

{% hint style="info" %}
Cette commande est optionnelle, vous pouvez aussi définir des paramètres personnalisés directement à l'intérieur d'un[ `trigger` command](#send-event), via le paramètre d'objet config.
{% endhint %}

La commande config prend le format suivant :

```javascript
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'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 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](https://doc.commandersact.com/fr/fonctionnalites/sources/sources-catalog/web/containers))
* `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 <a href="#send-event" id="send-event"></a>

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

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

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

Exemple : pour envoyer un événement purchase :

```javascript
cact('trigger', 'purchase', {   id:'1234',  currency: 'EUR',  //...});
```

Exemple : pour envoyer un événement purchase, 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"
});
```

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

Pour obtenir diverses valeurs depuis Commanders Act, utilisez cette commande :

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

Exemple : pour obtenir le consentement depuis TrustCommander, vous pouvez appeler l'API `consent.get` 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 façon asynchrone. Dans le cas où, par exemple, vous avez besoin d'informations de façon synchrone dans le `<head>` du document, il est recommandé de mettre en cache et récupérer le résultat de l'API dans `localStorage`.

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

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

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

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

Pour un usage avancé, nous fournissons aussi un API stub qui peut être ajouté lorsque vous devez interagir avec l'API avant que les containers ou les bannières ne soient chargés. Ce stub est déjà inclus dans les containers et les bannières de confidentialité, vous n'avez donc pas à l'ajouter dans la plupart des cas. Le stub sert à mettre en buffer 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 buffer 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 Javascript SDK dans le TMS

***

Notre système inclut maintenant plusieurs fonctionnalités nouvelles et améliorées pour vous aider à gérer et implémenter efficacement les tags sur votre site. 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 des tags.

***

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

**Introduction**

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

Voici comment vous pouvez utiliser ces événements :

```html
<!-- 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' });">
```

{% 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\_**`<siteId>_<containerId>`**\_ready :** Déclenche un événement spécifique pour chaque container`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 scroll.
* **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 Trigger pour déclencher un tag sur `consent-update` événement

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

### **Écoute de tous les événements**

Vous pouvez écouter tous les événements en utilisant la `cact('on', '*')` API.

```javascript
fonction 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 trigger personnalisé dans le 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 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.

```javascript
cact('config', { siteId: 4242, collectionDomain: 'example.com', sourceKey: 'ABCD-1234-EFGH' });
```

**`setProperty`**

Définir 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éclencher un événement côté navigateur pour l'utiliser comme trigger personnalisé de tag.

```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('é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.

```javascript
cact('once', 'page_view', listener_callback);
```

**`off` (Alias : `removeEventListener`)**

Enlever 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 `track_all_events` événement générique.

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

***

### Tag Context Variables

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` trigger personnalisé.

**`cact_container`**

Contient des informations sur le container.

```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 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 en utilisant la `from` propriété dans `emit` ou `trigger` API.

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

Pour plus d'exemples et une démo en direct, référez-vous aux liens de documentation fournis.

***

### Bonnes pratiques et conseils

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

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

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

Vous pouvez utiliser différents événements 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 é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 personnalisé TMS, vous devrez préfixer le nom de l'événement par "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 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" }
});
```