Audience

The Audience section of the dashboard contains information about your app’s users, and tools to help you effectively target your messages.

Choose your app from the Urban Airship dashboard, click the Audience dropdown menu, and make your selection. Each section’s purpose and options are detailed below.

Segments

Segments are predefined groupings of your audience that you can construct using combinations of Tags, Lists, Device Properties, and Location, using the Segments Builder.

Navigate to Audience » Segments. You will see either a “Get started…” message or a list of previously created Segments.


Three attributes are displayed per segment:

  • Name
  • Created: The list’s creation date and time.
  • Last Modified: The date and time when the list was last edited.

The segments list is sortable by Name, Date Created, and Date Last Modified.

To edit or delete a segment, click the gear icon at the end of its row, and choose Edit Segment or Delete Segment. See Editing Segments for detail and caveats. There is no confirmation step for deleting a segment.


Create a New Segment

  1. From Audience » Segments, click the New Segment button to open the Segments Builder.


  2. Select a Condition type from the dropdown menu. Your first condition has the default selection Tag.


    Details and options for each condition type:

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

  3. Optionally include nested logic. Click the gear icon at the end of a condition’s row, and select Add an Alternative. You also have the option here to Remove Condition.


  4. Optionally change Boolean logic values that will apply to each segment condition. The default statement is “If All of the following are True.” Use the All/Any and True/False dropdown menus to change your selections.

    • All = all criteria must be met (Boolean AND)
    • Any = any criteria must be met (Boolean OR)

    You can change the Boolean logic for the nested statements as you can for the entire expression.

  5. Enter a descriptive Name.

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

Navigate to Audience » Segments to return to your list of segments.

Editing Segments

From Audience » Segments, find the segment in the list, then click the segment name, or click the gear icon at the end of its row, and choose Edit Segment. You have access to all the options available in the steps to Create a New Segment.

When editing a segment, be mindful of any scheduled pushes that target that segment. If you have a scheduled push that targets a segment, and you edit that segment some time after the push’s creation, the push audience will not be updated to match the new segment. The scheduled push will be sent to the version of the segment that existed when the push was created, rather than the updated version.

If you want the scheduled push to target the updated segment, you must manually update the push. Navigate to Messages » Messages Overview, and click the Scheduled tab. Find the push in the list, click the Edit icon at the end of its row, then click Yes to confirm. You do not need to change the message itself — just click Review & Schedule in the progress header, then click the Schedule Message button. The targeted audience will be updated to reflect the changes made to the edited segment.

Sending to Segments

Select the radio button for Target Specific Users when defining your audience in the A/B Tests or Message composer.


See Target Specific Users for detail.

To send to a segment via the API, see the Segments API documentation.

Condition Types

The Segment Builder has three condition types. Details and options for each are listed here. See Create a New Segment for the full procedure.

Location

If your app uses Urban Airship’s historical location service, you may include location criteria in your Segments. Three months’ location history is the default data retention package, with options to retain six or twelve months’ location history. See the Data Retention Schedule.

Add location criteria for users who have or have not recently been in a location within a defined time period.

  1. Select Location from the segment condition dropdown menu.

  2. Choose has been or has not been from the next dropdown menu.

  3. Click the Select a location button, search or explore locations, and apply your selection. See Location Picker for usage detail.

  4. Constrain the time period for the location event. The default statement is “within the last 6 hours.” Use the dropdrown menus to choose within the last or between.


    For within the last, enter a numerical value and select hours, days, weeks, or months. Always use a number greater than 1, otherwise the system will only check the current period. We recommend using long time periods during testing. See Time Bucketing: “Within the Last X” for additional detail.

    For between, click the Select a date range button. Click a Select by option to choose a range type.


    • Year, Month, Week, and Day display a calendar on the left side of the pane. Click to make your selections.
    • Hour includes the calendar, as well as dropdown menus for the time and AM/PM.

    Make your selections for both Start Date and End Date, then click the Apply button.

Tag

