Adaptive Links API Tutorial

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 the Adaptive Links guide 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.

What You'll Do

In this tutorial, you will:

  1. Configure your Adaptive Links by performing a one-time POST API call.

Steps

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:

  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.

Sample Data

{
   "androidTemplateId": "610213",
   "availablePasses": 100000,
   "iosTemplateId": "581252",
   "isPersonalized": "false",
   "landingPageUrl": "http://urbanairship.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 Urban Airship SF"
      }
    ],
   "payload": {
      "externalId": null,
      "fields": {
         "offercode": {
            "value": "MJ85SMR"
         }
      },
      "headers": {
         "barcodeAltText": {
            "value": "MJ85SMR"
         },
         "barcode_value": {
            "value": "MJ85SMR"
         }
      }
   }
}

Modification

Adaptive Links created via the API can be edited or deleted via the API but only deleted in the dashboard.

To modify or delete Adaptive Links via the API, see the Wallet API

Creating Passes from Adaptive Links

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.

JSON parameters

payload
Object. Data set forwarded on to either androidTemplateId or iosTemplateId. This can include externalId, fields, headers, each with its own value or set of sub-values.
androidTemplateId and iosTemplateId
String. Templates the payload key will be passed to.
availablePasses
Integer. Total number of Adaptive Links passes that can be distributed.
landingPageUrl
String. This is the fallback url if a requesting device is undefined or a desktop computer.
parameterEncoding
Optional String. When set, allows url-encoded parameters to set or modify values when creating passes from an adaptive link. Possible values: base64.
locations
JSON array. An array of locations able to trigger a pass foreground and notification event.
locationRadius
Integer. Distance (in miles) from a given latitude/longitude coordinate.
maxResultLocations
Integer. Maximum number of locations able to be added to any one pass.
externalId
String. A unique 1:1 id associated with that pass on that device only — frequently member ID or the like.

Send the Pass

Now that you have an Adaptive Link, you can distribute its related pass in multiple ways. See: Pass Distribution Methods.

Tutorials