In This Section
Passes are distributed via URL. After you design a pass template, you can then generate pass URLs based on the template, 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.
- The URLs returned by the CSV Batch Importer are multi-use passes — they
can be downloaded by multiple devices.
- 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:
- Prepare your CSV file.
- Import the file and map fields.
- Submit the file for processing.
Features and options are explained along the way.
- Choose your project from the
Reach dashboard, then click the
Templates menu in the navigational header.
- Select the template that will serve as the base model for
your passes, then click the Edit Design button.
- 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:
- 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
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.
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
externalIdvalue 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
externalIdvalues will not be processed.
Import and Field Mapping
- Navigate to the same project and template used for Format CSV.
- Click the Batch Importer button.
- Click the Select a .csv file button. Only .csv files will be available
for selection. Choose the file you wish to upload.
- 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.
- Click the Confirm Mapping button after you have completed mapping each field.
- 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.
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:
In the above example URL,
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.