Settings Menu Guide

The Settings section of the dashboard is where you control your project’s configuration, integrations, permissions, and more.

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

Edit Project

Edit Project is where you can change your project’s name, set its icon, and select its mobile platforms.

  1. Enter your project’s name.

  2. Optionally choose or change the project icon.

  3. Click to select or remove the platforms that will use Urban Airship. Selected platforms are highlighted blue.

  4. Click the Update Project button, or click cancel to discard your changes. Clicking cancel will return you to the project dashboard.

Delete your project by clicking Delete Project in the lower left corner.

Team Access

Team Access is where you can view and manage project-related responsibilities.

Accounts Registration

When you register on, two linked accounts are created:

  1. Company Account

    • Where projects are created and contained.
    • Controlled by a single User Account.
  2. User Account

    • The Owner of the Company Account.

Access Overview

  • Only the Owner of a Company Account can create projects for that company.

  • Access is set for each project individually.

    • User Accounts that have an assigned role for a particular project are members of that project’s Team.
    • When an Owner creates a project, the Owner is automatically its first Team member.
    • A User Account can only be an Owner of one company but may be a Team member of multiple projects.
  • Project Team members will only see the project functions that apply to their role(s). For example:

    • If you’re assigned to Composers Only, you will see in the project dashboard:

    • If you’re assigned to Reports and Composers, you will see in the project dashboard:
    • If you’re assigned to Reports Only, you will see in the project dashboard:

Users cannot create projects in Company Accounts they do not own. If you need a new project to be created in a Company Account that you are not the Owner of, the Owner of that Company must first create the project then invite you to the new project’s Team.

Role Responsibilities

Tasks by Individual Project Owner Administrator Full Access Reports Only Composers Only Reports & Composers Reports, Composers, Segments
Create a project X
Delete a project X
View App Key, Secret, and Master Secret X X X
Create Message Personalization Templates X X X
Modify project details X X X
Create and modify an IP Whitelist X
Send a Team Access invitation to a new individual X X
Change an existing Team Member’s project role X X
Remove a Team Member’s access to a project X X
Modify Team Management Security options X
Compose Messages, Automated Messages, and A/B Tests X X X X X X
View all user activity in the Team Management Activity log X
View, print, and export Reports X X X X X X
View, create, and modify Segments X X X X

Sending Team Access Invitations

  1. Click in the Team Member field, and it will expand, then fill out the form.
    • Team Member: Enter the email address or username of the user you want to invite.

      If the user has an existing Urban Airship account, enter the user’s Urban Airship username. Otherwise, enter the user’s email address. In either case, the user will receive an email with an invitation to accept the new access. See: Accepting Team Access Invitations.

      Usernames are case-sensitive. Always use the username, if available. If you enter an email address for an existing Urban Airship user and that user’s account is associated with a different email address than the one you are inviting, he or she may attempt to create a new account.

    • Access Level: Select from the dropdown menu. See Role Responsibilities for detail.

    • Send email from: Choose whether to send the invitation from your email address, or Urban Airship

      Your email address
      This is the best option, as the invitation will appear as being sent directly from you, and you will receive any bounce notifications in the case the email address is invalid. The invitation is also less likely to be caught in the recipient’s spam filter.

      Send from Urban Airship
      Some companies’ email servers enforce a rule requiring domain name and email sender fields to be the same. If this is true for your company, choose this option to ensure that your email goes through. However, you may also want to ask the recipient to look for this email and also check any spam filter for it.

    • Message: Optionally add a personal note.

    • Send a copy to yourself?: Optionally check the box to send yourself a copy of the invitation.
  2. Click the Share Project button, or click cancel to discard.

The new user will be listed in the Team Access list by username if an account already exists, or by email address if an account still needs to be created. Users with pending invitations have (pending) noted next to the username or email address.

When a user either accepts an invitation or creates an Urban Airship account, the (pending) designation no longer appears next to the username in the Team Access list.

If a user with an existing Urban Airship account declines an invitation, the user will be removed from the project’s Team Access list.

A user without an Urban Airship account will remain on the Team Access list as (pending) until access is accepted, or until manually removed.

Accepting Team Access Invitations

