Dashboard Overview

The Dashboard is what we call the navigational and informational views of your Reach Projects. There are two levels:

  1. All your projects, listed at go.urbanairship.com/projects.

  2. An individual project, after you’ve opened it from the list of all your projects.

Your Projects

The top-level is a list of all your projects.


  • When logged in to go.urbanairship.com, return to Your Projects by clicking Reach in the navigational header.
  • Open an existing project by clicking its pane.
  • Click the New Project button to create a new project. See Design Passes for next steps.
  • Each project’s pane displays its name and an icon indicating its type.

Reach Dashboard

When you open a project from your list of projects, you are taken to the Reach Dashboard, where you can configure the project, create passes, set up triggers, view activity reports, and more.


The primary view displays several metrics tracking the usage statistics of your passes, including a current snapshot of the number of passes that have been created, installed, and removed in the history of the project.

  • Passes Created: The pass has been created but has not yet been added or deleted.
  • Passes Installed: The pass has been installed by the end user and has not been removed or deleted.
  • Passes Removed: The pass has been removed by the end user and not deleted. Deleted passes are removed from the Reach platform but remain on the end user’s device. Only end users can remove the pass. If a pass has been deleted, you will not have the ability to send any updates to the pass.

These metrics reflect the current count of passes rather than net pass activity. For example, if a user adds a pass, then removes the same pass, then adds the pass again, the Passes Installed count increases by one, while the Passes Removed count stays constant.

The Created metric only tracks Apple Wallet users.

Beneath the pass statistics is a per template breakdown of the same metrics.

The template name is followed by its ID and platform. Click a template name or the histogram icon at the end of a row to open its Activity Report.

Dashboard Menus

The project navigational header has four menus in addition to the Dashboard. Click to select.


  • Templates are the basis of the visual drag-and-drop interface of the Reach template editor, and they control the layout of Fields. A project can have multiple templates.
  • Reports show activity per template.
  • Triggers let you display content based on location or date.
  • Segments are used to update passes based on user tags.
  • Settings is where you manage the project’s details, barcode, certificates, and Associated App IDs. The project’s API key and secret are also available in the Settings menu.

Click Dashboard to return to the primary view.

Templates

The Templates in your current project are listed here. Click anywhere in a template’s row to see its expanded view, and click again to hide. If you have only one template in the project, the intial view is expanded.


Template Details

The Template Details pane displays the template Name, Description, ID, Custom ID, and creation date. Click Update to make changes to the Name, Description, or Custom ID, then click either the Save or Cancel button.

Entering a Custom ID overrides the template’s auto-generated default ID. After clicking Update, check the box to use a Custom ID, and enter your Custom ID in the field that appears.

Template Expiration

The Template Expiration pane displays the date when an Apple Wallet pass will expire. All passes generated from this template will expire according to the settings here. These settings can prevent the accumulation of stale passes in your end users’ wallets.

This feature is currently only available for Apple Wallet.

Passes with no expiration set will expire according to pass type defaults:

  • Boarding Pass/Event Ticket: Expires 30 days after pass creation.
  • Coupon: Expires 365 days after pass creation.
  • Loyalty/Member/Generic/Gift Card: Expires 730 days after pass creation.

Trial accounts can access this feature, but the account expiration overrides any expiry value that extends beyond the account expiration date.

Click Update to make changes, select the radio button for one of the choices below, then click either the Save or Cancel button.

  • Specify date: Set the date when passes generated from this template will expire.

    Click the date field and either use the date picker, or enter a date in MM/DD/YYYY format, then use the dropdown menu to select the time zone. Passes will expire at midnight on the specified date and time zone.

  • Specify duration: Set the number of days after pass creation when the pass will expire.

    Pass creation occurs either via the API or the CSV Batch Importer. Active length can be between 7 and 1,825 days. The default is 365 days.

  • Never: Passes generated from this template will never expire.

    This option is not available for boarding passes and event tickets.

Expired Passes

Expired passes display a greyed-out barcode and text “this pass has expired.”


Expired passes can be un-expired by updating the pass expiration date via the API.

Actions

