How Messages and Passes Work

This document explains how Urban Airship gets messages and passes to your users.

How Messages Work

Before you can send messages, you need:

  1. An app or website integrated with the Urban Airship SDK. The SDK enables communications with mobile devices and web browsers. However:

    • SMS and email notifications do not require an app or website.
    • Notifications sent to Open Channels do not require SDK integration, but your webhook server must be able to process and interpret a JSON payload.
  2. A container for your messages. This is the project. You will create a project for each app or website you want to communicate with.

  3. An audience of your app's or website's opted-in users.

    • Apple News notifications are sent to Apple News subscribers. The Apple News audience management is not handled via Urban Airship.

With those things in place, then:

  1. You create a message.

  2. Your app or website interprets the message via the Urban Airship SDK, displaying or delivering it to users.

    • SMS, email, and Apple News notifications are interpreted by a native client, and do not use or require the SDK.
  3. Users see your message.

Integration

To take advantage of Urban Airship, you must have an app, website, or another medium, e.g, SMS, email, etc., that you want to use to communicate with your users.

Mobile Apps and Websites

Your mobile app or website must include the Urban Airship SDK. The SDK is the mechanism for registering your users as channels in Urban Airship, making them eligible to receive non-SMS messages. The SDK also interprets message payloads that you send to your users and tracks user trends within your app.

The SDK also enables named user, Orchestration, and predictive features: Predictive Churn and Predictive Send Time Optimization.

SMS, Email, and Open Channels

You do not need to use the Urban Airship SDK for SMS, email, or open channels. However, these channels typically require you to use the API to register new channels and perform other features.

SMS and email are native messaging platforms; you can register users via the API, but you don't need to do anything special to communicate with your users via SMS or email.

However, while email and SMS channels are convenient mediums and easy to set up, they do not provide the orchestration and predictive features that help you better understand your user base. Data and analytic features generally require the SDK.

Open channels are platforms that are not natively supported by the Urban Airship SDK. To use Urban Airship with open channels, your open platform, e.g., chatbot, Slack integration, must be able to accept and interpret a JSON payload. Typically you will enable the delivery of the payload via a webhook server. See: Open Channels.

Your Project

Almost everything you do with Urban Airship, including creating messages, happens inside a project. A project is essentially Urban Airship's representation of your mobile app or website. A project:

  • Is a record for your mobile app, website, and any other channels you use to communicate with your audience.

  • Stores your message history, message templates, audience and analytic data, channel configuration, and default message configuration settings.

  • Contains the keys required to talk to various notification services.

You make use of all Urban Airship features from within a project or using your project's app key. Each of your apps or websites requires an individual Urban Airship project, which will have separate application keys and audiences. See: The SDKs and APIs: Authentication.

You create projects in the dashboard, Urban Airship's web interface located at go.urbanairship.com.

Your Audience

Your audience is the set of users that you want to send messages to.

Channels and Channel IDs

The underlying representation of an audience member is a channel, which is represented by a unique identifier, the channel ID. A channel contains all the necessary information that you (and the Urban Airship service) need to communicate with your users, including but not limited to: metadata used for targeting, associations with other Urban Airship or third-party identifiers, opt-in/opt-out status, orchestration data, and more.

To target a channel directly, use the channel_id which you will find in the channel object. The channel ID is a UUID representing an individual device, e.g., smartphone, browser, email address, etc).

Channel IDs are the atomic units of an audience and are assigned upon initial registration of a user. In the case of mobile apps and web users, our SDK creates the channel automatically. For email, SMS, and open channels, you must use our channel registration API to generate an addressable channel.

In most cases, however, it's not necessary to know the channel ID for each user in order to target either an individual user or groups of users. We have a number of other ways to group and target users such as tags, tag groups, audiences lists, segments, etc. See for details on other targeting mechanisms.

Selecting an Audience

In most cases, you won't concern yourself with individual channel IDs. You will instead select an audience based on things your channel IDs have in common. First you'll select which channels to address: Android, iOS, SMS, etc. Then you'll either select your entire audience, or just a section of your audience, based on tags, segments, and other identifying characteristics.

This is represented in the dashboard as:

  • All Users sends the message to your entire audience.

  • Target Specific Users lets you create a recipient group based on segmentation data. See: Target Specific Users.

  • Test Users are predefined recipient groups. After choosing Test Users, select from the Test Groups dropdown menu that appears. See: Audience: Test Groups.

  • Upload Users lets you upload a list of users just before sending the message. See: SMS Notification Tutorial: Upload Users.

Targeting

Urban Airship groups channel IDs by tag, named user, segments, audience lists, and more. In addition to your own tags, Urban Airship's predictive features group users based on how they use your app, their time zone, and other data reported by the SDK. You can use these grouping mechanisms to target specific sections of your audience.

Tags