Users who do not yet have an Urban Airship account will receive email with subject Activate your Urban Airship account and a request to follow a link to confirm the email address and activate the account. Saving the password activates the account.

All users will receive an email to accept the project access at If already logged in, this is accessible by clicking the Account menu icon in the right side of the header, then selecting Team Management from the dropdown menu.

See Managing Your Account: Team Management: Engage for information about accepting invitations.

Changing Project Roles

  1. Click edit next to the user’s current Access Level.
  2. Select a new role from the dropdown menu.
  3. Click the Save button, or cancel to discard the change.

Removing Access

Using the same steps as Changing Project Roles, select Remove Access from the dropdown menu.


Platforms is where you add, manage, and remove the third-party messaging platforms you have configured for your project, e.g., APNS. If your account has been enabled for Apple News Push Notifications, Web Notify, or Open Channels, configure them here.

Click the Configure button to get started. The button is labeled Edit if already configured. If you have APNS configured, its expiration date will display, and you have the option to upload a new certificate.

Configuration fields vary per platform. For information about configuring new services, see the Getting Started documentation.

After making your changes, click the Save button, or cancel to discard.

To remove the platform from your project, click remove this service.

Web Notify

  1. Provide default Title, Action URL, and Icon URL, and view changes in the previewer.

    • Default Title: Typically your brand name.
    • Default Action URL: Typically your brand’s homepage URL. This URL will be where users are sent when they click on your notification.
    • Default Icon URL: Enter the URL for your default icon. If you have CDN enabled, you will see radio buttons to select either Upload Icon or Provide Image URL.
      • Ensure the URL will be accessible by your mobile audience. HTTPS is required.
      • Upload file size limit is 2MB.
  2. Check the box under Secure Bridge if you have a non-secure (non-HTTPS) website.

  3. Click the Configure My Project button to generate your SDK download files.

  4. Click the Download the SDK button, and save the zip file.

  5. Complete the steps in Web: Getting Started.

To remove Web Notify from your project, click remove this service.

You can override these default values on a per message basis via the UI or API.

Any time you would like to update the default values, you will need to repeat this process and update your website with the new configuration files.

Apple News

  1. Enter values for each field, and check the box for each of the Supported Countries you have configured in your Apple News publisher channel settings.

    • Channel Name: Your Apple News channel name. This is used for preview purposes in the Apple News composer.
    • Channel ID: Your Apple News channel ID.
    • API Key: Your Apple News API key.
    • API Secret: Your Apple News API secret.
  2. Click the Save button, or cancel to discard.

To remove Apple News from your project, click remove this service.

  1. Your Apple News channel ID has no relation to an Urban Airship Channel ID.
  2. We validate the country selection when the Send Now or Send When Live button is clicked as the final step in composing an Apple News message. If a country selected here is not configured in your Apple News publisher channel settings, you will see an error in the composer when attempting to send to that country.

Open Channels

Open Channels configuration requires your webhook URL. See: Open Channels: Set Up Your Webhook Server.

  1. Enter values for each field. All fields are required.

    • Name: The canonical name for programmatic use through our API. 20-character maximum. A-Z, a-z, 0-9, _, and - only. Choose a name indicative of the platform, e.g., slack or sms.
    • Display Name: The user-friendly name that appears in the Urban Airship dashboard, e.g., “Email”, “Smart Toaster Dev”.
    • Webhook URL: The URL + path to which we will deliver message payloads, e.g.,
    • Webhook Username: The basic auth username the endpoint requires.
    • Webhook Password: The basic auth password the endpoint requires.
  2. Click the Save button, or cancel to discard.

    After saving, a Validation Code field appears, containing a 36-character UUID. This code must be returned by the webhook server at <webhook_root>/validate. See: Open Channels: Set Up Your Webhook Server.

  3. Check the Enabled box to enable this for API use, then click the Update button, or cancel to discard.

    We do not validate the endpoint until you enable and save the configuration. We will revalidate it each time you update the configuration, as long as it remains enabled.

To remove Open Channels from your project, click remove this service. You must remove each Open Channels configuration individually.

Quickstart Guide

The Quickstart Guide walks you through the technical steps you need to perform in order to send your first push notification.

