> 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/developpeurs/commanders-tag-gateway.md).

# Commanders Act Gateway

Ce document décrit comment déployer **Commanders Act Gateway**, une **passerelle first-party unifiée** qui utilise **une seule configuration et un seul chemin sur votre domaine** pour répondre à plusieurs besoins de tracking et d’hébergement.

Commanders Act Gateway inclut **Google Tag Gateway**, mais ne se limite **pas à Google**.\
Cette solution est conçue pour diffuser et collecter les données de **tous vos partenaires marketing et analytiques**, en utilisant la même infrastructure first-party.

Une configuration, un chemin first-party, trois usages :

* Google Tag Gateway (GA4, Google Ads)
* Tracking first-party vers toutes les destinations server-side
* Hébergement first-party de bibliothèques Third-party

Si votre objectif est de mettre en œuvre Google Tag Gateway, vous êtes au bon endroit.\
Si vous souhaitez mettre en place une architecture de tracking first-party durable et indépendante des fournisseurs, vous êtes également au bon endroit.

<figure><img src="https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-5c269a1cb309c24a7504446eef7a53b7aafd97d9%2Fschema_google_ads%20(4).png?alt=media" alt=""><figcaption></figcaption></figure>

***

**Pourquoi utiliser Commanders Gateway ?**

**1. Avantages de l’utilisation d’une passerelle**

Une configuration de passerelle améliore **la qualité et l’exhaustivité de la collecte des données** dans l’ensemble de votre stack marketing.

* Les scripts des fournisseurs sont diffusés depuis votre propre domaine, ce qui réduit le risque qu’ils soient bloqués par des bloqueurs de publicité.
* Les restrictions des navigateurs (comme l’ITP de Safari) limitent ou bloquent souvent les cookies Third-party et certains cookies JavaScript 1st party. Avec une configuration server-side first-party, les mesures restent toutefois plus fiables.
* Cela garantit **un tracking plus précis**, en fournissant aux partenaires des signaux de meilleure qualité pour la mesure, l’attribution et l’optimisation.

**2. Avantages de l’utilisation de Commanders Gateway**

En plus des avantages de toute approche par passerelle, **Commanders Gateway** offre des avantages uniques :

* Pas limité à Google Tag Gateway : la même configuration durable s’applique à **tous vos partenaires** (Meta, Snapchat, Bing, Awin, etc.).
* Configuration unifiée : un **seul chemin** (`/mypath`) diffuse et relaie toutes les bibliothèques des fournisseurs.
* Commanders Act fournit automatiquement des noms de fichiers JavaScript obfusqués, ce qui rend leur détection par les listes de blocage beaucoup plus difficile.
* Avec le même chemin simple, vous pouvez également activer d’autres **fonctionnalités d’hébergement et de tracking first-party** telles que l’hébergement de vos conteneurs de gestion des tags, le tracking des événements server-side ou les statistiques anonymes de votre CMP. Une seule configuration alimente l’ensemble de votre système d’hébergement et de tracking first-party.
* Une configuration centralisée simplifie le déploiement et la maintenance, tout en restant **prête pour l’avenir** face aux prochaines restrictions des navigateurs.

***

**Présentation**

**Commanders Gateway** vous permet de déployer des tags marketing et de mesure à l’aide de votre **propre infrastructure first-party**, hébergée sur le domaine de votre site Web.\
Cette infrastructure se situe entre votre site Web et les services de vos partenaires (Google, Meta, Bing, Snapchat, Awin, etc.).

Avec Commanders Gateway :

* Les bibliothèques Google (gtag.js / gtm.js) sont chargées directement depuis votre **domaine First-party**.
* Les bibliothèques des autres fournisseurs sont servies depuis `/mypath/js/` à l’aide de **noms de fichiers obfusqués**.
* Toutes les requêtes de mesure transitent par votre domaine avant d’être transmises aux points de terminaison des partenaires concernés.

***

**Google Tag Gateway (GTG) et le consentement**

{% hint style="info" %}
Cette section est consacrée à la vérification des exigences relatives au Consent Mode avec Google Tag Gateway (GTG). Elle explique ce que GTG change en matière de consentement, comment vérifier l’inscription et que faire si un signal de consentement « tardif » est détecté sur un domaine inscrit à GTG.
{% endhint %}

**Ce que Google Tag Gateway change en matière de consentement**