Click to select an Actions option.


  • Edit Design lets you change the content in the seclected template. Follow the steps in Create Templates.
  • Batch Importer is used to generate pass URLs. See CSV Batch Importer.
  • Publish applies template changes to Apple Wallet passes that have already been distributed. See Publish.
  • Delete will remove the template from the project. Before the template can be deleted, you must expire or delete all passes associated with the template.

Publish

Apply template design changes to Apple Wallet passes that have already been distributed.

While Publish is not supported for Android Pay, Android Pay passes will automatically update with any changes made to class fields. For a full list of class fields, please visit the Android documentation. Any field preceded by class constitutes a class field.

Changes apply to:

  • Images
  • Logo text
  • Colors
  • Back of pass fields

With the exception of logo text, any changes made to fields on the front of the pass will not be applied to currently distributed passes.

Update Passes


  1. Choose which passes to update. Select the radio button for All passes, or A specific segment.
    • The number of passes that will be updated follows the option for All passes.
    • Choose a previously created segment from the dropdown menu, or click the link to create one now.

  2. Choose when to update the passes. Select the radio button for either Now or At a Specific Date and Time.
    If sending At a Specific Date and Time, either choose a date from the calendar that appears after clicking the date field, or manually enter in YYYY-MM-DD format. Use the dropdown menus to make time selections.

    • The time zone is when the pass will be updated, not the passholder’s time zone.
    • Scheduled updates must be within 30 days of the current date.
  3. Click the Confirm Publish button to apply template changes, or Cancel to discard.

    You will be returned to the list of project templates. Click the Publish button again to see the status in the appropriate History table. You will receive an email once the syncing process has completed, and the status will update in the Published History table.

History

The history of scheduled and published updates are displayed in separate tables.

Scheduled Updates

  • Scheduled to publish is the date and time when the template update process is scheduled to initialize.
  • Segment is either All Passes or the segment chosen for the update.

Published History

  • Start is the date and time when the template update process was initialized.
  • End is the date and time when the template update process ended.
  • Status displays either In Progress, Completed, or Error.
Cancel a Scheduled Update

In the Scheduled Updates table, click the trash can icon at the end of any row, then click the Yes button to confirm, or cancel to discard.

Reports

A Template Report is a graph plotting the number of passes created, installed, and removed over a selected time period. Unlike the overview statistics on the project’s Dashboard, the numbers in the Template Report reflect net pass activity. In the example of a user installing, then removing, then adding a pass, the template report counts this as two passes installed and one pass removed.


A Template Report is available for each template in the project. Display or hide a report by clicking the arrow to the right of the template name.

By default, the Activity Report displays 30 days’ worth of data. You may also select a filter option below the graph, or enter a custom range. To enter a custom range, click each date field and either use the date picker, or enter dates in MM/DD/YYYY format. Custom ranges must be between 7 days and 3 months.

The Export as CSV button sends a CSV file of the report data to the email address defined in your go.urbanairship.com account. See Managing Your Account: Account Info: Profile if you need to change the address.

Triggers

Set Triggers to make pass-relevant text appear on a user’s lock screen based on location and/or date. Clicking the text opens the pass. Beacons may also be attached to Apple Wallet templates.

The Templates in your current project are listed here. Click anywhere in a template’s row to see its Trigger settings in the expanded view, and click again to hide. If you have only one template in the project, the intial view is expanded.


Relevant Location text is displayed on a user’s screen when the device is in the vicinity of certain location.

Proximity requirements differ between Apple Wallet and Android Pay, and by pass type for Apple Wallet. An Apple Wallet coupon, for example, will appear within 100 meters of the set location, and a boarding pass within 1,000 meters, while proximity for Android Pay is 150 meters for all pass types. See the Location Radius column in the Pass Types Reference table.

Relevant Date text is displayed on a user’s lock screen at a certain date and time. If only Relevant Date is used, the text displayed will be similar to “Today at 12:30”; if combined with Relevant Location, the Relevant Location text will be displayed instead.

The timing when the relevant text appears is determined by Apple Wallet and Android Pay and varies by pass type.

See the table in Pass Types & Layouts for available triggers per pass type, requirements, and location radius and date window information.

Relevant Location

