Adaptive Links API Tutorial

Generate a single link that automatically detects the device OS and installs the appropriate pass.

Adaptive Links bridge the gap between email, SMS, and digital wallet passes via an intelligent linking system capable of building and distributing platform-appropriate digital wallet passes on demand.

See Adaptive Links for more information. See also: Wallet Templates Menu Guide: Adaptive Links.

 Tip

You can even use an Adaptive Link for a single platform. If a user on the unsupported platform attempts to install your pass, you can set the link to drive the user to a landing page of your choosing.

When creating the Adaptive Link, use ID null for the second template, and make sure to include a value for landingPageUrl.

This applies to Adaptive Links created via the API only.

 Note

Adaptive Links may also be created via the dashboard. See: Adaptive Links Tutorial.

 Important

You must already have at least one Apple Wallet and one Google Pay template to associate with each other. If not, create and design a template in the dashboard now:

You must have at least one Apple Wallet and one Google Pay template before you can create an adaptive link. The adaptive link associates an Apple Wallet template and Google Pay template to produce a pass from either vendor when a user taps the link.

  1. Perform a one-time POST API call to https://wallet-api.urbanairship.com/v1/links/adaptive, referring to the template ID for the template you created in the previous step. Sample data and JSON parameters are below.

Example

{
    "androidTemplateId": "610213",
    "availablePasses": 100000,
    "iosTemplateId": "581252",
    "isPersonalized": "false",
    "landingPageUrl": "https://airship.com",
    "locationRadius": 10,
    "maxResultLocations": 5,
    "locations": [
        {
            "latitude": 45.5898,
            "longitude": -122.5951,
            "relevantText": "Welcome to Portland... Voodoo Donuts is near..."
        },
        {
            "latitude": 37.7835926,
            "longitude": -122.3982583,
            "relevantText": "Hello Airship SF"
        }
    ],
    "payload": {
        "externalId": null,
        "fields": {
            "offercode": {
                "value": "MJ85SMR"
            }
        },
        "headers": {
            "barcodeAltText": {
                "value": "MJ85SMR"
            },
            "barcode_value": {
                "value": "MJ85SMR"
            }
        }
    }
}

You can create and modify adaptive links for pass types other than boarding passes or event tickets through the dashboard or API. But, if you create an adaptive link through the API, you cannot modify it in the dashboard. You must create boarding pass and event ticket adaptive links through the API.

If you set the parameterEncoding parameter on your adaptive link, you can generate passes directly from your adaptive link with a GET call to https://wallet-api.urbanarishp.com/pass/adaptive/{adaptiveLinkId}/{device_type}.

When generating passes this way, you can append request parameters mapping to pass fields to the URL to add or update values to the pass at creation time. You can find a list of reserved parameters and other information about the adaptive link API here. Outside of reserved parameters, you can provide the fieldName=value for any field contained in the adaptive link.

If you configured your Adaptive Link object with the isPersonalized flag set to false (or the flag is absent), the first request will create a pass, and subsequent requests will create new instances of this same pass. If the isPersonalized flag is true, or your request includes url-encoded parameters, every request will create a new pass.

Example

If you wanted to add an offer code, barcode, member ID, and time/location, you could append query parameters to an adaptive link as follows:

https://wallet-api.urbanairship.com/v1/pass/adaptive/QXynXTbMhS?offercode=AUGUST&barcode=A1234567&tags=PST~OR&exid=A1234567
 Note

You cannot personalize Google Pay class fields with unique values. Any field preceded by class constitutes a class field. See Google Pay Pass Verticals documentation for a full list of class fields for each pass type.

By default, adaptive links expire after 6 months if they are unused. After you or a member of your audience uses an adaptive link to generate a pass, the link persists forever.

If you generate passes for an entire audience from a single adaptive link, then generating a test pass will cause the link to persist forever. If you distribute personalized adaptive links to your whole audience, then it's likely that some adaptive links will expire after six months, as not all users will click or tap their personalized link.

Passes generated from an adaptive link expire based on pass type or values set at the template or pass level.

Google Class Fields

Google Pay Class Fields cannot be personalized with unique values. Any field preceded by class constitutes a class field. For a full list of class fields, please visit the Google Pay documentation.

Send the Pass

Now that you have an Adaptive Link, you can [distribute its related pass in multiple ways(https://docs.airship.com/tutorials/wallet/distribute/).