CSV Batch Importer Tutorial

Passes are distributed via URL:

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

After you design a pass template, you can then generate the template’s pass URLs, either 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.

What You’ll Do

In this tutorial, you will:

  1. Prepare your CSV file.
  2. Import the file and map fields.
  3. Submit the file for processing.

Features and options are explained along the way.

Steps

Format CSV

  1. Choose your project from the Reach dashboard, then click the Templates menu in the navigational header.
  2. Select the template that will serve as the base model for your passes, then click the Edit Design button.
  3. 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:
  4. 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 same project and template used for Format CSV.

  2. Click the Batch Importer button.
  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 go.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.

Next Steps

Distribute Passes

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