Tags are selected from — not created by — the Segments Builder. Tags are generated from the app by sending a notification that adds that tag to users’ devices, and at least one user must have interacted with that notification.

  1. Select Tag from the segment condition dropdown menu.

  2. Choose is or is not from the next dropdown menu.

  3. Click the Select a tag button and choose Primary Device Tags, Device Property Tags, Predicted to Churn, or a tag group, if any. Tag groups use the same search method as Primary Device Tags.


    • Primary Device Tags are existing tags associated with your mobile audience. Enter your search term, and click to select from the listed search results, if any.

    • Device Property Tags are updated daily. Choose from the following, then enter your search term, and click to select from the listed search results, if any. Exceptions to Search are noted.

      • Push Notification Opt-in: Select Opted-in or Opted-out.
      • Timezone
      • Language
      • Language Country
      • iOS App Version
      • Android App Version
      • iOS Version
      • Android Version
      • iOS Model
      • iOS UA SDK Version
      • Android UA SDK Version
      • Background Enabled: Select Background Enabled or Background Disabled
      • Location Enabled: Select Location Enabled or Location Disabled

    • Predicted to Churn tags are audience risk profiles based on user behaviors indicating they are likely to become inactive, and are updated weekly. See Settings: Configuration: Predictive to enable this for your app, and the Predictive Churn topic guide for usage information. Choose from the following.

      • High risk: Users most likely to become inactive.
      • Medium risk: Users who exhibit signs of potentially becoming inactive.
      • Low risk: Users least likely to become inactive.

List

Include either Lifecyle Lists or Uploaded Lists in your segment. For more information about Audience Lists, see Audience Lists.

  1. Select List from the segment condition dropdown menu.

  2. Choose is or is not from the next dropdown menu.

  3. Click the Select a list button and choose Lifecyle Lists or Uploaded Lists.


    • Lifecycle Lists are divided by type, then by time interval and associated Devices count. To select, click the time interval for a Lifecycle List type.
    • Uploaded Lists are searchable. Enter your search term, and click to select from the listed search results, if any.

Geographic Location Criteria

Location Picker

When creating a location-based segment condition, you use the location picker, which has Search and Explore modes. Search is the initial mode.

Search

Enter a search term in the box, and results, if any, display on the map and are listed in the right-side pane.

Explore

Click the Explore icon to the left of the search box, and results for the mapped area, if any, display on the map and are listed in the right-side pane. The quantity/density of location points is determined by the level of zoom. Click and drag, and use the +/-zoom controls to change the displayed area.

Click a location on the map, and its corresponding result will highlight in the results pane, and vice versa. Click again to toggle on/off the location boundary.

Click Filter Results at the top of the results pane, make selections by checking boxes, then click the Apply button. You may also use the All, None, and Clear options as you make your selections.

Time Bucketing: “Within the Last X”

When creating a Location-based segment condition, you have the option to include location events that occurred “within the last” number of hours, days, weeks, or months.

Understanding how we “bucket” location events according to a given time period is important to know when using this feature.

  1. All time periods are in UTC.

  2. We view time in bucketed time periods for hours, days, weeks, and months.

    • Hour starts at X:00 UTC
    • Day starts at 12:00 AM UTC
    • Week starts at 12:00 AM UTC on Monday
    • Month starts at 12:00 AM UTC on the first day of month

  3. When choosing “within the last” for a given time period, you are selecting all location events that have occurred from the beginning of the most recent time bucket until now.

    Examples

    1. “within the last 1 hour” does not equal the last 60 minutes. It equals the time from the beginning of the current hour (UTC) until the time the segment is created.

      If you create a “within the last 1 hour” segment at 11:19 AM, you will have a segment that contains all devices that were in location X from 11:00 AM UTC until 11:19 AM UTC.

    2. “within the last 1 day” does not equal the last 24 hours. It equals the time from 12:00 AM UTC on the day the segment is created until the moment the segment is created.

      If you create a “within the last 1 day” segment at 11:19 AM, you will have a segment that contains all devices that were in location X from 12:00 AM UTC until 11:19am UTC.

    3. “within the last 2 weeks” does not equal the last 14 days. It equals a full 7-day week (the week preceding the current week) AND whatever portion of the current calendar week that has passed when the segment is created.

      If you create a “within the last 2 weeks” segment at 11:00am on Wednesday, August 12, you will have a segment that contains all devices that were in location X from 12:00am UTC, Monday, August 3, until 11:00am UTC, Wednesday, August 12.

Estimated Audience

Before pushing to a segment, you may want to know how many recipients are included in that segment. The Estimated Audience is displayed in the lower right corner in the Segment Builder when you are creating, editing, or viewing a segment.

To view an existing segment, from Audience » Segments, find the segment in the list, then click the segment name, or click the gear icon at the end of its row, and choose Edit Segment.