Tags are plain-text identifiers for channel_ids. Some tags are assigned by Urban Airship as the SDK gathers relevant, identifying information from the SDK, e.g., time zone, locale, etc. But, in many cases, you can assign tags to users arbitrarily or based on actions within your app and in response to messages. For example, you might use tags to determine where a customer is in a particular engagement funnel — not opening notifications, opening notifications, acting on notifications, etc. See: Tags and Named Users.

Named Users

A named user is set of channel_ids that represent a single user. For example, if a user logs into your website and mobile app, a named user groups those channels into a single entity, so you can better understand a customer's behavior.

Named users are typically assigned by the SDK. You don't have use an external system or otherwise figure out which channel IDs belong to which people; we do that for you. Named users have most of the same characteristics as channel IDs; you can assign tags to them, select audiences of named users, etc. Named users are the atomic unit for Urban Airship's analytic features. You have to use named users to take advantage of the system's predictive features. See: Tags and Named Users.

Audience Lists

Use audience lists to create recipient groups based on either your own uploaded data or automatically generated lifecycle information.

  • Lifecycle lists are automatically generated by Urban Airship and capture app open, uninstall, notification, and dormancy information. Lifecycle List auto-generation may be disabled.

  • Uploaded lists are created by you, static, updatable, and can be reused.These are known as static lists in the API.

    Unlike tags and named users, which are set in response to client or can otherwise change without your direct intervention, static lists retain a list of users until you decide to change the list. Use an Uploaded list to generate a point-in-time audience.

  • Inline lists are created by you at the time of sending a message for that message only, and any previously unregistered address will be registered as a new channel at send time. They are not stored for reuse. Inline lists are used with SMS, Email, and Open channels only.

See: Audience Lists.

Segments

Segments are predefined groupings of your audience that you can construct using combinations of tags, audience lists, device properties, and location. Any segment you create can be used again for later messages. They can also be edited. Segments also support advanced selection, like location, time zone, and other options that may be inconvenient to set each time you create a message. See: Engage Segments Builder

Create Messages

You can create and send messages via the API or the dashboard. In the dashboard you choose workflows, which provide various message types, delivery rules, automation, and other options you can employ for your messages. Learn more in Message and Workflow Types.

How Passes Work

You:

  1. Create a container for the pass type you want to create. This is the project.
  2. Design the pass. This is the template.
  3. Generate a URL that points to the pass. This is the pass URL.
  4. Distribute the pass URL to recipients.

The recipients:

  1. Open the pass URL, then install the pass.
  2. Install the pass to their Apple Wallet or Google Pay digital wallets.

Create and Design

The first step of creating a pass is creating a project that will store the templates for that pass type. Projects can contain both Apple Wallet and Google Pay templates for a single pass type.

You must then design a template for your pass. The template holds the design, field information, and default field values for your pass. If designing passes to support both Apple Wallet and Google Pay users, you will design two templates, one for each platform.

You will then create a link to the pass that users can tap or click to install the pass. Android pass URLs can also be provided in a Save to Google Pay button. This pass URL can either be platform-specific — for either iOS or Android users — or you can create an Adaptive Link.

Adaptive links are the preferred pass-creation method. An Adaptive Link detects the recipient's platform and installs the appropriate pass. Instead of sending an Apple Wallet pass URL to one recipient group and a Google Pay pass URL to another (or both URLs to all recipients), you can associate the two templates using an Adaptive Link, then distribute that single Adaptive Link to all intended recipients.

Distribute

While you can use Reach to create passes, you cannot distribute passes via Reach. Since the pass is essentially a URL, you can send the pass however you would send any URL, such email or SMS. See: Pass Distribution Methods.

It's important to remember that you are sending a link to install a pass, not attachment to a message body. You should send a pass over a medium that you expect to reach your audience and persist, in case a user decides to dismiss a notification alert and install the pass at a later time.

If you are also an Urban Airship Engage customer, you can include the pass URL with all our message types. Depending on the message type you choose, you can link to the pass:

  • When the user taps or clicks the notification.
  • When the user taps a button.
  • From the body of the message.

Install

A user receives the pass URL, opens the URL, and then has the option to install the pass. The user only needs to install the pass once. They can then open the pass from Apple Wallet, Google Pay, or an app that relies on the respective Apple and Google APIs.

Update Content

After a user installs a pass, you can seamlessly update the pass as event information, gift card balance, loyalty points, and other information changes, so that your users are always up to date.

By updating an already-installed pass, you can ensure that your customers never miss their gates, and that they take advantage of the loyalty programs that bring them back to your business.

You can optionally continue to update content and appearance of a pass that has already been installed by a recipient. See: Publish Tutorial.

Get Started

Messages

To get messages to your users, you need:

The Engage Getting Started Guide walks you through the whole process.

Tip

Try sending messages now, using our 1st Flight app. No development required!

Passes

To get passes into the hands (devices!) of your users, you need:

  • An account on go.urbanairship.com.
  • A certificate for Apple Wallet or Google Pay.
  • A project to contain your certificate, templates, pass URLs, and other settings and information.
  • A template to generate your passes from.

The Reach Getting Started Guide walks you through the whole process, with links to individual tutorials for each step.