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.
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
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:
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
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
urlas 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