**Google Tag Gateway (GTG) pour les annonceurs** permet à un site Web de servir les tags Google (`gtag.js`, `gtm.js`) depuis son propre domaine First-party plutôt que depuis `googletagmanager.com`, à l’aide d’un CDN, d’un répartiteur de charge ou d’un serveur Web. Commanders Act Gateway peut être utilisé pour mettre en œuvre GTG (voir [Architecture](#architecture) ci-dessous).

GTG ne change pas *ce que* fait le Consent Mode — il change **l’origine du tag Google et, surtout, le moment où il peut se charger par rapport à votre bannière de consentement**. C’est à ce niveau que le timing a un impact sur le consentement :

* **Injection automatisée du CDN en un clic** (la configuration dans l’interface proposée par Google pour Cloudflare, Akamai, Fastly ou un Google Cloud Load Balancer) permet à Google d’injecter directement la règle de routage dans la configuration de votre CDN ou de votre répartiteur de charge, en plaçant généralement le tag Google très tôt dans la page. Comme cette injection a lieu **en dehors de votre gestionnaire de tags ou du code source de la page**, vous ne pouvez généralement **plus contrôler l’ordre de chargement des scripts** par rapport à votre bannière de consentement. Si le script d’initialisation du consentement de votre CMP n’a pas encore été exécuté et n’a pas défini les états de consentement par défaut, le tag Google peut se déclencher en premier.
* **Configuration GTG manuelle / en libre-service**, où vous configurez vous-même le routage et référencez directement le script First-party dans le code source de votre page, vous permet de contrôler l’ordre de chargement des scripts : vous décidez si le tag Google ou le script de consentement de votre CMP se charge en premier.

Lorsqu’un tag Google se déclenche avant que votre CMP ait défini un état de consentement par défaut, Google parle de **signal de consentement « tardif »** : le tag s’exécute avec un état de consentement inconnu/non défini au lieu de respecter la valeur par défaut que votre CMP était censée définir. Les tags peuvent alors se comporter comme si aucun framework de consentement n’était présent, et les outils de diagnostic de Google le signalent (voir [Vérification](#verification-checklist) ci-dessous).

{% hint style="warning" %}
Revenir sur GTG n’est **pas** la solution recommandée pour corriger un signal de consentement tardif : cela vous ferait perdre les avantages de durabilité de la mesure First-party que GTG est conçu pour offrir. Les mesures correctives recommandées sont décrites dans la section [Si un signal de consentement tardif est détecté](#if-a-late-consent-signal-is-detected-and-gtg-enrollment-is-confirmed) ci-dessous.
{% endhint %}

**Documentation de Google sur GTG**

* [Google tag gateway for advertisers – présentation générale](https://developers.google.com/tag-platform/tag-manager/gateway)
* [Configurer Google tag gateway for advertisers](https://developers.google.com/tag-platform/tag-manager/gateway/setup-guide)

**Vérifier si un tag est inscrit à GTG**

Avant d’examiner un problème de consentement lié à GTG, vérifiez si le domaine est effectivement inscrit. Vous pouvez utiliser l’une des méthodes suivantes :

* **Dans l’interface utilisateur du produit Google** — Dans Google Tag Manager, accédez à **Admin → Google tag gateway**. Chaque domaine est répertorié avec un statut : `First-party` (GTG est actif), `Not started` (GTG n’a pas été activé), ou `Activated domains` pour les domaines configurés manuellement ou via un autre tag. Le même statut est disponible dans l’écran équivalent de Google Ads et Google Analytics.
* **Google Tag Assistant** — Connectez Tag Assistant au site Web, déclenchez les tags concernés et vérifiez d’où proviennent réellement les requêtes du Google tag et à quelle destination elles sont envoyées (**Summary → Output → Hits Sent**). Si les requêtes du Google tag sont acheminées vers votre propre domaine (par exemple `example.com/mypath/` ou `example.com/gtag/js`) au lieu de `www.googletagmanager.com` ou `www.google-analytics.com`, GTG est actif pour cette page.
* **Outils de développement du navigateur** — Dans l’onglet Network, vérifiez si le script et les requêtes de mesure pour `gtag.js` / `gtm.js` proviennent de votre domaine first-party plutôt que d’un domaine Google.

**Si un signal de consentement « tardif » est détecté et que l’inscription à CAGT est confirmée**

Un signal de consentement tardif apparaît généralement dans les [outils de débogage du consentement](https://developers.google.com/tag-platform/security/guides/consent-debugging) de Google (chronologie du consentement de Tag Assistant ou avertissement dans la console) lorsque le Google tag se déclenche avant la définition d’un état de consentement par défaut, ou lorsque l’état du consentement est signalé comme « inconnu » au moment du déclenchement du tag.

**Après avoir confirmé à la fois (a) la présence d’un signal de consentement tardif et (b) l’inscription de GTG sur le domaine**, Google recommande l’une des mesures correctives suivantes :

1. **Adopter Advanced Consent Mode** dans la configuration de votre CMP Commanders Act, et configurer **Data Transmission Controls** et **Global Consent Defaults** dans les paramètres de votre Google tag (Google Ads, GA4 ou Campaign Manager 360), en fonction de vos exigences de conformité. C’est le mécanisme que Google recommande spécifiquement pour les tags utilisant GTG — voir [pourquoi ci-dessous](https://claude.ai/chat/4300c170-a117-4d9d-ae3c-86117d316787#why-advanced-consent-mode-u+c-is-recommended-for-gtg).
2. **Migrer tous vos Google tags dans un seul conteneur Google Tag Manager, puis déployer ce conteneur lui-même via GTG**, au lieu d’injecter des tags gtag.js individuels. Cela centralise le contrôle de l’ordre de chargement dans GTM, de sorte que les vérifications de consentement intégrées à GTM s’appliquent à chaque Google tag du conteneur, quel que soit le routage du script du conteneur.
3. **Configurer GTG manuellement**, afin que vous — et non une injection automatisée par un CDN — contrôliez l’emplacement de la référence au script GTG first-party dans le code source de votre page, par rapport au script de la bannière de consentement Commanders Act.

{% hint style="info" %}
Ces trois options ne s’excluent pas mutuellement. Par exemple, une configuration manuelle de GTG (option 3) peut être combinée à Advanced Consent Mode (option 1) pour une résilience accrue si l’ordre de chargement est modifié par une évolution future de la page ou du CDN.
{% endhint %}

**Pourquoi Advanced Consent Mode est recommandé pour GTG**

Advanced Consent Mode est le mécanisme recommandé par Google pour les tags utilisant GTG car, contrairement à Basic Consent Mode (qui bloque simplement le tag jusqu’à ce qu’une valeur par défaut soit définie), il est **compatible avec les configurations manuelles de GTG** : il permet au Google tag de se charger et d’envoyer des pings sans cookie respectueux de la confidentialité, même lorsque le consentement est refusé ou encore inconnu, puis de passer à une mesure complète dès que le choix du visiteur est reçu — sans dépendre de l’ordre exact de chargement du script GTG et de la bannière de consentement.

Pour l’activer avec Commanders Act :

* Activez **Advanced Consent Mode** dans votre configuration Google Consent Mode de Commanders Act — voir [Google Consent Mode dans Commanders Act TMS](https://doc.commandersact.com/features/consent-management/setup-guides/tag-manager/google-consent-mode-in-commanders-act-tms) et [Google Tag Manager (GTM) – Consent Mode](https://doc.commandersact.com/features/consent-management/setup-guides/tag-manager/google-tag-manager-gtm-consent-mode).
* Activez **les contrôles de transmission des données** dans les paramètres de votre Google tag (Google Ads, GA4 ou Campaign Manager 360) afin de restreindre séparément les données publicitaires, analytiques et de diagnostic lorsque le consentement est refusé — voir [Contrôles de transmission des données](https://support.google.com/google-ads/answer/16054531).
* Définissez **les valeurs par défaut globales du consentement** pour votre Google tag afin qu’un état de consentement de base (refusé, sauf si d’autres règles sont requises) s’applique toujours à chaque région, même dans le rare cas où l’exécution du stub CMP en premier ne peut pas être garantie — voir la [section sur le comportement propre à chaque région du guide de Google sur le mode de consentement](https://developers.google.com/tag-platform/security/guides/consent#region-specific_behavior) et [les paramètres Consent Overview de GTM](https://support.google.com/tagmanager/answer/10718549?hl=en).

{% hint style="success" %}
Choisissez le bon modèle ! Si vous devez activer Google Consent Mode avec IAB TCF, utilisez nos [modèles de bannière TCF IAB](https://doc.commandersact.com/features/consent-management/user-guides/privacy-banners/banner-templates) (Footer ou Popin) et suivez les [spécifications de configuration indiquées ici](https://doc.commandersact.com/features/consent-management/setup-guides/tag-manager/google-consent-mode-in-commanders-act-tms#additional-settings)
{% endhint %}

***

**Architecture**

Avec **Commanders Gateway**, vous réservez un **chemin unique** sur votre domaine, par exemple :

```
https://example.com/mypath/
```

* **Les scripts Google** (gtag.js / gtm.js) sont chargés directement depuis `/mypath/`.
* **Les autres scripts des fournisseurs** (Meta, Snapchat, Bing, Awin, etc.) sont servis depuis `/mypath/js/` avec un **nom de fichier obfusqué** généré par Commanders Act.

Exemple :

```
https://example.com/mypath/js/f4558899203.js
```

La correspondance entre chaque fournisseur et le nom de son script obfusqué est indiquée dans l’ **interface First-Party Hosting de Commanders Act**.

**Schéma (conceptuel) :**

```
Site Web  →  example.com/mypath/ (Google tags)
         →  example.com/mypath/js/f4558899203.js (Meta, Snap, Bing…)
         →  Commanders Gateway  →  point de terminaison du fournisseur
```

***

**Filtrage et gouvernance des cookies**

Certaines organisations, en particulier celles qui appliquent des politiques de confidentialité strictes, peuvent s’inquiéter de l’envoi de **cookies first-party à des partenaires externes** tels que Google. Commanders Gateway prend en charge la **minimisation des données** et fournit des mécanismes permettant de contrôler les cookies qui peuvent transiter par la gateway. Deux approches complémentaires peuvent être utilisées :

**Liste de blocage des cookies en périphérie**

Les clients peuvent filtrer les cookies **directement au niveau du CDN ou de la couche edge** (Cloudflare Worker, Fastly Compute, etc.). Cela peut être fait en **configurant simplement le code Worker fourni dans ce guide** (voir l’onglet Cloudflare Free ou Fastly ci-dessous) pour supprimer certains cookies avant que la requête soit transmise à Commanders Gateway.

Cela permet de supprimer certains cookies de la requête **avant qu’elle n’atteigne Commanders Gateway**, garantissant ainsi que seuls les cookies approuvés par l’organisation quittent son infrastructure.

**Liste blanche de cookies avant leur transfert aux partenaires**

Commanders Gateway peut également appliquer une **liste blanche de cookies lors du transfert des requêtes aux partenaires**.

Par exemple, lors du transfert de requêtes de mesure à Google, la passerelle peut être configurée pour **n’inclure que les cookies associés à Google** (tels que `_ga` ou `_gcl_*`).\
Tous les autres cookies sont automatiquement exclus de la requête envoyée à Google.

**Avant de commencer**

Ce guide part du principe que votre site Web est déjà configuré avec :

* Un système de gestion des tags (Commanders Act, Google Tag Manager ou équivalent).
* Un CDN ou un répartiteur de charge (Cloudflare, Akamai, Fastly, Nginx, etc.) capable de transférer des requêtes vers des points de terminaison externes.

***

**Étape 1 : choisir le chemin de diffusion des tags**

Vous devez réserver **un chemin** sur le domaine de votre site Web.

Exemple :

```
/mypath
```

Attention : cette configuration redirige tout le trafic utilisant le chemin choisi. Pour éviter d’affecter votre site Web, choisissez un chemin qui n’est pas déjà utilisé.

***

**Étape 2 : acheminer le trafic**

{% tabs %}
{% tab title="Cloudflare Enterprise" %}
Avec Cloudflare Enterprise, nous recommandons d’utiliser un **Cloudflare Worker** pour agir comme proxy pour tout le trafic provenant du chemin choisi, par exemple `/mypath`, vers l’infrastructure de Commanders Gateway.

Cette approche est la même que pour la configuration Cloudflare Free. Elle est plus fiable que d’essayer d’acheminer le chemin à l’aide des règles d’origine Cloudflare, car le Worker offre un contrôle total sur l’URL de la requête, les en-têtes, le filtrage des cookies et le transfert des données de géolocalisation.

**Étape 1 : créer le Worker**

1. Dans le tableau de bord Cloudflare, accédez à **Workers & Pages** → **Créer une application** → **Worker**.
2. Copiez-collez le code suivant :

```javascript
const prefix = "/mypath"; // Example path, replace with the path you choose in the previous step
const sid = "12345"; // Example workspace ID (aka site ID), replace with your own ID

// List of cookie names that must NOT be forwarded to Commanders Gateway. You can add your technical cookies if needed
const blacklistedCookies = [
  "PHPSESSID",
  "JSESSIONID"
];

addEventListener("fetch", event => {
  event.respondWith(handleRequest(event.request));
});

function filterCookieHeader(cookieHeader, blacklist) {
  if (!cookieHeader) return "";

  const blacklistSet = new Set(blacklist);

  const filteredCookies = cookieHeader
    .split(";")
    .map(cookie => cookie.trim())
    .filter(cookie => {
      const cookieName = cookie.split("=")[0];
      return !blacklistSet.has(cookieName);
    });

  return filteredCookies.join("; ");
}

async function handleRequest(request) {
  const url = new URL(request.url);

  if (url.pathname.startsWith(prefix)) {
    // Construct target URL. It replaces ${sid} with your workspace/site ID above.
    const targetUrl = `https://s${sid}.commander4.com${url.pathname}${url.search}`;

    // Clone request headers
    const newHeaders = new Headers(request.headers);
    newHeaders.set("X-Forwarded-Host", url.host);
    newHeaders.set("X-Forwarded-For", request.headers.get("CF-Connecting-IP"));
    newHeaders.set("X-Forwarded-Proto", "https");


    const country = request.cf?.country || "";
    const region = request.cf?.regionCode || "";

    if (country) newHeaders.set("X-Forwarded-Country", country);
    if (region) newHeaders.set("X-Forwarded-Region", region);
    if (country && region) {
      newHeaders.set("X-Forwarded-CountryRegion", `${country}-${region}`);
    }

    // Filter the Cookie header before proxying the request.
    const cookieHeader = newHeaders.get("Cookie");
    const filteredCookies = filterCookieHeader(cookieHeader, blacklistedCookies);

    if (filteredCookies) {
      newHeaders.set("Cookie", filteredCookies);
    } else {
      newHeaders.delete("Cookie");
    }

    // Remove Host header to avoid conflicts
    newHeaders.delete("host");

    // Proxy request to Commanders Gateway infra
    const proxyRequest = new Request(targetUrl, {
      method: request.method,
      headers: newHeaders,
      body: request.body,
      redirect: "manual"
    });

    const response = await fetch(proxyRequest);
    const responseHeaders = new Headers(response.headers);
    responseHeaders.delete("NEL");
    responseHeaders.delete("Report-To");

    return new Response(response.body, {
      status: response.status,
      statusText: response.statusText,
      headers: responseHeaders
    });
  }

  return new Response("Not Found", { status: 404 });
}
```

Ce Worker relaie les requêtes en ajoutant des en-têtes supplémentaires :

* `X-Forwarded-Host`
* `X-Forwarded-Country`
* `X-Forwarded-Region`
* `X-Forwarded-CountryRegion`

Il peut également filtrer les cookies sensibles ou techniques avant de transférer la requête vers Commanders Gateway.

**Étape 2 : associer le Worker au chemin**

1. Dans Cloudflare, ouvrez les paramètres de votre domaine.
2. Accédez à **Workers Routes**.
3. Ajoutez une nouvelle route avec les paramètres suivants :
   * **Modèle d’URL**: `www.example.com/mypath*`
   * **Worker**: sélectionnez le Worker créé à l’étape 1.

Une fois la configuration enregistrée, toutes les requêtes vers `/mypath` seront redirigées via un proxy vers Commanders Gateway.

**Étape 3 : vérifier la configuration**

Vous pouvez vérifier la configuration en accédant à l’adresse suivante :

```
https://example.com/mypath/g/healthy
```

Remarque : le sous-chemin Google par défaut est /g/, mais il peut être personnalisé. Il se trouve immédiatement après /mypath/.

La réponse doit être :

```
ok
```

Pour vérifier le transfert des données de géolocalisation, vous pouvez également tester :

```
https://example.com/mypath/g/?validate_geo=healthy
```

La réponse doit également être :

```
ok
```

Le proxy transmet l’adresse IP du visiteur depuis l’en-tête Cloudflare `CF-Connecting-IP` via `X-Forwarded-For`. Il utilise `request.cf.regionCode` pour le code de région ISO. Les redirections sont renvoyées au navigateur au lieu d’être suivies à la périphérie du réseau.

**Vérifier le transfert de l’adresse IP et de la localisation du visiteur**

Ouvrez `https://example.com/mypath/debug/`, en utilisant le domaine de votre propre site web et le préfixe Gateway. Vérifiez les champs sous `computed`:

* `behindClientProxy` doit être égal à `true`.
* `clientIpSource` doit être égal à `"x-forwarded-for"` (ou à `"true-client-ip"` si vous utilisez cet en-tête).
* `countryRegionSource` doit identifier les en-têtes `x-forwarded-*` normalement `"x-forwarded-countryregion"` lorsque l’en-tête combiné est fourni.

Vérifiez que l’adresse IP et le pays/la région calculés correspondent au visiteur, et non au proxy. Utilisez des codes ISO, par exemple le pays `FR`, la région `IDF` et la valeur combinée `FR-IDF`. Un nom de région complet tel que `Île-de-France` est ignoré. Si aucune adresse IP ou localisation exploitable du visiteur n’est transmise, le Gateway utilise l’adresse IP ou la localisation du proxy. Une vérification de l’état de santé réussie ne suffit pas à confirmer la transmission de l’adresse IP et de la localisation du visiteur.
{% endtab %}

{% tab title="Cloudflare Snippet" %}
Cloudflare Snippets constituent une solution plus légère qu’un Worker complet pour transférer le chemin du Commanders Gateway. Un Snippet exécute du JavaScript à la périphérie du réseau et est associé à une **règle Snippet** qui détermine les requêtes auxquelles il s’applique.

{% hint style="info" %}
Cloudflare Snippets sont disponibles avec les offres **Pro, Business et Enterprise** . Le nom d’hôte utilisé pour le gateway doit être configuré en proxy via Cloudflare.
{% endhint %}

**Étape 1 : créer le Snippet**

1. Dans le Dashboard Cloudflare, ouvrez votre domaine.
2. Accédez à **Règles** → **Snippets**.
3. Créez un Snippet et donnez-lui un nom descriptif, par exemple `Commanders Gateway`.
4. Collez le code suivant :

```javascript
const CONFIG = {
  prefix: "/mypath", // Replace with the gateway path chosen for your website
  targetBase: "https://s1234.commander4.com", // Replace 1234 with your workspace/site ID
  blacklistedCookies: [
    "PHPSESSID",
    "JSESSIONID"
  ]
};

function filterCookieHeader(cookieHeader, blacklist) {
  if (!cookieHeader) return "";
  const blacklistSet = new Set(blacklist);
  return cookieHeader
    .split(";")
    .map(c => c.trim())
    .filter(c => {
      const name = c.split("=")[0].trim();
      return !blacklistSet.has(name);
    })
    .join("; ");
}

export default {
  async fetch(request) {
    const url = new URL(request.url);

    if (!url.pathname.startsWith(CONFIG.prefix)) {
      return new Response("Not Found", { status: 404 });
    }

    const remainingPath = url.pathname.slice(CONFIG.prefix.length) || "/";
    const targetUrl = `${CONFIG.targetBase}${CONFIG.prefix}${remainingPath}${url.search}`;

    const newHeaders = new Headers(request.headers);

    newHeaders.set("X-Forwarded-Host", url.host);
    newHeaders.set("X-Forwarded-For", request.headers.get("CF-Connecting-IP"));

    newHeaders.set("X-Forwarded-Proto", "https");

    const country = request.cf?.country || "";
    const region = request.cf?.regionCode || "";
    if (country) newHeaders.set("X-Forwarded-Country", country);
    if (region) newHeaders.set("X-Forwarded-Region", region);
    if (country && region) {
      newHeaders.set("X-Forwarded-CountryRegion", `${country}-${region}`);
    }

    const cookieHeader = newHeaders.get("Cookie");
    const filteredCookies = filterCookieHeader(cookieHeader, CONFIG.blacklistedCookies);
    if (filteredCookies) {
      newHeaders.set("Cookie", filteredCookies);
    } else {
      newHeaders.delete("Cookie");
    }

    newHeaders.delete("host");

    const proxyRequest = new Request(targetUrl, {
      method: request.method,
      headers: newHeaders,
      body: request.body,
      redirect: "manual"
    });

    const response = await fetch(proxyRequest);

    if (response.status >= 300 && response.status < 400) {
      return new Response(response.body, {
        status: response.status,
        headers: response.headers
      });
    }

    return response;
  }
};
```

**Étape 2 : personnaliser la configuration**

Mettez à jour les valeurs en haut du Snippet :

* `prefix`: remplacez `/mypath` avec le chemin réservé à Commanders Gateway sur votre domaine.
* `targetBase`: remplacez `s1234.commander4.com` par le point de terminaison Commanders Gateway associé à l’ID de votre espace de travail/site.
* `blacklistedCookies`: ajoutez tous les cookies de session, sensibles ou internes qui ne doivent pas être transférés à Commanders Gateway.

Le Snippet transmet également le pays et la région du visiteur via `X-Forwarded-Country`, `X-Forwarded-Region`, et `X-Forwarded-CountryRegion`.

Les réponses de redirection de Commanders Gateway sont volontairement renvoyées au navigateur au lieu d’être suivies automatiquement à la périphérie du réseau.

**Étape 3 : configurer la règle du Snippet**

Associez le Snippet à une règle qui ne correspond qu’à votre chemin Commanders Gateway.

Par exemple, dans l’éditeur d’expressions :

```
starts_with(http.request.uri.path, "/mypath")
```

Remplacez `/mypath` par le même chemin configuré dans `CONFIG.prefix`.

{% hint style="warning" %}
Veillez à synchroniser la règle du Snippet et `CONFIG.prefix` . Si les chemins diffèrent, les requêtes risquent de ne pas être relayées comme prévu.
{% endhint %}

Déployez le Snippet après l’avoir testé avec les outils d’aperçu de Cloudflare.

**Étape 4 : vérifier la configuration**

Après le déploiement, vérifiez que :

* `https://example.com/mypath/healthy` → renvoie `ok`.
* `https://example.com/mypath/?validate_geo=healthy` → renvoie `ok` si la transmission des données de géolocalisation est correctement configurée.
* Les cookies répertoriés dans `blacklistedCookies` ne figurent plus dans les requêtes reçues par Commanders Gateway, tandis que les autres cookies sont conservés.

Le proxy transmet l’adresse IP du visiteur depuis l’en-tête Cloudflare `CF-Connecting-IP` via `X-Forwarded-For`. Il utilise `request.cf.regionCode` pour le code de région ISO. Les redirections sont renvoyées au navigateur au lieu d’être suivies à la périphérie du réseau.

**Vérifier le transfert de l’adresse IP et de la localisation du visiteur**

Ouvrez `https://example.com/mypath/debug/`, en utilisant le domaine de votre propre site web et le préfixe Gateway. Vérifiez les champs sous `computed`:

* `behindClientProxy` doit être égal à `true`.
* `clientIpSource` doit être égal à `"x-forwarded-for"` (ou à `"true-client-ip"` si vous utilisez cet en-tête).
* `countryRegionSource` doit identifier les en-têtes `x-forwarded-*` normalement `"x-forwarded-countryregion"` lorsque l’en-tête combiné est fourni.

Vérifiez que l’adresse IP et le pays/la région calculés correspondent au visiteur, et non au proxy. Utilisez des codes ISO, par exemple le pays `FR`, la région `IDF` et la valeur combinée `FR-IDF`. Un nom de région complet tel que `Île-de-France` est ignoré. Si aucune adresse IP ou localisation exploitable du visiteur n’est transmise, le Gateway utilise l’adresse IP ou la localisation du proxy. Une vérification de l’état de santé réussie ne suffit pas à confirmer la transmission de l’adresse IP et de la localisation du visiteur.
{% endtab %}

{% tab title="Cloudflare Free" %}
Avec Cloudflare Free, la configuration repose sur un **Worker simple** qui relaie tout le trafic provenant du chemin choisi (par exemple, `/mypath`) vers l’infrastructure Commanders Gateway.

**Étape 1 : créer le Worker**

1. Dans le tableau de bord Cloudflare, accédez à **Workers & Pages** → **Créer une application** → **Worker**.
2. Copiez-collez le code suivant :

```javascript
const prefix = "/mypath"; // Example path, replace with the path you choose in the previous step
const sid = "12345"; // Example workspace ID (aka site ID), replace with your own ID

// List of cookie names that must NOT be forwarded to Commanders Gateway. You can add your technical cookies if needed
const blacklistedCookies = [
  "PHPSESSID",
  "JSESSIONID"
];

addEventListener("fetch", event => {
  event.respondWith(handleRequest(event.request));
});

function filterCookieHeader(cookieHeader, blacklist) {
  if (!cookieHeader) return "";

  const blacklistSet = new Set(blacklist);

  const filteredCookies = cookieHeader
    .split(";")
    .map(cookie => cookie.trim())
    .filter(cookie => {
      const cookieName = cookie.split("=")[0];
      return !blacklistSet.has(cookieName);
    });

  return filteredCookies.join("; ");
}

async function handleRequest(request) {
  const url = new URL(request.url);
  if (url.pathname.startsWith(prefix)) {
    // Construct target URL (it replaces ${sid} with your workspace/site ID above)
    const targetUrl = `https://s${sid}.commander4.com${url.pathname}${url.search}`;

    // Clone request headers
    const newHeaders = new Headers(request.headers);
    newHeaders.set("X-Forwarded-Host", url.host);
    newHeaders.set("X-Forwarded-For", request.headers.get("CF-Connecting-IP"));
    newHeaders.set("X-Forwarded-Proto", "https");


    const country = request.cf?.country || "";
    const region = request.cf?.regionCode || "";
    if (country) newHeaders.set("X-Forwarded-Country", country);
    if (region) newHeaders.set("X-Forwarded-Region", region);
    if (country && region) {
      newHeaders.set("X-Forwarded-CountryRegion", `${country}-${region}`);
    }

    // Filter the Cookie header before proxying the request.
    const cookieHeader = newHeaders.get("Cookie");
    const filteredCookies = filterCookieHeader(cookieHeader, blacklistedCookies);

    if (filteredCookies) {
      newHeaders.set("Cookie", filteredCookies);
    } else {
      newHeaders.delete("Cookie");
    }

    // Remove Host header to avoid conflicts
    newHeaders.delete("host");

    // Proxy request to Commanders Gateway infra
    const proxyRequest = new Request(targetUrl, {
      method: request.method,
      headers: newHeaders,
      body: request.body,
      redirect: "manual"
    });
    const response = await fetch(proxyRequest);
    const responseHeaders = new Headers(response.headers);
    responseHeaders.delete("NEL");
    responseHeaders.delete("Report-To");

    return new Response(response.body, {
      status: response.status,
      statusText: response.statusText,
      headers: responseHeaders
    });
  }
  return new Response("Not Found", { status: 404 }); // Return 404 if request path does not match prefix
}
```

Ce Worker relaie les requêtes tout en ajoutant des en-têtes supplémentaires (`X-Forwarded-Host`, `X-Forwarded-Country`, `X-Forwarded-Region`).

**Étape 2 : associer le Worker au chemin**

1. Dans Cloudflare, ouvrez les paramètres de votre domaine.
2. Accédez à **Workers Routes**.
3. Ajoutez une nouvelle route avec les paramètres suivants :
   * **Modèle d’URL**: `www.example.com/mypath*`
   * **Worker**: sélectionnez le Worker créé à l’étape 1.

Une fois la configuration enregistrée, toutes les requêtes vers `/mypath` seront redirigées via un proxy vers Commanders Gateway.

Le proxy transmet l’adresse IP du visiteur depuis l’en-tête Cloudflare `CF-Connecting-IP` via `X-Forwarded-For`. Il utilise `request.cf.regionCode` pour le code de région ISO. Les redirections sont renvoyées au navigateur au lieu d’être suivies à la périphérie du réseau.

**Vérifier le transfert de l’adresse IP et de la localisation du visiteur**

Ouvrez `https://example.com/mypath/debug/`, en utilisant le domaine de votre propre site web et le préfixe Gateway. Vérifiez les champs sous `computed`:

* `behindClientProxy` doit être égal à `true`.
* `clientIpSource` doit être égal à `"x-forwarded-for"` (ou à `"true-client-ip"` si vous utilisez cet en-tête).
* `countryRegionSource` doit identifier les en-têtes `x-forwarded-*` normalement `"x-forwarded-countryregion"` lorsque l’en-tête combiné est fourni.

Vérifiez que l’adresse IP et le pays/la région calculés correspondent au visiteur, et non au proxy. Utilisez des codes ISO, par exemple le pays `FR`, la région `IDF` et la valeur combinée `FR-IDF`. Un nom de région complet tel que `Île-de-France` est ignoré. Si aucune adresse IP ou localisation exploitable du visiteur n’est transmise, le Gateway utilise l’adresse IP ou la localisation du proxy. Une vérification de l’état de santé réussie ne suffit pas à confirmer la transmission de l’adresse IP et de la localisation du visiteur.
{% endtab %}

{% tab title="CloudFront" %}
Utilisez votre distribution CloudFront existante pour acheminer le chemin First-party réservé vers Commanders Act Gateway. Dans les exemples ci-dessous, remplacez `mypath` par votre préfixe Gateway et `1234` par l’ID de votre espace de travail/site Commanders Act.

**Étape 1 : créer l’origine Gateway**

1. Ouvrez votre distribution et accédez à **Origines** → **Créer une origine**.
2. Définissez **Domaine de l’origine** sur `s1234.commander4.com`, sans protocole ni chemin.
3. Laissez le champ **Chemin de l’origine** vide. Le chemin complet de la requête, y compris `/mypath`, doit parvenir à la Gateway sans modification.
4. Utilisez **HTTPS uniquement** pour la connexion à l’origine, sur le port **443**.
5. Enregistrez l’origine.

**Étape 2 : créer le comportement Gateway**

Accédez à **Comportements** → **Créer un comportement** et configurez les éléments suivants :

| Paramètre                      | Valeur requise                                               |
| ------------------------------ | ------------------------------------------------------------ |
| Modèle de chemin               | `/mypath/*`, ou `/<prefix>/*` pour le préfixe de votre choix |
| Origine                        | L’origine Gateway créée ci-dessus                            |
| Règle de protocole du visiteur | Rediriger HTTP vers HTTPS                                    |
| Méthodes HTTP autorisées       | **GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE**             |
| Règle de cache                 | **Managed-CachingDisabled**                                  |
| Règle de requête à l’origine   | **Managed-AllViewerExceptHostHeader**                        |

Placez ce comportement avant tout modèle plus général susceptible de correspondre aux requêtes Gateway.

{% hint style="warning" %}
Le suffixe `/*` dans le modèle de chemin est obligatoire. `/mypath` seul ne correspond qu'à cette URL exacte : les requêtes telles que `/mypath/js/...`, `/mypath/cdp/...` et `/mypath/g/...` seraient acheminées vers votre site Web au lieu de l'être vers le Gateway.

Sélectionnez la liste complète des méthodes HTTP autorisées. Les événements utilisent **POST** et les requêtes de pré-vérification CORS du navigateur utilisent **OPTIONS**. N'autoriser que GET et HEAD les bloque.
{% endhint %}

**Managed-AllViewerExceptHostHeader** transmet tous les en-têtes du viewer à l'exception de `Host`, toutes les chaînes de requête, tous les cookies, ainsi que les en-têtes CloudFront relatifs au protocole, à l'appareil et à la localisation, notamment `CloudFront-Viewer-Country` et `CloudFront-Viewer-Country-Region`. CloudFront définit le `Host` de la requête à l'origine sur `s1234.commander4.com`.

{% hint style="warning" %}
N'utilisez pas **Managed-AllViewer** ni de stratégie de requête à l'origine personnalisée pour le comportement Gateway. L'ancienne stratégie personnalisée `metrics-proxy-headers` n'est plus nécessaire.

Une stratégie personnalisée utilisant **Tous les en-têtes du viewer et les en-têtes CloudFront suivants** transmet le Host du site Web, ce qui empêche l'origine Gateway de fonctionner correctement. Une stratégie personnalisée utilisant **Tous les en-têtes du viewer, à l'exception de** ne permet pas d'ajouter les en-têtes de localisation CloudFront, ce qui empêche la transmission des données de géolocalisation.
{% endhint %}

**Étape 3 : créer et associer la CloudFront Function requise**

La fonction conserve le nom d'hôte du site Web dans `x-forwarded-host` avant que CloudFront ne remplace `Host` par le nom d'hôte de l'origine Gateway. Elle copie également les en-têtes CloudFront de pays et de région disponibles dans les en-têtes de transfert Gateway.

1. Dans **CloudFront** → **Functions**, créez une fonction avec le runtime JavaScript **2.0**.
2. Collez le code suivant :

```javascript
function handler(event) {
  var request = event.request;
  var headers = request.headers;

  // Conserver le nom d'hôte du site Web sans modifier l'en-tête Host en lecture seule.
  headers['x-forwarded-host'] = { value: headers.host.value };

  // Remplacer les en-têtes de transfert fournis par le viewer par les données de localisation CloudFront.
  delete headers['x-forwarded-country'];
  delete headers['x-forwarded-region'];
  delete headers['x-forwarded-countryregion'];

  var country = headers['cloudfront-viewer-country'];
  var region = headers['cloudfront-viewer-country-region'];

  if (country && country.value) {
    headers['x-forwarded-country'] = { value: country.value };
  }
  if (region && region.value) {
    headers['x-forwarded-region'] = { value: region.value };
  }
  if (country && country.value && region && region.value) {
    headers['x-forwarded-countryregion'] = {
      value: country.value + '-' + region.value
    };
  }

  // Gardez l’URI complète et la chaîne de requête inchangées.
  return request;
}
```

3. Enregistrez, testez et **publiez** la fonction.
4. Modifiez le comportement `/mypath/*` . Sous **Associations de fonctions**, associez la fonction publiée à **Viewer request**.
5. Enregistrez le comportement et attendez la fin du déploiement de la distribution.

{% hint style="warning" %}
La fonction Viewer request est obligatoire. N’ajoutez pas `x-forwarded-proto` à cette fonction : AWS interdit cet en-tête dans les fonctions edge et renvoie **502 Bad Gateway** si la fonction le définit. Le Gateway utilise HTTPS par défaut. Ne modifiez pas l’en-tête en lecture seule `Host` dans la fonction.
{% endhint %}

CloudFront ajoute automatiquement l’IP du visiteur à `X-Forwarded-For`. Avec la stratégie de requête à l’origine et la fonction Viewer request ci-dessus, le Gateway utilise l’IP transférée du visiteur ainsi que les codes de pays/région disponibles pour les requêtes de collecte Google et Commanders Act. Il n’est pas nécessaire d’ajouter la gestion des IP à la fonction.

**Étape 4 : vérifier la configuration complète**

1. Ouvrez `https://example.com/mypath/debug/`, en remplaçant le domaine et le préfixe par vos propres valeurs.
2. Dans les en-têtes renvoyés, vérifiez que :
   * `headers.host` est égal à `s1234.commander4.com` (l’ID de votre espace de travail/site).
   * `x-forwarded-host` est égal à `example.com` (le nom d’hôte de votre site Web).
   * Lorsque les données de localisation CloudFront sont disponibles, `x-forwarded-country`, `x-forwarded-region` et `x-forwarded-countryregion` contiennent les valeurs correspondantes.
3. Vérifiez `https://example.com/mypath/healthy` : il doit renvoyer `ok`.
4. Déclenchez un événement de test via votre intégration de suivi configurée. Dans les outils de développement du navigateur, confirmez que la requête **POST** utilise votre domaine et votre préfixe First-party, atteint le Gateway et apparaît dans l’inspecteur d’événements ou la destination attendue.
5. Testez une requête préliminaire **OPTIONS** vers le même endpoint d’événement, avec l’Origin réel du site Web et les en-têtes utilisés par la requête POST. Confirmez qu’elle atteint le Gateway et que la réponse CORS autorise la requête.

Ne vous arrêtez pas après le contrôle de santé : les requêtes POST et OPTIONS doivent également fonctionner avant l’activation.

**Dépannage**

* Les requêtes correspondant au préfixe atteignent votre site Web : vérifiez `/<prefix>/*` et la priorité des comportements.
* Les requêtes POST ou OPTIONS sont rejetées : vérifiez la liste complète des méthodes HTTP autorisées.
* La réponse de débogage affiche votre site Web dans `headers.host` : sélectionnez **Managed-AllViewerExceptHostHeader**.
* `x-forwarded-host` est absent : publiez et associez la fonction à **Viewer request** pour le comportement du Gateway.
* CloudFront renvoie une erreur 502 après l’association de la fonction : vérifiez qu’elle ne définit pas `x-forwarded-proto` et ne modifie pas `Host`.

Références AWS : [Managed origin request policies](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-origin-request-policies.html) et [Restrictions on edge functions](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/edge-function-restrictions-all.html).

**Vérifier le transfert de l’adresse IP et de la localisation du visiteur**

Ouvrez `https://example.com/mypath/debug/`, en utilisant le domaine de votre propre site web et le préfixe Gateway. Vérifiez les champs sous `computed`:

* `behindClientProxy` doit être égal à `true`.
* `clientIpSource` doit être égal à `"x-forwarded-for"` (ou à `"true-client-ip"` si vous utilisez cet en-tête).
* `countryRegionSource` doit identifier les en-têtes `x-forwarded-*` normalement `"x-forwarded-countryregion"` lorsque l’en-tête combiné est fourni.

Vérifiez que l’adresse IP et le pays/la région calculés correspondent au visiteur, et non au proxy. Utilisez des codes ISO, par exemple le pays `FR`, la région `IDF` et la valeur combinée `FR-IDF`. Un nom de région complet tel que `Île-de-France` est ignoré. Si aucune adresse IP ou localisation exploitable du visiteur n’est transmise, le Gateway utilise l’adresse IP ou la localisation du proxy. Une vérification de l’état de santé réussie ne suffit pas à confirmer la transmission de l’adresse IP et de la localisation du visiteur.
{% endtab %}

{% tab title="Akamai" %}
{% hint style="warning" %}
Commanders Gateway avec Akamai est en **bêta**. Si vous avez une question ou rencontrez un problème avec votre configuration, contactez le support
{% endhint %}

**Créer la règle de redirection**

1. Créez une nouvelle version de votre configuration de diffusion dans **Property Manager**.
2. Dans la section **Property Configuration Settings** ajoutez une nouvelle règle :
   * Nommez-la : *Route measurement*
3. Ajoutez un nouveau **Match**:
   * Type de correspondance : `Path`
   * Condition : *est l’un de*
   * Valeur : `/mypath/*`
4. Ajouter un nouveau **comportement**:
   * Sélectionnez *Comportement de propriété standard* et choisissez le **serveur d’origine** comportement.
   * Définissez **Origin Server Hostname** sur `s1234.commander4.com.`
   * Définissez **Forward Host Header** sur *Origin Hostname*.
5. Enregistrez la nouvelle règle et déployez vos modifications.
   * ⚠️ Testez la règle de redirection dans votre **environnement de staging** avant le déploiement en production.
   * Assurez-vous qu’aucune autre règle ne modifie ou ne supprime les en-têtes de réponse sortants (par exemple, *Content-Type*), car cela pourrait empêcher les scripts de fonctionner.

***

**Transmettre l’adresse IP du visiteur, le nom d’hôte du site web et le protocole**

Dans la règle du Gateway, configurez la requête sortante vers l’origine pour inclure :

| En-tête             | Valeur                                                              |
| ------------------- | ------------------------------------------------------------------- |
| `X-Forwarded-Host`  | Le nom d’hôte d’origine du site web, issu de la requête du visiteur |
| `X-Forwarded-Proto` | `https` pour le site web HTTPS                                      |
| `X-Forwarded-For`   | L’adresse IP du visiteur, ajoutée par Akamai à la chaîne sortante   |

Si vous utilisez `True-Client-IP` à la place, configurez Akamai pour qu’il renseigne ce champ avec l’adresse IP du visiteur. Utilisez l’adresse IP déterminée par Akamai, plutôt qu’une valeur fournie par le navigateur. Laissez **Forward Host Header** défini sur **Origin Hostname**.

**Inclure les informations de géolocalisation**

1. Accédez à la section **Property Variables** et ajoutez les variables suivantes :

| Nom de la variable | Paramètres de sécurité |
| ------------------ | ---------------------- |
| USER\_REGION       | Masqué                 |
| USER\_COUNTRY      | Masqué                 |

2. Choisissez votre **règle de redirection** (créée ci-dessus) dans les paramètres de configuration de la propriété.
3. Ajoutez deux nouveaux **comportements** (un par variable) :

| Variable              | Créer une valeur à partir de | Obtenir les données depuis | Champ Edgescape | Opération |
| --------------------- | ---------------------------- | -------------------------- | --------------- | --------- |
| PMUSER\_USER\_REGION  | Extraire                     | Données Edgescape          | Code de région  | Aucun     |
| PMUSER\_USER\_COUNTRY | Extraire                     | Données Edgescape          | Code pays       | Aucun     |

4. Ajoutez deux nouveaux **Modifier l’en-tête de requête sortant** comportements :

| Action  | Sélectionner le nom de l’en-tête | Nom d’en-tête personnalisé | Valeur de l’en-tête            |
| ------- | -------------------------------- | -------------------------- | ------------------------------ |
| Ajouter | Autre...                         | X-Forwarded-Region         | {{user.PMUSER\_USER\_REGION}}  |
| Ajouter | Autre...                         | X-Forwarded-Country        | {{user.PMUSER\_USER\_COUNTRY}} |

Utilisez le **code de région** (code de subdivision ISO), et non le nom de la région. Transmettez le pays et la région séparément, comme indiqué ci-dessus, ou fournissez leur valeur combinée via `X-Forwarded-CountryRegion` (par exemple `FR-IDF`).

5. Enregistrez la nouvelle règle et déployez vos modifications.

***

**Filtrer les cookies avant de les transférer vers Commanders Gateway**

Vous pouvez empêcher le transfert de certains cookies vers Commanders Gateway. Cela peut être utile pour les cookies de session, les cookies contenant des informations sensibles ou les cookies techniques internes qui ne doivent pas quitter votre infrastructure.

La liste des cookies à exclure dépend des exigences de votre organisation.

**Option 1 : utiliser les fonctionnalités de gestion des cookies d’Akamai**

Si des comportements de gestion des cookies sont disponibles dans votre configuration Akamai, configurez Akamai pour supprimer les cookies concernés de la requête avant son transfert vers Commanders Gateway.

Par exemple, vous pouvez vouloir exclure des cookies tels que :

```
PHPSESSID
JSESSIONID
```

Configurez le comportement de façon à ce que ces cookies soient supprimés de la **requête client envoyée à l’origine**, où l’origine correspond à votre point de terminaison Commanders Gateway.

{% hint style="info" %}
Le nom exact et la disponibilité des comportements de gestion des cookies d’Akamai peuvent varier selon les produits Akamai activés sur votre compte.
{% endhint %}

**Option 2 : modifier l’en-tête Cookie sortant**

Si les fonctionnalités de gestion des cookies ne sont pas disponibles, vous pouvez utiliser un **Modifier l’en-tête de requête sortante** comportement de l’en-tête `Cookie` et supprimer les cookies sélectionnés à l’aide d’une expression régulière.

Exemple pour `PHPSESSID` et `JSESSIONID`:

```regex
(?:^|;\s*)(PHPSESSID|JSESSIONID)=[^;]*
```

Configurer :

* **En-tête :** `Cookie`
* **Action :** Remplacement par expression régulière
* **Expression régulière :** l’expression ci-dessus, adaptée à votre liste de cookies
* **Remplacement :** vide

{% hint style="warning" %}
Testez soigneusement cette configuration avant de la déployer en production. Une expression régulière incorrecte peut entraîner un en-tête `Cookie` mal formé ou supprimer involontairement des cookies qui devraient être transmis.
{% endhint %}

Si vous utilisez plusieurs configurations CDN ou edge pour la même implémentation, veillez à ce que la liste des cookies exclus soit cohérente dans chacune d’elles.

***

**Vérifier la configuration**

Après avoir déployé la configuration Akamai :

* Accédez à `https://example.com/mypath/healthy` → devrait afficher `ok`.
* Tester les en-têtes de géolocalisation : `https://example.com/mypath/?validate_geo=healthy` → devrait également afficher `ok`.
* Vérifiez que les requêtes transmises à Commanders Gateway ne contiennent plus les noms des cookies exclus, tandis que les autres cookies sont toujours transmis normalement.

**Vérifier le transfert de l’adresse IP et de la localisation du visiteur**

Ouvrez `https://example.com/mypath/debug/`, en utilisant le domaine de votre propre site web et le préfixe Gateway. Vérifiez les champs sous `computed`:

* `behindClientProxy` doit être égal à `true`.
* `clientIpSource` doit être égal à `"x-forwarded-for"` (ou à `"true-client-ip"` si vous utilisez cet en-tête).
* `countryRegionSource` doit identifier les en-têtes `x-forwarded-*` normalement `"x-forwarded-countryregion"` lorsque l’en-tête combiné est fourni.

Vérifiez que l’adresse IP et le pays/la région calculés correspondent au visiteur, et non au proxy. Utilisez des codes ISO, par exemple le pays `FR`, la région `IDF` et la valeur combinée `FR-IDF`. Un nom de région complet tel que `Île-de-France` est ignoré. Si aucune adresse IP ou localisation exploitable du visiteur n’est transmise, le Gateway utilise l’adresse IP ou la localisation du proxy. Une vérification de l’état de santé réussie ne suffit pas à confirmer la transmission de l’adresse IP et de la localisation du visiteur.
{% endtab %}

{% tab title="Fastly" %}
{% hint style="warning" %}
La prise en charge de Commanders Gateway par Fastly est actuellement en **bêta**. Les étapes ci-dessous s’adressent aux utilisateurs techniques familiarisés avec Fastly Compute (Compute Services). Selon la configuration de votre compte Fastly (domaines, TLS, produits activés), certaines étapes de liaison en production peuvent varier.
{% endhint %}

Avec Fastly, la configuration diffère de celle de Cloudflare. Vous déployez un **service Compute** (Wasm) et le configurez principalement via l’ **API et la CLI Fastly** depuis un terminal.

**Prérequis**

1. Créez un jeton API dans l’interface Fastly (les autorisations doivent permettre l’accès à Compute, aux services, aux backends et aux déploiements).
2. Exportez le jeton dans l’environnement de votre terminal :

```
export FASTLY_API_TOKEN=XXXXXXXXXXXX
```

3. Installez les prérequis :

* Node.js
* Fastly CLI

**Étape 1 : créer le service Compute**

Créer un nouveau service Compute :

```
fastly service create --name "CA Gateway" --type wasm
```

Fastly renvoie un **ID de service**, par exemple :

```
dyBxiT8wpc2c8ZQg2KRrMN
```

Enregistrez-le : vous en aurez besoin pour créer le backend et effectuer les déploiements.

**Étape 2 : créer un projet Compute local (kit de démarrage)**

Générez un projet local à partir du kit de démarrage JavaScript par défaut :

```
npm create @fastly/compute@latest -- --language=javascript --default-starter-kit
```

Cela crée une structure de projet similaire à celle-ci :

```
.
├── README.md
├── fastly.toml
├── package.json
└── src
    ├── index.js
    └── welcome-to-compute.html
```

**Étape 3 : configurer l’ID de service dans fastly.toml**

Modifiez `fastly.toml` et définissez l’ID de service :

```
# fastly.toml
service_id = "YOUR_SERVICE_ID"
```

**Étape 4 : créer le backend (origine Commanders Gateway)**

Créez un backend pointant vers l’infrastructure Commanders Gateway (remplacez `1234` par l’ID de votre espace de travail/site) :

```
fastly backend create \
  --service-id YOUR_SERVICE_ID \
  --version 1 \
  --name commander_gateway \
  --address s1234.commander4.com \
  --use-ssl \
  --port 443 \
  --ssl-sni-hostname s1234.commander4.com
```

Remarques :

* `--version 1` est un point de départ courant. Si votre service possède déjà des versions, utilisez celle que vous comptez déployer.
* L’adresse du backend doit être `s1234.commander4.com` (l’ID de votre propre espace de travail/site).

**Étape 5 : implémenter la logique de routage dans src/index.js**

Remplacez le contenu de `src/index.js` par le code de worker suivant.

Vous devez mettre à jour :

* `prefix` (le chemin de votre client, par exemple : `/mypath`)
* `sid` (l’ID de votre espace de travail/site Commanders, par exemple : `s1234`)

```javascript
/// <reference types="@fastly/js-compute" />

import { env } from "fastly:env";
import { includeBytes } from "fastly:experimental";

const prefix = "/PATHACHANGER";              // TODO: replace with your chosen gateway path (e.g. "/mypath")
const sid = "s123456";                       // TODO: replace with your workspace/site ID (e.g. "s1234")
const BACKEND = "commander_gateway";         // Fastly backend name pointing to sid.commander4.com

// List of cookie names that must NOT be forwarded to Commanders Gateway. Add your technical cookies if needed
const blacklistedCookies = [
  "PHPSESSID",
  "JSESSIONID"
];

addEventListener("fetch", (event) => event.respondWith(handleRequest(event.request, event.client)));

function filterCookieHeader(cookieHeader, blacklist) {
  if (!cookieHeader) return "";

  const blacklistSet = new Set(blacklist);

  const filteredCookies = cookieHeader
    .split(";")
    .map(cookie => cookie.trim())
    .filter(cookie => {
      const cookieName = cookie.split("=")[0];
      return !blacklistSet.has(cookieName);
    });

  return filteredCookies.join("; ");
}

async function handleRequest(request, client) {

  const url = new URL(request.url);

  // Only proxy requests that match the configured prefix
  if (!url.pathname.startsWith(prefix)) {
    return new Response("Not Found", { status: 404 });
  }

  // Preserve the complete customer path, including its configured prefix.
  const target = `https://${sid}.commander4.com${url.pathname}${url.search}`;

  // Clone headers and add forwarding info
  const headers = new Headers(request.headers);
  headers.set("X-Forwarded-Host", url.host);
  headers.set("X-Forwarded-Proto", "https");

  // Append the visitor IP to the existing forwarding chain.
  if (client.address) {
    const forwardedFor = headers.get("X-Forwarded-For");
    headers.set("X-Forwarded-For", forwardedFor
      ? `${forwardedFor}, ${client.address}`
      : client.address);
  }

  // Forward geo information when available (optional but recommended)
  const geo = client.geo;
  const country = geo && geo.country_code ? geo.country_code.toUpperCase() : "";
  const region = geo && geo.region ? geo.region : "";
  if (country) headers.set("X-Forwarded-Country", country);
  if (region)  headers.set("X-Forwarded-Region", region);
  if (country && region) headers.set("X-Forwarded-CountryRegion", `${country}-${region}`);

  // Filter the Cookie header before proxying the request.
  const cookieHeader = headers.get("Cookie");
  const filteredCookies = filterCookieHeader(cookieHeader, blacklistedCookies);

  if (filteredCookies) {
    headers.set("Cookie", filteredCookies);
  } else {
    headers.delete("Cookie"); // Remove the Cookie header entirely if all cookies were filtered out
  }

  // Avoid Host header conflicts at origin
  headers.delete("host");

  // Rebuild the request for the origin
  const originReq = new Request(target, {
    method: request.method,
    headers,
    body: request.body
  });

  // Bypass cache to ensure measurement hits are never cached
  const co = new CacheOverride("pass");

  // Send request to the configured Fastly backend
  return fetch(originReq, { backend: BACKEND, cacheOverride: co });

}
```

Important :

* Remplacez `s1234.commander4.com` par le point de terminaison correspondant à l’ID réel de votre espace de travail/site.
* Conservez le même `prefix` comme le chemin que vous réservez sur le domaine du client (exemple : `/mypath`).
* N’ajoutez PAS de barre oblique finale à la fin du chemin dans les URL côté client.

**Étape 6 : déployer**

Déployez le service Compute :

```
npm run deploy
```

**Étape 7 : tester**

Après le déploiement, Fastly fournit un domaine temporaire pour les tests, par exemple :

```
https://plainly-rested-bison.edgecompute.app/mypath/healthy
```

La réponse doit être :

```
ok
```

**Liaison de production (domaine du client)**

À ce stade, le service Compute s’exécute sur un domaine de test fourni par Fastly. Pour le mettre en production sur le domaine du client (exemple : `https://example.com/mypath/`), vous devez encore lier le service au domaine de production et vous assurer que TLS est configuré.

Cela implique généralement, selon la configuration du client :

* D’ajouter le domaine du client au service Fastly et de configurer TLS pour celui-ci (TLS géré ou certificat du client).
* De créer l’enregistrement DNS requis (souvent un CNAME) afin que `example.com` pointe vers Fastly.
* De s’assurer que le service Compute reçoit les requêtes pour le chemin choisi (exemple : `/mypath*`) sur ce domaine.

Comme les étapes exactes dépendent des produits Fastly activés sur le compte et de la façon dont le client gère TLS et le DNS, considérez cette étape comme une étape bêta et contactez le support si vous avez besoin des commandes exactes pour votre configuration.

**Vérifier le transfert de l’adresse IP et de la localisation du visiteur**

Ouvrez `https://example.com/mypath/debug/`, en utilisant le domaine de votre propre site web et le préfixe Gateway. Vérifiez les champs sous `computed`:

* `behindClientProxy` doit être égal à `true`.
* `clientIpSource` doit être égal à `"x-forwarded-for"` (ou à `"true-client-ip"` si vous utilisez cet en-tête).
* `countryRegionSource` doit identifier les en-têtes `x-forwarded-*` normalement `"x-forwarded-countryregion"` lorsque l’en-tête combiné est fourni.

Vérifiez que l’adresse IP et le pays/la région calculés correspondent au visiteur, et non au proxy. Utilisez des codes ISO, par exemple le pays `FR`, la région `IDF` et la valeur combinée `FR-IDF`. Un nom de région complet tel que `Île-de-France` est ignoré. Si aucune adresse IP ou localisation exploitable du visiteur n’est transmise, le Gateway utilise l’adresse IP ou la localisation du proxy. Une vérification de l’état de santé réussie ne suffit pas à confirmer la transmission de l’adresse IP et de la localisation du visiteur.
{% endtab %}
{% endtabs %}

***

**Étape 3 : mettre à jour les scripts dans votre système de gestion de tags ou sur votre site Web**

Remplacez les URL des scripts des fournisseurs par les nouveaux chemins **First-party**.

Exemples :

**Google**

```html
<!-- Au lieu de -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-12345"></script>

<!-- Utilisez -->
<script async src="/mypath/"></script>
```

**Meta (Facebook Pixel)**

```html
<!-- Au lieu de -->
<script src="https://connect.facebook.net/en_US/fbevents.js"></script>

<!-- Utilisez (chemin obfusqué fourni dans l’interface Commanders Act) -->
<script src="/mypath/js/f4558899203.js"></script>
```

**Snapchat**

```html
<script src="/mypath/js/a82b99df732.js"></script>
```

**Bing (UET)**

```html
<script src="/mypath/js/c77ac91be11.js"></script>
```

Chaque nom de fichier obfusqué est généré automatiquement et disponible dans l’interface **Commanders Act First-Party Hosting**.

**OneTag**

Vous pouvez modifier manuellement le domaine de votre configuration cact() à l’aide de `collectionDomain` Propriété. Exemple :

```javascript
cact(..., {collectionDomain: "www.youdomain.com/mypath"});
```

Avertissement : n’ajoutez PAS de `/` à la fin du chemin

***

**Étape 4 : vérifier la configuration**

* Pour le chemin global, vérifiez le point de terminaison de santé :
  * `https://example.com/mypath/healthy` → devrait renvoyer `ok`
* Utilisez les outils de développement du navigateur pour vérifier que :
  * Les scripts Google sont chargés depuis `/mypath/`
  * Les scripts des autres fournisseurs sont chargés depuis `/mypath/js/{obfuscated}.js`
  * Les requêtes sont envoyées à votre **domaine First-party**.
* Vérifiez que les événements apparaissent dans les dashboards partenaires correspondants (Google Analytics, Facebook Events Manager, etc.).

***

**Avantages**

* **Durabilité**: Le tracking continue de fonctionner, même avec Safari ITP et les restrictions relatives aux cookies Third-party.
* **Résilience**: Le fait de servir les scripts depuis votre domaine avec des noms de fichiers obfusqués complique l’action des règles de blocage.
* **Configuration centralisée**: Un seul chemin (`/mypath`) gère tous les fournisseurs.
* **À l’épreuve du temps**: S’adapte au Privacy Sandbox et aux futures restrictions des navigateurs.
*

**Configurer la collecte de données First-party pour les fonctionnalités de Commanders Act (via Gateway)**

Ce chapitre explique comment acheminer la collecte de données de Commanders Act via votre **chemin de gateway First-party** (par exemple `/mypath`) pour les principales fonctionnalités de Commanders Act.

Remarques importantes :

* Le chemin de gateway indiqué dans les exemples (`/mypath`) n’est qu’un exemple. Les clients choisissent leur propre chemin lors de la configuration de la gateway dans leur CDN ou outil edge (Cloudflare, Akamai, etc.).
* Tous les exemples ci-dessous supposent que votre gateway fonctionne correctement : `https://example.com/mypath/healthy` renvoie `ok`.

***

**1. Destinations server-side via la gateway (exemple : Meta Facebook CAPI)**

Le tracking server-side de Commanders Act repose sur des **oneTag** tags. En général, vous avez un oneTag par événement que vous souhaitez collecter, par exemple :

* `page_view`
* `add_to_cart`
* `purchase`

Pour acheminer ces événements oneTag via la gateway, vous devez mettre à jour la **configuration du tag oneTag** afin que la configuration de `cact()` utilise votre domaine et votre chemin de collecte First-party.

Dans votre tag oneTag (ou dans l’extrait partagé utilisé par vos tags oneTag), définissez `collectionDomain`:

```javascript
cact(..., { collectionDomain: "www.yourdomain.com/mypath" });
```

Remarques :

* Remplacez `www.yourdomain.com/mypath` par votre propre domaine et le chemin configuré dans votre gateway.
* N’ajoutez PAS de `/` à la fin du chemin.
* Une fois cette configuration définie, tous les événements oneTag (page\_view, add\_to\_cart, purchase, etc.) seront collectés via le chemin de votre gateway First party.

***

**2. Collecte de la CDP, de Campaign Analytics et de la CMP via la gateway**

*(Data Activation, statistiques de Campaign Analytics et de la CMP, et preuve de consentement)*

Ces trois fonctionnalités reposent sur le même mécanisme de routage. Pour envoyer leurs données via la gateway, vous devez définir la variable **`tC.clientCollectDns`** soit :

* directement dans chaque tag concerné, **soit**
* dans un **tag de configuration global** qui s’exécute avant tous les tags Commanders Act (recommandé).

Exemple :

```javascript
tC.clientCollectDns = "www.yourdomain.com/mypath";
```

Comportement :

* Dès que `tC.clientCollectDns` est définie, la collecte pour **Data Activation, Campaign Analytics et le suivi lié à la CMP** s’effectuera via la gateway.
* `mypath` n’est qu’un exemple. Les clients peuvent utiliser n’importe quel chemin configuré dans leur configuration de gateway.

Options d’implémentation :

* **Option A (simple) :** ajoutez la ligne directement dans le tag Data Activation / Campaign Analytics / CMP.
* **Option B (recommandée) :** ajoutez-la dans un tag de configuration global qui s’exécute avant tous les tags Commanders Act.

***

**Liste de vérification**

Après avoir appliqué les modifications ci-dessus, vérifiez les points suivants :

* Le point de terminaison d’état de la gateway : `https://example.com/mypath/healthy` renvoie `ok`.
* Dans les outils de développement du navigateur (onglet Network), les requêtes de collecte Commanders Act sont envoyées vers votre domaine et chemin First party (par exemple `https://example.com/mypath/...`).
* Les événements et les données apparaissent comme prévu dans :
  * les tableaux de bord des destinations server-side (exemple : Meta Events Manager pour CAPI)
  * les flux Data Activation
  * les statistiques de la CMP et les rapports de preuve de consentement (le cas échéant)
  * les rapports de Campaign Analytics


---

# 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/developpeurs/commanders-tag-gateway.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.
