Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Real-world examples
  • 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.

Registration

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

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

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.

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

Last updated