Two rows show the total Estimated Audience and Opted-In counts, as well as counts per configured platform. The values update dynamically following each change to segment conditions.


  • Estimated Audience is the total estimated audience accessible through push notifications, in-app messages, and Message Center.
  • Opted-In contains members of Estimated Audience who have opted-in to receiving push notifications.

Estimates are based on a sampling of your audience that meets the segment criteria. A 95% confidence interval is calculated from the sample, and the rounded midpoint of each interval is displayed.

The sampling is specifically based on metadata associated with channels . Named Users and their metadata are not considered. For example, tags set on a Named User will not be calculated.

For a more detailed look at the estimate, hover over any value to see the confidence interval upper and lower bounds, giving you an idea of how much variance the estimate involves.


Due to a number of potential unknowns, including device on/off states, connectivity, and the disparities and limitations of iOS and Android, it is impossible to measure and maintain with 100% certainty the number of recipients. Given these constraints, our sampling model provides the most up-to-date estimate possible.

Lists

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

Uploaded Lists must be in CSV format, with a maximum of 10 million rows and a maximum file size of 1.5 GB.

Lifecycle Lists capture app open, uninstall, notification, and dormancy information. Lifecycle List auto-generation may be disabled.

Uploaded

When you navigate to Audience » Lists, the default tab is Uploaded, where you will see either “no lists” or previously created Uploaded Lists.

Five attributes are displayed per list:

  • Name and description
  • Status: Ready indicates that your list may be used as a message recipient group. Processing indicates that our servers have not yet completed the upload. Failed indicates that your list failed to upload.
  • Devices: The number of channels associated with the list. Note that this count simply reflects the number of valid channel identifiers associated with a given list. Uninstalled channels may still be reflected in the channel count, meaning that sending to a list may result in a send count lower than the channel count. Read additional detail in Troubleshooting.
  • Created: The creation date of the list.
  • Last Modified: The date the list was last edited.

Lists are sortable by Name, number of Channels, Date Created, and Date Last Modified.

Attribute information may contain a combination of values from both the last uploaded list and the last successfully processed list. For example, if the processing step fails after you edit an existing list, the Status indicator will read Failed, but Devices and Last Modified will display information from the last successfully processed list.

You can create up to 100 Uploaded Lists per application. Because lists are static, they can become outdated very quickly. We encourage active curatation of lists, updating them with current data as frequently as possible.

Lists containing 100+ devices that have not been used for message delivery or updated in the past 90 days will be automatically deleted.

CSV Format

Uploaded CSV files are limited to a maximum of 10 million Named Users, Channel IDs, or Aliases, and a maximum file size of 1.5 GB. Each row must be an identifier_type,UUID pair. For example, these could be the first four rows of a valid CSV file:

ios_channel,5i4c91s5-9tg2-k5zc-m592150z5634
ios_channel,90c09202-940s-3920-b9028tfs0820
android_channel,fi9458d2-90s1-z903-f8235u9u2oj2
named_user,SDo09sczvJkoiu

Create a New List

  1. Click the + List button in the upper right corner of the Lists page.

  2. Enter a descriptive Name so you can easily find it when selecting your audience. The Name may not be changed after you save the list.

  3. Enter a Description that explains what kind of identifiers are contained within your CSV file.

  4. Click the Choose file button, browse and select your file, then you will see the button label change to Uploaded List.


    If you need to choose a different file before saving the list, click clear next to the Uploaded List button. You will see the button label change back to Choose file, and you can start again.

  5. Click the Save button, and you will be returned to the Uploaded tab, where your new list’s status will likely be Processing. Once the Status is Ready, you can send to your new list.

    Processing time is generally quick but varies depending on the size of your list and server load. Small lists can process within seconds, while large lists may take 5 or 10 minutes. We recommend uploading lists at least a few hours before you need to send to them. This will give you plenty of time to address any potential errors.

    See Troubleshooting if your list’s Status is Failed.

When a new list is uploaded, an empty list is created first while the list identifiers are processed. Please be sure the new list completes processing and displays a Device count before sending to it. It is possible to upload a new list and then immediately send to it, resulting in zero (0) sends because it hasn’t completed processing.

Lists that contain a significant number of Aliases will likely require longer than normal processing time. If you are using Aliases, consider upgrading to using Named Users. Read about upgrading from Alias to Named User.

You can create an empty list by completing Create a New List steps but without uploading a CSV file. This list can be used via both the UI and API, but it will, of course, send to 0 devices. This may be useful if you want to send a scheduled message to a list but you haven’t yet finished collecting the data necessary to construct the CSV file.