You may add up to ten Relevant Locations per template.

  1. Click the Add Triggers button, then the Add a Relevant Location button.
  2. Start typing an address in the Address field, then click to choose the address from the list of matches that appears.

    After selecting the address, its GPS coordinates will be listed next to the Location pane’s title.

  3. Optionally enter the Relevant Text that will appear on the lock screen when a passholder is near the Location, e.g., “Store nearby on 3rd and Main.”

    For Android passes, the Relevant Text is determined by Android, so it is not editable.

    If you would like to set multiple Locations, click the Add Another Location button and continue with your specifications. To remove an existing Location, click the X in the upper right corner of its pane.

  4. Click the Save Changes button, or Cancel to discard.

Relevant Date/Time

  1. Click the Add Triggers button, then the Add a Relevant Time button.
  2. Click the Select a day field and either use the date picker, or enter a date in MM/DD/YYYY format.

  3. Click the Select a time field and either select a time from dropdown menu, or enter a time in 24-hour notation, e.g., 16:47 for 4:47 p.m.

  4. Use the dropdown menu to Select a time zone.

    To remove an existing Date and Time, click the X in the upper right corner of its pane.

  5. Click the Save Changes button, or Cancel to discard.

Beacons

Apple Wallet supports the addition of up to ten Beacons per template. For information about implementing Beacons, please see our iBeacons Topic Guide.

  1. Click the Add Triggers button, then the Add a Beacon button.
  2. Enter the Beacon’s UUID

  3. Optionally enter the Beacon’s Major and Minor values, if any.

  4. Enter the Relevant Text that will appear on the lock screen when a passholder is near the Beacon.

    If you would like to set multiple Beacons, click the Add Another Beacon button and continue with your specifications. To remove an existing Beacon, click the X in the upper right corner of its pane.

  5. Click the Save Changes button, or Cancel to discard.

Segments

Segments are predefined groupings of your audience that you can construct using Tags in the Segments Builder. Target pass updates to your created segments. Segments are created within a project and can be used for any template within that project.

Tags are selected from — not created by — the Segments Builder. Select tags that you have already created and attached to passes. See the API: Tags documentaion.

You will see either a link to Create a segment now or a list of previously created Segments.

Three attributes are displayed per segment:

  • Segment Name
  • Date Created
  • Date Edited: The date and time when the list was last edited.

Click an action icon at the end of a segment row.

Pencil = Edit segment

Trash can = Delete segment
Click the Yes button to confirm, or cancel.

Create a New Segment

  1. Click the New Segment button to open the Segments Builder.
  2. Select whether the conditions you set will apply to All or Any passes in the project. The default statement is “Include passes where All of the following are true.” Use the All/Any dropdown menu to change your selection.

    • All = all criteria must be met (Boolean AND)
    • Any = any criteria must be met (Boolean OR)
  3. Choose is or is not from the next dropdown menu.

  4. Enter your search term, and click to select from the listed search results, if any.

    If you would like to set multiple conditions, click the Add a condition button and continue with your specifications.

    To remove an additional condition, click the X at the end of its row.

  5. Enter a descriptive name.

  6. Click the Save button, or Exit to discard.

Click the Segments menu link to return to your list of segments.

Updating a Segment’s Passes

To update a Segment’s passes, use the Publish feature.

Settings

Settings has five submenus. Details and options for each are below.

Project Details

Project Details displays the Project Name, Project Description, ID, Custom Project ID, and creation date.


  • Click Update or the Edit Details button to make changes to the Project Name, Project Description, or Custom Project ID, then click either the Save or Cancel button.
  • Entering a Custom Project ID overrides the project’s auto-generated default Project ID.
  • Clicking the Delete Project button is followed by a confirmation dialog. Before the project can be deleted, you must expire or delete all passes associated with the project.

Certificates

Manage your Apple and Android certificates for the selected project.


Apple Wallet

To integrate Apple Wallet with your account, you need:

  • An Apple Pass Type Certificate
  • The Certificate password

If you do not yet have them, see Getting Started: Certificate Set Up: Apple Wallet, then return to this screen to add them to your account.

Changing the Pass Type ID for the certificate used on your project will make it impossible to edit passes generated with the old certificate. For this reason, you should ensure you have uploaded a valid certificate before you begin making passes.

Add a New Certificate

Upload a new certificate to the project.


  1. Select the radio button for Upload a new .p12.
  2. Enter the Certificate password
  3. Click the Choose File button, and select the .p12 (exported certificate) file.
  4. Click the Save button, or cancel to discard.