Documentation for implementing the Urban Airship SDK, connecting to push notification services, e.g., APNs and FCM, and configuring your project for push notifications is provided from within the guide.


Configuration is where you control the features and settings related to composing and sending messages.


Each feature is listed with a description and its minimum mobile SDK version. Toggle to enable/disable.

The On/Off feature controls only apply to functionality within the message composers. They do not enable or disable functionality at the API level.

  • Message Center: Deliver rich content to a message center in your app. SDK 2.0+.
  • Delivery by Time Zone: Schedule a message to go out at the same time in different time zones. SDK 3.1+.
  • Landing Page, Deep Link, URL, and Add Tags: UA Actions Framework. SDK 4.0+.
  • Remove Tags: Remove a tag when a user interacts with a push notification or button. SDK 4.0.
  • Notification Buttons: Interactive notifications for your app, including our 30+ out-of-the-box buttons. SDK 5.0+.
  • In-App Messages: Send a message that appears inside your app. SDK 6.0+.
  • Custom Keys: Pass key/value pairs of custom data through the push to your app. All SDKs.
  • Broadcast Push: Send to all devices. All SDKs.

Some newer Notification Buttons require a later SDK. See Built-In Interactive Notification Types for the full list and SDK requirements.

Not supported for Web Notify at this time: Message Center, Landing Page, Deep Link, Notification Buttons, and In-App Messages.

The Deep Link Action directs the user to a specific resource, either within your app or on the web. A deep link must be in the format of a URL. Deep link templates are URLs with placeholders in the path. Specify the path when composing your message — each segment appears as an individual text field. See the Actions topic guide for more about Deep Links.

Edit or delete existing deep links by clicking the pencil and trash can icons.

  1. Click the New Deep Link button.

  2. Enter a Name and URL for the deep link.
    • Name: Enter a descriptive name so you can easily identify it in the list of all deep links.
    • URL Template: Deep Link URLs have a maximum length of 255 characters. Template segments must be contained in curly braces: { }.
    • Allow Non-Standard URLs: Check this box to allow a non-standard URL pattern.

      The Deep Link Preview appears to the right of the entry fields. If the URL is entered in template format, each segment’s field is shown as it will appear when composing a message. The URL is validated as you type. A warning banner will appear if the URL format is incorrect, or if a single brace is used rather than an enclosing pair.
  3. Click the Save button, or cancel to discard.

Fields for template segments do not support slashes (“/”) .

If you want to send a Deep Link for, you must first edit the template to include both the category field (e.g., productivity) and the specific product field (e.g., calculator).

An alternative configuration would be to edit the URL template to read{widget}. You can create additional Deep Links for separate categories as necessary. For example, if you need a finance category, you can create a new deep link with URL template{widget}. This would save users from having to remember the full list of categories and their spellings.

Notification Buttons

Notification Buttons prompt a user to take specific actions within or outside of the app. Optionally include buttons when composing a message. Learn more in Interactive Notifications.

Edit or delete existing buttons by clicking the pencil and trash can icons.

Learn how to create custom buttons in the Custom Notification Buttons Tutorial.

Using Notification butttons in your message automatically creates Custom Events, where one event is assigned to each button. When viewing the associated Message Reports or the Event Tracking report, you will see a custom event listing for any button that has been pressed.

Android Notification Categories

Urban Airship Notification Categories map to Android notification channels.

After a developer has created Android notification channels within your app, add them here as Android Notification Categories. Then you can select a category as an Optional Message Feature when composing a message. Android O (8.0) only.

Edit or delete existing categories by clicking the pencil and trash can icons.

  1. Click the New Notification Category button.

  2. Enter a Name and Category ID.
    • Name: This name appears in the dropdown menu when you enable Notification Category as an Optional Message Feature.
    • Category ID: Enter the String id defined for your Android notification channel.
  3. Click the Save button, or cancel to discard.

In-App Messages

In-App Messages are banner notifications that appear inside of your app. Configure their display options, then click the Save button.

  • Primary Color is the color of the button text and message background. Enter a hexadecimal value.
  • Secondary Color is the color of the message text, button background, and certain UI elements, e.g., the drawer pull on iOS. Enter a hex value.
  • In-App Message Position controls whether the in-app message displays at the top or bottom of the screen. Select a radio button.
  • In-App Message Duration is the amount of time that the in-app message displays on the screen. The default is 15 seconds, or select the radio button for Specify, enter a numerical value, and select Seconds or Minutes.

