Generate and Distribute Passes

After you design your pass Template, you can then Generate the passes and Distribute them to your users.

Haven’t created your Template yet? Hop over to Design Passes.

Generate Passes

You can generate passes by using the Reach API or by uploading a CSV file via the Reach dashboard.

CSV Batch Importer

To create passes via the CSV Batch Importer, you must upload a CSV file formatted with columns that match the field layout for your pass template. After uploading the CSV file in the Reach dashboard, you will receive a link to download the processed file appended with the pass URLs. You can then distribute the passes via email or the method of your choosing.

  1. The URLs returned by the CSV Batch Importer are multi-use passes — they can be downloaded by multiple devices.

  2. URLs are Dynamic

Viewable passes are not generated until the user interacts with the pass URL and installs the pass on a device. Due to the dynamic nature of pass URLs, keep in mind the following:

  • When a pass is created with specific values, the pass cannot be updated until after it has been installed.

  • If a template is changed before a pass is installed, the pass will have the newest template state.

  • Caution: Creating multiple passes with a single external ID will cause any pass after the first one that is installed to fail and send an error message. Make sure that each pass has a unique external ID.

Format CSV

  1. Navigate to the Templates section in the Reach dashboard, select the template that will serve as the base model for your passes, then click the Edit Design button.


  2. Click Field Layout in the header, and use the field names as the initial data in your CSV file:


    The field names for your template are located on the left side of the Field Layout screen.


  3. Create a CSV file with a header row that specifies each field name, followed by rows specifying values for each field name. Each row represents a single pass.

The only date format accepted for Android templates is YYYY-MM-DD.

You will be able to map your CSV headers to the correct Field Names after import.

Here is the start of a valid CSV file corresponding to the template in the above images:

We recommend your CSV file contain no more than 500,000 rows. While we do not limit the number of passes you can create via batch import, the file size limit is 250 MB.

Additional Columns

In addition to columns specifying each field name, you may also include columns for:

  • barcode_value : You can use this column to customize barcode values on a per-pass level.

  • externalId : The external identifier value specifies a user ID in a backend system (e.g. a CRM database), which may be used to map a pass to your data. For example, suppose a customer receives a pass with an externalId value that links to an ID in your backend loyalty system. If this customer makes a purchase that earns loyalty points, his or her pass can be updated with this new data. Because this field maps to a specific pass, it must be unique. Rows containing duplicate externalId values will not be processed.

Import and Field Mapping

  1. Navigate to the Templates section in the Reach dashboard, and select the template you used for your CSV file fields.

  2. Click the Actions dropdown menu, then Batch Importer.


  3. Click the Select a .csv file button.


    Only .csv files will be available for selection. Choose the file you wish to upload.


  4. Matched CSV headers and Field Names will auto-select. Use the dropdown menu to select the correct Field Name per CSV header, or leave blank if there is no corresponding Field Name or if you wish to not match to the CSV header, e.g. a field name matches but you don’t want it displayed on the pass.


  5. Click the Confirm Mapping button after you have completed mapping each field.


  6. Enter your email address. This defaults to the email address in your reach.urbanairship.com account, but you can enter any valid email address. Make changes, if necessary, then click the Process CSV button.


Pass URLs

When your CSV file has finished uploading/validating, an email confirmation and download link will be sent to the provided address.

The validation process will search for errors, and if any are detected, the email will direct you to the offending line(s). Once your CSV file has finished uploading/validating, an updated CSV file containing Pass ID and Download URL columns will be sent to the given address.

Each URL can be used to download the associated pass. The updated file will also be available via the Download CSV file button.

When you receive the processed CSV file, an additional column titled Download URL is added to the file. The URLs in the Dowload URL column are formatted like so:

https://wallet-api.urbanairship.com/v1/pass/dynamic/2931580989855247863.50827_457a6a69-cea8-4bbe-860a-aba56ee5a269

In the above example URL, 2931580989855247863.50827_457a6a69-cea8-4bbe-860a-aba56ee5a269 is the internal reference ID that you will need when referencing this pass via the Reach API.

URLs that are not activated will expire after 6 months.

Distribute Passes

After you generate passes via the CSV Batch Importer or the API, you can distribute them to recipients in multiple ways.

Display Passes on Lock Screen

There are two ways to make your pass show up on a user’s lock screen: Relevant Location and Relevant Date. See Triggers for set up steps.

Relevant Location displays a shortcut to your pass on the user’s screen when the device is in the vicinity of certain location. The radius around the location where the shortcut appears is determined by Apple Wallet or Android Pay and varies by pass type. For instance, Boarding Passes will appear on the lock screen at around 2 miles, but Coupons will appear at a few hundred feet.

Relevant Date displays a shortcut to your pass on a user’s lock screen at a certain date and time. This is handy for certain types of passes, like Events and Boarding Passes. As with Relevant Location, the timing when the shortcut appears is determined by Apple Wallet or Android Pay and varies by pass type. Relevant Date is not supported on Coupons or Store Cards.

A .pkpass file can be considered similar to a PDF, or any other document that you might link to. Right now, you can upload the .pkpass file to your web server, and link to it as you normally would.”

For Mobile Safari to recognize the file, your server has to be properly configured to support the MIME-type application/vnd.apple.pkpass. The process for adding MIME-type support varies by web server vendor. Many hosting companies provide a control panel interface which allows you to easily add a new type.

Save to Android Pay

A pass URL generated from an Android Pay template provides a deep link from Google into the Android Pay app so that the pass can be downloaded directly without requiring a browser window to facilitate the request.

Save to Android Pay lets your users save an object to Android Pay from the web at the click of a button. Urban Airship simplifies this process by providing an API function that returns the JavaScript that will render the Save to Android Pay button with the necessary information to create a wallet object. All you need is the user information and any pass-specific details.

In order to generate the necessary JavaScript, a server-side post to our API with the necessary information must occur. The post is as follows:

POST /v1/pass/{templateID}/saveToWallet

The template ID must match the template ID in Reach. This API call will accept the following optional JSON values:

JSON Parameters

fields
the values for the card
externalID
An ID that can be used to update the card in the future
tag
a single tag that the card will be added to
onSuccess
a JavaScript function you create that is called when the card is successfully added
onFail
a JavaScript function you create that is called when the card fails to be added. The response back from this API call will have all of the necessary JavaScript that can be injected into the page and will render the Save to Android Pay button.

For more information on this API function and the returned JavaScript, please see the API reference at Google Save to Android Pay.

Once the Save to Android Pay button is rendered on the page, a user can hover over it to display the currently logged in account, with an option to change to a different account. If not logged in, a log in window appears.

After clicking the button while logged in with a valid Google account, the Google Object will be created and saved to the user’s wallet. Depending on how you configure the onSuccess JSON value, you can redirect to a different page or simply do nothing, and the Google JavaScript library will let the user know the card was successfully saved.

Send Test Pass

After you have saved your Template, send yourself a test pass on an iOS device. The device must be running at minimum iOS 6 to view passes.

  1. Navigate to the Templates section in the Reach dashboard, select a template, then click the Edit Design button.

  2. Click the Send Test Pass button at the bottom of the screen.

  3. Enter an email address in the browser dialog that opens, then click the OK button.

  4. Open the Mail app on your iOS device, open the “New Pass Generated…” email, and tap the Wallet attachment to view the pass.