Adaptive Links

Adaptive links detect the user’s platform and install the correct pass for their device vendor. An adaptive link can specify an Apple and Google template.

Adaptive Link request

An adaptive link request contains identifiers for the templates you used to generate passes from the link and any fields you want to set when users create passes from the link. If you need to create a boarding pass adaptive link, go to the boarding pass object.

Jump to examples ↓

All of

OBJECT PROPERTIES
- androidTemplateExternalId string
  The custom identifier of the Google template for passes issued from this adaptive link.
- androidTemplateId integer
  The Google template for passes issued from the adaptive link.
- availablePasses integer
  The total number of passes that can be created from this link. If absent, the link supports 1,000,000 passes.
- iosTemplateExternalId string
  The custom identifier of the Apple template for passes issued from the adaptive link, if assigned.
- iosTemplateId integer
  The iOS template for passes issued from the adaptive link.
- isPersonalized boolean
  If true, each request (when a recipient uses an adaptive link) generates a new pass. You can update any of the individual passes generated from the adaptive link. If you generate the adaptive link using any request parameters, isPersonalized is automatically set to true.
  If false, only the first request generates a pass; subsequent requests generate a new instance of the same pass. When isPersonalized is false, you cannot update passes generated from an adaptive link by updating the adaptive link itself. Rather, you must use the Bulk Update Passes endpoint to push updates to the pass instances generated from the adaptive link.
- landingPageUrl string
  The address users are redirected to if their device type cannot be detected or they cannot install the pass for another reason.
- parameterEncoding string
  When set, allows url-encoded parameters to set or modify values when creating passes from the adaptive link.
  Possible values: base64
OBJECT PROPERTIES
- androidPassLinkId string
  A dynamic link for Android passes.
- expirationDate string
  When set, indicates the date this adaptive link expires. An expired adaptive link will return a JSON object with an error message instead of a pass.
- installLimit integer
  The number of times a user can install the pass. When the pass reaches its limit, attempts to install the pass are met with errors.
  This limit only affects the adaptive link itself, not actual Apple pass files. If you want to prevent users from installing shared passes on Apple devices, you should also set sharingStatus to prohibit sharing.
- installLimitPerPassExternalId integer
  The number of times a user can install the pass that has an externalId. When the pass reaches its limit, attempts to install the pass are met with errors.
  This limit only affects the adaptive link itself, not actual Apple pass files. If you want to prevent users from installing shared passes on Apple devices, you should also set sharingStatus to prohibit sharing.
- iosPassLinkId string
  A dynamic link for iOS passes.
- locationRadius integer
  Determines the range, in miles, that a pass holder can be from a location to associate their pass with a location. If absent, the default location radius is 10 miles.
- locations array
  An array of up to 10,000 locations associated with the adaptive link. Apple Wallet supports up to 10 locations per pass. If you exceed this limit, Apple Wallet passes will use the 10 locations nearest to a user (located by IP address) when they install the pass.
  You can also include a location radius and the maximum number of locations to be matched upon pass creation. Wallet sorts locations to be matched in order from closest to/furthest from the location provided by the device.
- maxResultLocations integer
  The maximum number of locations the pass recipient can match. If the pass holder matches multiple locations, locations are returned in order from closest to farthest.
- payload objectREQUIRED
  The field names and values you want to update for those pass fields. Changing a value will result in a change message notifying the user of the changed value.
  While the payload object is required, it can be an empty object.
  OBJECT PROPERTIES
  - sharingStatus object
    A field determining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as other fields, you only need to set the value within the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.
    On iOS devices, oneUserOneDevice prohibits sharing ("sharingProhibited": true); all other values allow sharing.
    You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.
    OBJECT PROPERTIES
    - changeMessage string
      The message that appears when you update this field.
    - value stringREQUIRED
      Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting: oneUserOneDevice prohibits sharing; all other values allow sharing.
      Possible values: multipleHolders, oneUserAllDevices, oneUserOneDevice

Used in:

Examples