Repeat these steps to add another certificate.

Select an Existing Certificate

Designate which previously uploaded certificate should be used with the project.

  1. Select the radio button for Select an existing .p12.
  2. Select a certificate from the dropdown menu.
  3. Click the Save button.

You may change the project’s certificate as often as needed.

If you have created any passes for a project and then change the certificate, Reach will be unable to interact with or update those passes. The certificate authorization will fail on those passes and they will be in an orphaned state.

Replace Certificate

Use Replace certificate when you need to upload a new certificate to your project, typically to replace an expiring certificate. The new certificate is validated upon upload to verify it has the same basename and Team ID as the original. If it is not a valid replacement, you are given the option to add it as a new certificate.


  1. Click the Replace certificate button.
  2. Select the radio button for Upload a new .p12.
  3. Enter the Certificate password.
  4. Click the Choose File button, and select the .p12 (exported certificate) file.
  5. Click the Save button, or cancel to discard.

Android Pay

Android Pay integration is initiated by Urban Airship. Please contact us to make your request for set up.

Barcode

Barcode displays information about your project’s selected barcode format and associated default values. You may change your barcode choice here, as well as edit the default values. Click the Edit Barcode button, make your desired changes, then click the Save button, or Cancel to discard.


Each heading is defined on the page. When editing, hover over the question mark icon near each element for more detail.

Encoded Barcode Value

  • If the barcodes should be the same for every pass, set the default barcode value here.
  • If the barcodes should be dynamic, differing for each pass, you must add specific keys to the header in the API.

Associated App ID

This section only applies to Apple Wallet only.

If you have an iOS app that works with your pass, you can add a link to the app from the back of a pass. Enter the app’s iTunes Store Identifier (ADAM ID) here to create an association between the app and the project. This places the link to the app on the back of the pass.


  • If the app isn’t installed on the device, the link opens the app’s page in the App Store.
  • If the app is already installed, the link will open the app.

There are two steps to enable this feature:

  1. Enable the iOS app for use with passes. See Configure the App ID.

  2. Create an association between the app and the project by entering the app’s iTunes Store Identifier (ADAM ID). See Add the ADAM ID.

Configure the App ID

Make sure you perform these steps using the same Apple Developer account that is associated with your app’s Apple Pass Type Certificate.

  1. Log in to your Apple Developer account, navigate to Certificates, Identifiers & Profiles, select App IDs from the left side menu, then click the row of app you want to edit. You should then see a list of services associated with the app.

  2. Click the Edit button at the bottom of the page.
  3. Check the box for Wallet, then click the OK button to confirm.

Although this change may take a few hours to propagate throughout Apple’s system, you do not need to resubmit your app for approval. You can now add the ADAM ID to your project.

Add the ADAM ID

  1. Click the Configure ADAM ID button.
    Existing ADAM IDs are listed in individual panes. Click the X at the end of a row to to delete.
  2. Enter the ADAM ID.

    A quick way to find the ADAM ID is to copy the numbers at the end of the app’s iTunes URL. If the URL is https://itunes.apple.com/app/id123456789, the ADAM ID is 123456789. Another way is to navigate to iTunes Connect in the iOS Dev Center, find your app, and copy the Apple ID.
    If you have another app to associate with the project, click the +Add An ADAM ID button to create an additional field. They will be listed as ADAM ID 1, ADAM ID 2, etc.

    When using multiple ADAM IDs, list them in order of priority—the only one that will be used is the first one that is compatible with the user’s device.

  3. Click the Save button, or Cancel to discard.

API

API displays your Project Key and Project Key, which are used for issuing requests to the Reach API.


Save to Android Pay

Save to Android Pay allows end users to save wallet objects from your website to Android Pay. See Passes: Distribute Passes: Save to Android Pay. To activate this feature, define an Origin URL.

  1. Click the Edit button.

  2. Enter the root URL where your Save to Android Pay button will be placed, e.g., https://www.mysite.com.

    The Origin URL is a list of domains to whitelist JSON Web Token (JWT) saving functionality. The Save to Android Pay button will not render if this field is not filled out properly.


  3. Click the Save button, or Cancel to discard.