CSV Batch Importer Tutorial

Passes are distributed as URLs:

  1. The URL points to the pass.
  2. When a user opens the URL, they can view and install the pass.
 Note

Google Pay can no longer be installed on devices running Android KitKat (v4.4). However, existing Google Pay users on KitKat can continue using the app until mid-August, 2018 when support for KitKat is completely phased-out.

If distributing passes based on a Google Pay template, you should exclude devices running Android KitKat or earlier from your audience.

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

 Important

  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.

CSV Formatting

Quickly find the headers you will use for your CSV:

  1. Open your mobile wallet project and go to Templates.
  2. Select the template that will serve as the base model for your passes, then click Edit Design.
  3. Use the field names as the initial data in your CSV file. The field names shown in this image are Tier and Tier Name.

Now you can create a CSV file with a header row that specifies field names, followed by rows specifying values for each field name. Each row represents a single pass.

 Note

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

We recommend your CSV file contain no more than 500,000 rows. The CSV file size limit is 250 MB, but there is no limit to the number of passes you can create this way.

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

  • barcode_value : Provide custom barcode values for each pass.
  • externalId : The external identifier value specifies a user ID in a backend system (e.g. a CRM database) that you can use to map a pass to your data. For example, if a customer receives a pass with an externalId value that links to an ID in your backend loyalty system. When your customer makes a purchase that earns loyalty points, you can update his or her pass can with this new data. This field must be unique. Airship will not process rows containing duplicate externalId values.

Here is the start of a valid CSV file:

 Warning

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

Import and Field Mapping

  1. Go to the same project and template used when formatting your CSV.
  2. Click Batch Importer.
  3. Click Select a .csv file and choose your file.
  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 Confirm Mapping after you have completed mapping each field.
  6. Enter your email address. This defaults to the email address in your Airship account, but you can enter any valid email address.
  7. Click Process CSV.

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 Wallet API.

 Note

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.