Create an empty list, then compose the scheduled message, selecting the empty list as the audience. Once your CSV file is ready, edit the list, and upload the CSV file. The message will be sent to your intended recipients as long as the upload has completed processing and the list Status is Ready before the scheduled send time.


Editing Lists

You may edit an Uploaded List’s Description and CSV file. From the Uploaded tab, find the list you want to edit, then click the Edit icon at the end of its row. Complete the Description and CSV file upload steps as instructed in Create a New List.

If you replace a CSV file or add one to a list that was created without an uploaded CSV file, be advised that:

  • The CSV file will be processed in the same manner as a new list.
  • The previously uploaded list is available during processing.
  • All existing scheduled messages will use the most recent processed list.

You cannot append new values to an existing list by uploading only the new values. To extend a list with additional identifier_type,UUID pairs, you must update the original CSV file with those values, then edit the list, uploading the new CSV file that contains both the original pairs and the additions.


Troubleshooting

Failed Upload

If your Uploaded List shows Status Failed, review these typical causes:

Invalid UUID
One or more of the given UUIDs are invalid. See this page for more information on properly formatted UUIDs.

Invalid identifier type
You included an identifier type that is not recognized by the uploader. The valid identifier types are ios_channel, android_channel, amazon_channel, alias, and named_user.

Too many identifiers
The list uploader supports up to 10 million identifier_type,UUID pairs. Exceeding this limit will result in an error.

Too many lists
You can have up to 100 Uploaded Lists. Attempting to create more than 100 Uploaded Lists will result in an error.

Wrong number of columns
CSV files must be two columns, containing identifier_type,UUID pairs. If you attempt to upload a CSV file composed of more or fewer than two columns, the uploader will return an error.

Invalid name/description
Names and descriptions can have lengths of up to 64 and 10000 characters, respectively. If one of these limits is exceeded, the uploader will return an error.

Timeout

Upload may timeout due to a poor internet connection. If so, the file upload must be attempted again. To ensure that the entirety of a given list is successfully processed, we do not support partial uploads.

Devices Count

As stated in the attributes explanations above, the Devices count is the number of channels associated with a list. When interpreting this number, keep in mind:

  1. If your CSV file contains Aliases or Named Users, the Devices count may be higher than the number of rows in the CSV file. This is because each Alias and Named User is resolved into the corresponding devices. For example, if your CSV file contains an entry for named-user-123412 and this named user has eight associated channels, then 8 will be added to the Device count.

  2. The Devices count includes both users who are opted-in and opted-out of push. For example, if you send a push to a list of 1,000 devices where 600 of the devices are opt-in, only 600 devices will receive that push, whereas an in-app message would go to all 1,000 devices. This distinction between a list’s Devices count (total devices) and opt-in devices is important to know when viewing a push-to-list’s Total Sends metric — Total Sends will correspond to opt-in devices rather than the Devices count.

  3. In order to improve processing time, Urban Airship does not validate that channels are active and addressable when they are processed by our system. We only validate that channels have the right format. This means that any channels that have either been uninstalled or are incorrect but in proper format will still be reflected in the total channel count when the list is done processing, and sending to the list will result in a lower send count than was on the list of channels.

Lifecycle

Lifecycle Lists are automatically generated Audience Lists that capture data about your users’ app opens and notification receipts. This data can be used to target users based on app activity. For example, with Lifecycle Lists you have a built-in recipient list of all users who have opened your app in the past 7 days.

Navigate to Audience » Lists, and click the Lifecycle tab. If it is your first time using Lifecycle Lists, click the Turn On button.


Once initially enabled, your first Lifecycle Lists will be available in 24 hours. The delay is necessary in order to populate the minimum data required for the shortest time interval: Last Whole Day.

You can turn off this feature at any time after your first lists are generated. At the top of the Lifecycle tab, toggle to disable.


List Types

  • First App Open: Opened the app for the first time within the given time interval.

  • Opened App: Opened the app within the given time interval.

  • Uninstalls: Devices that have been marked as uninstalled within the given time interval. Note that you must attempt to send a push to an uninstalled device before our system marks it as uninstalled. For details, please see Detecting Uninstalled Devices.

  • Sent Notification: Devices that have received a notification within the given time interval.

  • Direct Opens: Opened the app directly from a notification within the given time interval.

  • Dormant: Given a time interval X, the dormant list contains users that have not opened the app in the last X days, but did open the app at least once in the X days prior to not opening the app. Tooltips provided in the UI give actual values.