Automation Limits

Automation Limits control over-notification to users who repeatedly meet Automation Composer criteria, capping automated messages per device per given time interval, e.g., a maximum of 4 messages every 10 hours. Add, edit, and delete Automation Limits here.

  1. Click the Add Limit button.

  2. Enter the maximum number of messages to be sent within the time period, then define the time period with a number of Hours or Days, no more than 48 hours or 90 Days. To add another, click the Add Limit button and continue with your specifications. Two limits are the maximum.

  3. Click the Save button.

Edit the limits at any time. Delete a limit by clicking the X at the end of its row.

Automation Limits occur at the project level. You can also create a Rule Limit for a specific message. For example, if you create an Automated Message with a trigger that is likely to occur frequently, a Rule Limit would prevent the repeated delivery of the same message to the user. See: Event Triggers: Options.

Indicator Locations

Automation Limits indicators are in multiple locations.

Automation Composer: The last option in the Setup section of the Automation composer.

Messages Overview: The bottom right corner of the Messages » Messages Overview » Automated tab.

Message Report: The top right corner of an Automated message’s Message Report.


A description of each Predictive type is below. Toggle to enable.

  • Churn: Analyze your app’s audience to identify user devices that exhibit behaviors indicating they are likely to become inactive. You must have at least one week of churn analysis before you can target churn risk groups. See the Predictive Churn guide for usage information.

Predictive is not supported for Web Notify at this time.

Platform Priority

Set your project’s Platform Priority order for use with the priority_platform tag. Any platform you have configured and enabled in Settings » Platforms is listed here. See the Orchestration guide for usage information.

Check the Enable box next to any platform you would like to include, change their order by using the directional arrows, then click the Save button. A confirmation banner will appear after saving changes.

  • When choosing the APP channel as priority, we will deliver to any iOS, Android, or Amazon devices that are opted-in to notifications.
  • Open Channels are listed using the name entered when adding the service in Settings » Platforms.

Your list of prioritized platforms is cascading; if the highest priority platform is opted-out or uninstalled, then the next highest priority platform will become that named user’s priority platform.

If a user has multiple opted-in channels on a given platform, e.g. both an iPad and iPhone on iOS, the message will be sent to both channels.

Additional processing time may be required to set the priority_platform tag for larger audiences. The priority_platform tag will be available for use after several minutes for smaller audiences and up to several hours for audiences of 1 million or more.

APIs & Integrations

Your API & Integrations information, options, and settings are all found here.

Urban Airship API

View your project’s App Key, App Secret, and App Master Secret. For more information, see: App Keys & Secrets: Security.

Custom Event Tokens

To send custom events to Urban Airship that originate from outside of your app or website, you must generate a custom event bearer token for the authorization header in your request.

For details about adding events from external systems, e.g., CRM or POS databases, see Add Custom Events in our Server-Side Custom Events documentation.

Create a Custom Event Token

  1. Click the Create Token button.
  2. Enter a token name, then click the Create Token button.

  3. Copy the values, then click the Got it button to close the window.

    You will not be able to view the App Key and Access Token after leaving this screen, so copy and save them now.

Remove a Custom Event Token

  1. Click the Revoke button next to any token.

  2. Check the box to confirm your understanding, then click the Delete button.

Named Users

By default, Named User association can only occur server-side, via the API. The setting in this menu overrides that preference, enabling client-side Named User association. Toggle to enable. See the Integration Options Primer for requirements and usage information.

Before enabling client-side association, consider your use case. By restricting association to server-side calls only, you have the added security of requiring your master secret to be verified after each call. While this creates a more secure call to association, you also lose the convenience of having your application automatically associate named users on login. Most apps will not require this additional security, but if your app deals with extremely sensitive data, you may want to consider leaving this disabled and doing named user association exclusively through the API.

Tag Groups

