> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/fr/scripting/endpoints/link-url-enrichment.md).

# Enrichissement de l'URL du lien

Réécrivez l’URL de destination d’un lien suivi cliqué dans une Carte, par exemple pour ajouter des paramètres de campagne, avec runtime.wallet.linkUrlEnricher.

Les liens d’une carte (boutons du site web, liens au dos de la carte, modules de liens Google Wallet) peuvent être suivis : lorsqu’un porteur en touche un, la requête passe par The Wallet Crew, qui enregistre l’appui et redirige le porteur vers la destination. En chemin, The Wallet Crew ajoute des paramètres UTM à l’URL de destination. L’enrichisseur d’URL de lien permet à un script de locataire de décider à la place de l’URL finale, avec la carte et le lien sous la main, afin d’ajouter les paramètres de campagne propres à la marque, un segment ou un lien profond qui dépend de la carte. Cette page est la référence pour `runtime.wallet.linkUrlEnricher`.

L’enrichisseur change l’endroit où arrive le porteur ; il ne modifie pas les liens affichés sur la carte, qui proviennent du modèle de carte.

<details>

<summary><strong>Exemples concrets</strong></summary>

* Une marque remplace les paramètres UTM par défaut par sa propre convention de nommage, avec le Wallet et la position du lien dans la carte.
* Un détaillant ajoute le niveau d’adhésion du membre à l’URL d’arrivée, afin que son site web affiche les offres correspondantes.
* Une marque ouvre une page d’arrivée différente pour les porteurs Apple Wallet et Google Wallet.

</details>

## Enregistrement

La clé est `runtime.wallet.linkUrlEnricher`. L'enregistrer suffit : aucun fichier de configuration n'y fait référence.

```js
export default function (context) {
  context.register('runtime.wallet.linkUrlEnricher', {
    Enrich: async (url, link) => null
  });
}
```

{% hint style="warning" %}
L’enregistrement d’un enrichisseur remplace entièrement les paramètres UTM par défaut. Un script qui veut les conserver les ajoute lui-même.
{% endhint %}

Sans enrichisseur, The Wallet Crew ajoute `utm_source=thewalletcrew`, `utm_medium` (`apple` ou `google`), `utm_campaign` (la position du lien, comme `back_field` ou `links_module`) et `utm_content` (l’identifiant du lien dans cette position, lorsqu’il y en a un), sauf si l’URL contient déjà un `utm_source` paramètre. Un fragment (`#section`) est conservé à la fin de l’URL.

## Quand il s’exécute

Le script s’exécute chaque fois qu’un porteur touche un lien suivi, au sein de la requête de redirection : le porteur attend qu’il se termine avant l’ouverture de la destination, donc le gestionnaire doit rester rapide et éviter les appels externes. Lorsqu’il s’exécute, l’appui a déjà été enregistré comme un événement d’ouverture de lien de la carte.

## Gestionnaires

| Méthode    | Paramètres    | Retours                                                         | Obligatoire |
| ---------- | ------------- | --------------------------------------------------------------- | ----------- |
| `Enrichir` | `url`, `link` | une chaîne d’URL, `null`, ou une promesse de l'un ou de l'autre | Obligatoire |

`url` est l’URL de destination telle qu’elle est écrite dans le modèle de carte. `link` (le nom du paramètre est libre, il est positionnel ; les typings de l’éditeur l’affichent comme `contexte`) décrit la carte et le lien, avec des clés en PascalCase :

| Clé              | Type           | Signification                                                                                                                |
| ---------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `CarteId`        | chaîne         | L’identifiant de la carte. Vide lorsque la carte n’a pas pu être chargée.                                                    |
| `CarteType`      | chaîne         | Le type de carte. Vide lorsque la carte n’a pas pu être chargée.                                                             |
| `Identifiants`   | objet          | Les identifiants de la carte, indexés sans le `identifiant.` préfixe. Vide lorsque la carte n’a pas pu être chargée.         |
| `AdditionalData` | objet ou null  | Les données supplémentaires de la carte.                                                                                     |
| `Métadonnées`    | objet          | Les métadonnées de la carte. Vide lorsque la carte n’a pas pu être chargée.                                                  |
| `Appareil`       | nombre ou null | Le Wallet pour lequel la carte a été générée : `0` pour Apple Wallet, `2` pour Google Wallet.                                |
| `Origine`        | nombre ou null | Où se situe le lien dans la carte, sous forme de nombre (tableau ci-dessous).                                                |
| `ID source`      | chaîne ou null | L’identifiant du lien dans son origine : une clé de champ, un type d’action, un libellé de lien ou un identifiant de module. |
| `Langue`         | chaîne ou null | La langue dans laquelle le texte du lien a été rendu, lorsque le texte est localisé.                                         |