{
  "iosTemplateId": 12345,
  "androidTemplateId": 154321,
  "isPersonalized": "true",
  "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "androidPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "landingPageUrl": "https://example.com/landing.html",
  "expirationDate": "2022-10-01",
  "availablePasses": 100000,
  "ttlInDays": 30,
  "parameterEncoding": "base64",
  "locationRadius": 10,
  "maxResultLocations": 5,
  "payload": {},
  "locations": [
      {
         "latitude": 45.5898,
         "longitude": -122.5951,
         "city": "Portland",
         "country": "US",
         "region": "OR",
         "regionCode": "97218",
         "relevantText": "Welcome to Portland... Voodoo Donuts is only 11 miles away",
         "streetAddress1": "7000 NE Airport Way"
      },
      {
         "latitude": 45.525492,
         "longitude": -122.686092,
         "city": "Portland",
         "country": "US",
         "region": "OR",
         "regionCode": "97209",
         "relevantText": "Welcome to the Ship!",
         "streetAddress1": "1417 NW Everett St #300",
         "streetAddress2": ""
      },
      {
         "latitude": 45.5205,
         "longitude": -122.6788,
         "relevantText": "See you at dinner tonight… or did you already hit voodoo donuts?"
      }
    ]
  }

Adaptive Link response

An adaptive link response includes URLs that users can access to detect and install a pass.

Jump to examples ↓

All of

OBJECT PROPERTIES
- androidTemplateExternalId string
  The custom identifier of the Google template for passes issued from this adaptive link.
- androidTemplateId integer
  The Google template for passes issued from the adaptive link.
- availablePasses integer
  The total number of passes that can be created from this link. If absent, the link supports 1,000,000 passes.
- iosTemplateExternalId string
  The custom identifier of the Apple template for passes issued from the adaptive link, if assigned.
- iosTemplateId integer
  The iOS template for passes issued from the adaptive link.
- isPersonalized boolean
  If true, each request (when a recipient uses an adaptive link) generates a new pass. You can update any of the individual passes generated from the adaptive link. If you generate the adaptive link using any request parameters, isPersonalized is automatically set to true.
  If false, only the first request generates a pass; subsequent requests generate a new instance of the same pass. When isPersonalized is false, you cannot update passes generated from an adaptive link by updating the adaptive link itself. Rather, you must use the Bulk Update Passes endpoint to push updates to the pass instances generated from the adaptive link.
- landingPageUrl string
  The address users are redirected to if their device type cannot be detected or they cannot install the pass for another reason.
- parameterEncoding string
  When set, allows url-encoded parameters to set or modify values when creating passes from the adaptive link.
  Possible values: base64
OBJECT PROPERTIES
- adaptiveLinkId integer
  A unique identifier for the adaptive link. Use this value to reference the adaptive link in future operations.
- androidPassLinkId string
  A dynamic link for Android passes. This field cannot be provided for links/adaptive/multiple requests, nor is it provided in those responses (e.g., boarding passes, event tickets, etc.).
- androidUrl string
  A pass URL specific to Android users.
- createdAt string
  The date and time when the item was created.
- expirationDate string
  The date this adaptive link expires. This property appears in the response only if it has been explicitly set with a previous API request. Cannot be set to a date more than 1,080 days in the future.
- iosPassLinkId string
  A dynamic link for iOS passes. This field cannot be provided for links/adaptive/multiple requests, nor is it provided in those responses (e.g., boarding passes, event tickets, etc.).
- iosUrl string
  A pass URL specific to iOS users.
- isExpired boolean
  If true, the adaptive link is expired. An expired adaptive link will return a JSON object with an error message instead of a pass.
- projectId integer
  The ID of the project.
- ttlInDays integer
  The number of days of inactivity before this adaptive link automatically expires.
- updatedAt string
  The date and time when the item was last updated.
- url string
  The adaptive link URL itself; using this URL on an Android or iOS device will detect device types and install the correct pass.

Used in:

Examples

{
  "adaptiveLinkId": "abchd345678",
  "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/android",
  "landingPageUrl": "https://example.com/landing.html",
  "isPersonalized": "true",
  "isExpired": true,
  "expirationDate": "2020-10-01",
  "availablePasses": 100000,
  "ttlInDays": 730
}