> 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/scripting/endpoints/link-url-enrichment.md).

# Link URL enrichment

Rewrite the destination URL of a tracked link tapped in a pass, for example to add campaign parameters, with runtime.wallet.linkUrlEnricher.

The links of a pass (website buttons, back-of-pass links, Google Wallet link modules) can be tracked: when a holder taps one, the request goes through The Wallet Crew, which records the tap and redirects the holder to the destination. On the way, The Wallet Crew adds UTM parameters to the destination URL. The link URL enricher lets a tenant script decide the final URL instead, with the pass and the link at hand, to add the brand's own campaign parameters, a segment, or a deep link that depends on the pass. This page is the reference for `runtime.wallet.linkUrlEnricher`.

The enricher changes where a holder lands; it does not change the links displayed on the pass, which come from the pass template.

<details>

<summary><strong>Real-world examples</strong></summary>

* A brand replaces the default UTM parameters by its own naming convention, with the wallet and the position of the link in the pass.
* A retailer adds the member's tier to the landing URL, so its website shows the matching offers.
* A brand opens a different landing page for Apple Wallet and Google Wallet holders.

</details>

## Registration

The key is `runtime.wallet.linkUrlEnricher`. Registering it is enough: no configuration file refers to it.

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

{% hint style="warning" %}
Registering an enricher replaces the default UTM parameters entirely. A script that wants to keep them adds them itself.
{% endhint %}

Without an enricher, The Wallet Crew adds `utm_source=thewalletcrew`, `utm_medium` (`apple` or `google`), `utm_campaign` (the position of the link, such as `back_field` or `links_module`) and `utm_content` (the link's identifier within that position, when there is one), unless the URL already has a `utm_source` parameter. A fragment (`#section`) is kept at the end of the URL.

## When it runs

The script runs every time a holder taps a tracked link, inside the redirect request: the holder waits for it before the destination opens, so the handler must stay fast and avoid external calls. By the time it runs, the tap has been recorded as a link-opened event of the pass.

## Handlers

| Method   | Parameters    | Returns                                      | Required |
| -------- | ------------- | -------------------------------------------- | -------- |
| `Enrich` | `url`, `link` | a URL string, `null`, or a promise of either | Required |

`url` is the destination URL as written in the pass template. `link` (the parameter name is free, it is positional; the editor typings show it as `context`) describes the pass and the link, with PascalCase keys:

| Key              | Type           | Meaning                                                                                            |
| ---------------- | -------------- | -------------------------------------------------------------------------------------------------- |
| `PassId`         | string         | The pass id. Empty when the pass could not be loaded.                                              |
| `PassType`       | string         | The pass type. Empty when the pass could not be loaded.                                            |
| `Identifiers`    | object         | The pass identifiers, keyed without the `id.` prefix. Empty when the pass could not be loaded.     |
| `AdditionalData` | object or null | The pass's additional data.                                                                        |
| `Metadata`       | object         | The pass metadata. Empty when the pass could not be loaded.                                        |
| `Device`         | number or null | The wallet the pass was generated for: `0` for Apple Wallet, `2` for Google Wallet.                |
| `Origin`         | number or null | Where the link sits in the pass, as a number (table below).                                        |
| `SourceId`       | string or null | The link's identifier within its origin: a field key, an action type, a link label or a module id. |
| `Language`       | string or null | The language the link text was rendered in, when the text is localized.                            |

`Device` and `Origin` are both set, or both `null` when the link carries no source information.

| `Origin` | Position                                            | `SourceId`      |
| -------- | --------------------------------------------------- | --------------- |
| `0`      | Homepage (brand or venue website)                   |                 |
| `1`      | Help URL                                            |                 |
| `2`      | App deep link                                       |                 |
| `3`      | Apple featured action button                        | the button type |
| `4`      | Apple transactional link (sell, transfer, order...) | the link type   |
| `5`      | Apple informational link (directions, parking...)   | the link type   |
| `6`      | Apple back field hyperlink                          | the field key   |
| `7`      | Google links module                                 | the link label  |
| `8`      | Google value added module                           | the module id   |
| `9`      | Google text or message module hyperlink             | the module id   |
| `10`     | Apple Share button                                  | `sharing`       |

## Return value

| Returned              | Effect                                                                                          |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| A URL string          | The holder is redirected to it.                                                                 |
| `null` or `undefined` | The holder is redirected to the original `url`, unchanged (without the default UTM parameters). |

## Errors and edge cases

* **Enrich throws or its promise rejects**: a warning is logged and the holder is redirected to the original `url`, unchanged.
* **Enrich is missing** from the registered object: the call fails, and the holder is redirected to the original `url` as for a thrown error.
* **The pass cannot be loaded**: the script still runs, with an empty pass context.
* **Several files register the key**: the last registered wins, and the load order of files is not defined.

## Example

The script keeps the brand's own campaign naming, adds the member tier stored in the pass metadata, and leaves an existing query string and fragment intact. It does not put personal data in the URL: the tier is a segment, not an identity.

```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
  });
}
```

## Checking the result

Tapping a tracked link of a test pass on a device, or opening the tracked link in a browser, shows the final URL in the address bar. When the URL is unchanged although the script should have changed it, the platform's monitoring shows whether `Enrich` threw.

## Common pitfalls

* The script appends `?` to a URL that already has a query string, or places parameters after the fragment.
* An external call in the handler makes every tap slow.
* Identifiers or email addresses are added to the URL, where they end up in the destination's analytics and logs.

## FAQ

<details>

<summary><strong>Are all links of a pass tracked?</strong></summary>

Only tracked links go through The Wallet Crew and therefore through the enricher. Links that are shared by every pass of a Google Wallet class, such as the class homepage, are not tracked per pass.

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