Tag Groups are configurable namespaces for organizing tags. Primary Device Tags is a predefined Tag Group, and you may create up to 100 custom Tag Groups. See Tag Groups Walkthrough for usage information.

Existing tags associated with your mobile audience are listed under Primary Device Tags. In most cases this means all the tags that are currently being set via the Urban Airship SDK based on users’ interaction with the app. For example, if you send a push that sets a tag on a user after they tap it, then that tag is added to the Primary Device Tags group.

The pane for a disabled Tag Group is grey. See: Edit a Tag Group.

Create a Tag Group

Tag Groups cannot be deleted, and the Group Key field and security setting cannot be edited. Please double check that the Group Key is correctly filled out and the security setting is appropriate.

  1. Click the Create Tag Group button.

  2. Enter a Name, Description, and Group Key for the new tag group.
    • Name: This Name appears elsewhere in the UI, so choose something easily understandable that directly links back to the associated database, e.g., “Loyalty Database Tags.”

    • Description: The Description should supplement the title, giving additional information about the Tag Group, if necessary. Be descriptive enough that anyone in your company would understand its source and purpose.

    • Group Key: This permanent, unique ID is the text you will use when referring to your Tag Group in the API. While you can use any characters for the Group Key, it is highly recommended that you exclusively use lowercase ASCII characters. No spaces are allowed in a group key. Example: pos-database.
  3. Optionally check the box to Allow these tags to be set only from your server. This enables high security for read-write operations, only allowing tags be read or changed by API calls authenticated with your master secret key.

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

Urban Airship reserves Tag Groups prefixed with "ua_". Any Tag Groups you might create with that prefix will not function.

Without this Security setting enabled, tags can be read and written from an app using only the application secret. By enabling the high security setting, read-write operations must be validated with your master secret key, preventing attackers from using the app secret to set or read their own device tags. Whether or not your app will benefit from this added security depends on the use case. If preventing attackers from reading or setting their own device tags is absolutely critical, consider enabling this feature.

Edit a Tag Group

  1. Click the pane of a custom Tag Group.

  2. Make your desired changes.
    • Only Name and Description are editable fields.
    • Disable a Tag Group by unchecking the Enable this Tag Group box.
  3. Click the Save button, or Cancel to discard.


When sending an Automated message, you may choose to trigger sending the message based on Location. Location Triggers require integration with the Gimbal Platform. See Location Triggers for requirements and set up information.

Gimbal is supported for iOS, Android, and Amazon platforms only.

If you have already configured Gimbal, you have two options:

  • Sync location data from Gimbal: Click the Sync Now button.
  • Delete your current Gimbal Server API key: Click remove this API Key. A warning displays with confirmation steps. Check the box for I would like to proceed and click the Yes, remove button, or click the Nevermind button to cancel.

Test Push

The Test Push form is a simple utility for testing push notifications without needing to format HTTP requests using a Command-line tool such as cURL. One tab is displayed per platform. Platforms are configured in Settings » Platforms.

The Test Push form supports sending test notifications to iOS, Android, Windows Phone 8 and Windows 8. Amazon is not supported, and no new delivery platforms will be added to this legacy utility in the future.

Select a tab, fill out the fields, then click the Send it! button. Fields per platform are listed below.


  • Channel ID or Device Token: Specify the device you are sending the test push to by entering a Channel ID or device token.
  • Badge: Enter a badge value to indicate an unread count. Alternatively, you may use the autobadge feature.
  • Alert: Enter the text to be displayed in the alert view.
  • Sound: Specify a custom sound for the alert. A Core Audio Format (CAF) file must be present in the application build in order to play the sound. If no custom sound is provided, the default sound will play.
  • Payload: Use JSON to specify the notification payload. It is not necessary to enter the JSON directly into this field; the field will automatically populate based on the values given in the fields above.


  • Channel ID or APID: Specify the device you are sending the test push to by entering a Channel ID or APID.
  • Alert: Enter the text to be displayed in the alert view.
  • Extra key: Pass an extra (custom) key to the app in the notification payload.
  • Extra value: Pass a value for the extra key.

Windows 8 / Windows Phone 8

  • APID: Specify the device you are sending the test push to by entering an APID.
  • Alert: Enter the text to be displayed in the alert view.