`Appareil` et `Origine` sont tous deux définis, ou tous deux `null` lorsque le lien ne contient aucune information source.

| `Origine` | Position                                                  | `ID source`             |
| --------- | --------------------------------------------------------- | ----------------------- |
| `0`       | Page d’accueil (site web de la marque ou du lieu)         |                         |
| `1`       | URL d’aide                                                |                         |
| `2`       | Lien profond de l’application                             |                         |
| `3`       | Bouton d’action mis en avant Apple                        | le type de bouton       |
| `4`       | Lien transactionnel Apple (vente, transfert, commande...) | le type de lien         |
| `5`       | Lien informatif Apple (itinéraire, stationnement...)      | le type de lien         |
| `6`       | Hyperlien du champ arrière Apple                          | la clé de champ         |
| `7`       | Module de liens Google                                    | le libellé du lien      |
| `8`       | Module à valeur ajoutée Google                            | l’identifiant du module |
| `9`       | Hyperlien du module de texte ou de message Google         | l’identifiant du module |
| `10`      | Bouton de partage Apple                                   | `partage`               |

## Valeur de retour

| Renvoyé              | Effet                                                                                              |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| Une chaîne d’URL     | Le porteur y est redirigé.                                                                         |
| `null` ou `indéfini` | Le porteur est redirigé vers l’URL d’origine `url`, inchangé (sans les paramètres UTM par défaut). |

## Erreurs et cas limites

* **Enrich lève une erreur ou sa promesse est rejetée**: un avertissement est consigné et le porteur est redirigé vers l’URL d’origine `url`, inchangé.
* **Enrich est absent** de l’objet enregistré : l’appel échoue et le porteur est redirigé vers l’URL d’origine `url` comme pour une erreur levée.
* **La carte ne peut pas être chargée** : le script s’exécute quand même, avec un contexte de carte vide.
* **Plusieurs fichiers enregistrent la clé**: le dernier enregistré l’emporte, et l’ordre de chargement des fichiers n’est pas défini.

## Exemple

Le script conserve la propre convention de nommage des campagnes de la marque, ajoute le niveau d’adhésion du membre stocké dans les métadonnées de la carte, et laisse intacts une chaîne de requête et un fragment existants. Il ne met pas de données personnelles dans l’URL : le niveau est un segment, pas une identité.

```js
const WALLETS = { 0: 'apple-wallet', 2: 'google-wallet' };
const POSITIONS = ['homepage', 'help', 'app', 'featured', 'transactional', 'informational', 'back', 'links', 'offers', 'message'];

function addParameters(url, parameters) {
  const hashIndex = url.indexOf('#');
  const base = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
  const fragment = hashIndex >= 0 ? url.slice(hashIndex) : '';
  const query = Object.keys(parameters)
    .filter((key) => parameters[key] !== null && parameters[key] !== undefined && parameters[key] !== '')
    .map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(parameters[key])}`)
    .join('&');
  if (!query) {
    return url;
  }
  return `${base}${base.includes('?') ? '&' : '?'}${query}${fragment}`;
}

async function enrich(url, link) {
  if (url.includes('utm_source=')) {
    return null;
  }

  return addParameters(url, {
    utm_source: 'wallet',
    utm_medium: WALLETS[link.Device] ?? 'wallet',
    utm_campaign: link.PassType || null,
    utm_content: POSITIONS[link.Origin] ?? null,
    tier: link.Metadata?.tier ?? null
  });
}

export default function (context) {
  context.register('runtime.wallet.linkUrlEnricher', {
    Enrich: enrich
  });
}
```

## Vérification du résultat

Taper un lien suivi d’une carte de test sur un appareil, ou ouvrir le lien suivi dans un navigateur, affiche l’URL finale dans la barre d’adresse. Lorsque l’URL est inchangée alors que le script aurait dû la modifier, le suivi de la plateforme montre si `Enrichir` a levé une erreur.

## Pièges courants

* Le script ajoute `?` à une URL qui contient déjà une chaîne de requête, ou place les paramètres après le fragment.
* Un appel externe dans le gestionnaire ralentit chaque appui.
* Des identifiants ou des adresses e-mail sont ajoutés à l’URL, où ils se retrouvent dans les analyses et les journaux de la destination.

## FAQ

<details>

<summary><strong>Tous les liens d’une carte sont-ils suivis ?</strong></summary>

Seuls les liens suivis passent par The Wallet Crew et donc par l’enrichisseur. Les liens partagés par chaque carte d’une classe Google Wallet, comme la page d’accueil de la classe, ne sont pas suivis par carte.

</details>


---

# 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://docs.thewalletcrew.io/developers-guides/fr/scripting/endpoints/link-url-enrichment.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.