Android devices with faulty registrations may be included in the Uninstalls list regardless of whether or not they have an active installation of your app. Consequently, the Uninstalls list may contain a small number of devices that have not actually uninstalled your app.


List Detail

Each list type has three time intervals: Last Whole Day, Last 7 Days, and Last 30 Days. Whole Day is defined as a period of time commencing and terminating at midnight UTC.


Each list type’s pane displays its name, definition, and the following per time interval:

  • Processing status indicator: A green circle with a check mark has hover text “Successfully processed.” A yellow triangle with an exclamation point has hover text “Failed to process. Please contact support@urbanairship.com.”

  • Time interval days, dates, and time zone.

  • Last Processed day, date, and time zone.

  • Download CSV link: See the Lifecycle List CSV Download topic guide for usage information.

  • Devices count: The number of channels associated with the list. As with Uploaded Lists, the Devices count includes both users who are opted-in and opted-out of push. For example, if you send a push to a list of 1,000 devices where 600 of the devices are opt-in, only 600 devices will receive that push, whereas an in-app message would go to all 1,000 devices. This distinction between a list’s Devices count (total devices) and opt-in devices is important to know when viewing a push-to-list’s Total Sends metric — Total Sends will correspond to opt-in devices rather than the Devices count.

Sending to Lists

Select the radio button for Target Specific Users when defining your audience in the A/B Tests or Message composer.


See Target Specific Users for detail.

To send to a list via the API, see the Static Lists API documentation.

If a Lifecyle List or Uploaded List is processing, you will not be able to send to the list until processing has finished.

If you edited an Uploaded List and it is still processing, you can still send to the list, but the recipients will be from the pre-edited version.


Test Devices

When selecting your audience in the A/B Tests or Message composer, you have the option Test Devices, which is a predefined recipient group. Once you are satisifed with a trial message sent to Test Devices, just change the audience type and send your live, production message.

By keeping a saved list of approved test devices in the Urban Airship dashboard, you can be sure that during testing messages will only reach the specific devices on your list. You might limit these to company employees such as Product staff, Development team, et cetera.

The Test Devices feature is supported on Android and iOS devices, and requires an Enterprise Edition account. Only Administrators can create a Test Devices list. See the Team Access settings for more information about user roles.


Setting Up Test Devices

Enter up to 100 comma-separated Device Tokens and Android Channels, then click the Save button. Only registered device identifiers that have not been uninstalled can be entered.

Administrators may edit and save changes to the Test Devices list at any time.

Sending to Test Devices

Select the radio button for Test Devices when defining your audience in the A/B Tests or Message composer.

How to Find Your Device Identifier

You must build into your app a mechanism to expose the device identifier to the console:

You can view the console with these tools:

iOS

Android

If you didn’t write the device identifier to the console, you can use the steps here to help retrieve it: Using Charles Proxy to profile an Urban Airship Implementation.

Device Lookup

Information about an individual device can be found by looking up a Channel ID, Named User ID, or Device Token. Enter a device identifier into the search bar.

If a valid identifier was entered, you will see a display with information about associated devices. This example shows the results for a Named User ID search, including Created and Last Modified dates for the Named User itself, as well as information for each device associated with the Named User.

Depending on the ID type queried and data available, results may include:

  • Channel ID, Named User ID, or Device Token
  • Installation, Opted In, and Background status indicators
  • Created date
  • Last Registration date
  • Aliases
  • Push Address
  • Tags
  • Timezone
  • Language Country
  • Language
  • [OS] Model
  • [OS] Version
  • [OS] UA SDK Version
  • [OS] App Version
  • Location Enabled status
  • Push Notification Opt-in status
  • Background Enabled status

Device Tokens

A device token is an identifier for the Apple Push Notification System (APNS) for an iOS device (iPhone or iPad).

This page lists all iOS device tokens associated with your app and returns the following information per device token:

  • Created date
  • Last Registration date
  • Status
  • Alias
  • Tags

See Apple’s APNS documentation.

Android Channels

Channels are a type of Urban Airship push identifier for Android, Windows 8, and Windows Phone 8 devices. When an end user runs your application for the first time after installing it, a Channel is created and returned to Urban Airship. As of the Android 5.0 SDK, Airship Push Identifiers (APIDs) are known as Android Channels.

This page lists all Android Channels associated with your app and returns the following information per Android Channel:

  • Created date
  • Last Registration date
  • Status
  • Alias
  • Tags
  • GCM Registration ID

See the Channels Primer.