Engage 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 Engage 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. See: Engage Team Access.


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 or Web Notify configure them here. For Open Channels, click to select from the left side menu.

Platforms that have not yet been configured appear greyed-out and have a Configure button. Click the Configure button to get started. The button is labeled Edit if already configured. If you have APNS configured for iOS, its expiration date is displayed, and you have the option to upload a new certificate.

Configuration fields vary per platform. For information about configuring new services, click the Quickstart Guide button in the upper right corner.

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 dashboard 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 workflow.
    • 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 creating an Apple News notification. If a country selected here is not configured in your Apple News publisher channel settings, you will see an error in the dashboard when attempting to send to that country.

Open Channels


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

Each Open Channel is listed by its configured Display Name followed by its canonical Name, newest channels first. Disabled channels appear greyed-out.

Click the + Configure New Open Channel button and follow our set up steps, or click the Edit button to make changes to a previously configured channel.

After making your changes to an existing channel, click the Update button, or cancel to discard.

To remove a channel from your project, contact Support.

Configure an Open Channel

  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., "Alexa," "Smart Toaster Dev.""
    • Webhook URL: The URL + path to which we will deliver message payloads, e.g., https://acme-toaster.appspot.com/api/channels/production.
    • 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.

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 creating and sending messages.


Control features available in the dashboard workflows. 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 workflows. 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 creating your message — each segment appears as an individual text field. See: Message Actions: Deep Link and Button Actions: Deep Link.

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 creating 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 http://widgets.com/productivity/calculator, 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 http://widgets.com/productivity/{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 http://widgets.com/finance/{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 creating 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 buttons 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 creating 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 Message Design


This section applies to in-app messages created via the Message, A/B Test, and Automation workflows, and Push Templates.

Configure the default appearance of In-App Messages, 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.

In-App Automation Design


This section applies to in-app messages created via the In-App Automation workflow only.

Configure the default appearance of In-App Messages created via the In-App Automation workflow. After making changes, a confirmation banner will appear in the lower left corner of the screen.

Each message style has its own tab. Colors are entered as hexadecimal values. The default value for all color fields is white (#FFFFFF).


  • Background Color: The color of the message background. Enter a hexadecimal value.

  • Dismiss Action Color: The color of the dismiss element. For modal and full screen messages, this is the color of the "X" button used to dismiss the message. For banner messages, this is the color of the drawer pull element that indicates the direction the user can swipe to dismiss the message. Enter a hexadecimal value.

  • Placement: Determines the screen position of a banner message. A message set to Top will appear by animating down from the top of the screen. A message set to Bottom will animate up from the bottom of the screen. Select Top or Bottom from the dropdown menu.

  • Border Radius: Governs the degree to which a banner or modal message's corners will be rounded. For banner messages, this applies to bottom corners for top-placed messages and top corners for bottom-placed messages. Enter an integer from 0 to 20.

  • Display fullscreen on small screen devices: Stretches a modal message's layout to fullscreen on small devices, e.g. mobile phones, maintaining the same button layout. Check the box to enable.


Set for the message Heading and Body.

  • Text Color: The text color of the message heading or body. Enter a hexadecimal value.

  • Size: Small, Medium, or Large. Select from the dropdown menu.

    Set the default values in the Font Size section of the Fonts tab.

  • Alignment: Align text left, middle, or right. Click to select.

  • Style: Bold, Italic, or Underline. Click to select.

  • Font Family: Serif or Sans-serif. If you have configured Custom Fonts, they will also be listed. Select from the dropdown menu.


Set for each button. Buttons are in order of the layout selected in the Content step of the In-App Automation Workflow.

  • Background Color: The button background color. Enter a hexadecimal value.

  • Text Color: The button text color. This should contrast with the Background Color. Enter a hexadecimal value.

  • Label Size: The button text font size. Select Small, Medium, or Large from the dropdown menu.

    Set the default values in the Font Size section of the Fonts tab.

  • Border Color: The button border color. This may contrast with the Background Color. Enter a hexadecimal value.

  • Border Radius: Governs the degree to which the four corners of the button are rounded. Enter an integer from 0 to 20.


Configure custom fonts and default font size values for header, body, and button label text.

Custom Fonts

Make your app's installed fonts available to select in In-App Automation Design.

Add individual font names to create a font stack. A font stack is a list of the font names that will be passed down from the app to the device. The font stack is used in order to provide alternatives in the event that your custom font is not available to your app. It also lets you unite font names from different platforms into a single selection, as your custom font name may differ between iOS and Android.


Custom font configuration will not install a custom font for you. A developer must still install the custom font within the app:

Edit or delete existing font stacks by clicking the pencil icon or X.

Create separate font stacks for serif and sans-serif fonts.

  1. Click the Add a custom font stack button.

  2. Enter a name for the font stack, enter a font name, then click the Add button. The name appears in the Font Family dropdown menu in In-App Automation Design. Make sure to use the correct Font Name Format
    Continue adding individual font names until your list is complete. Click the X next to any added font to remove it.

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

You can now select the custom font stack in In-App Automation Design.

Font Size

Set the default font size values for header, body, and button label text. Either manually enter a numeric value, or click a field and use the up/down arrows to adjust the existing value.

Font Name Format

You will need a developer to confirm the font names configured within the app. Font name format varies per platform:

  • iOS: Use the PostScript Name (or Fullname) of your font. This is not necessarily the filename of the font. The best way to verify the PostScript Name is to use the Font Book application on OSX.

  • Android: Use the same name that's in your app's fonts.xml. See the Fonts In XML guide. For example, if you define a font in res/fonts/my_cool_font.xml, the font name is my_cool_font.

Background Push


This section applies to in-app messages created via the In-App Automation workflow only.

Background push is used to pre-load in-app messages on a user's device, which increases the speed and reliability of message delivery. It disabled by default. When disabled, the SDK downloads and refreshes the entire message list upon next app open. For information about the potential impacts of background push, see: In-App Messages: Background Push.

Toggle to enable/disable.

iTunes ID

Some features depend on your app's Apple ID, which is used as the iTunes App Store Identifier. Enter the Apple ID, then click the Save button.


A quick way to find the Apple 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 Apple ID is 123456789.

Another way is to locate your app in iTunes Connect and copy the Apple ID.

App Screens

App Screens can be used as In-App Automation display triggers or conditions. Specify the screens when creating your message. See: Display Triggers: Screenview and Display Triggers: Conditions: Screenview.


The Screenview display trigger and condition and App Screens require enabling Screen Tracking within your app, which involves capturing Screen View events throughout your app in native code.

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

  1. Click the New App Screen button.

  2. Enter the Unique ID and a Description for the app screen.
    • Unique ID: Enter the name of the screen exactly as it was registered within your app.
    • Description: Enter extra information to help you identify this from the list of all app screens.
  3. Click the Submit button, or cancel to discard.

Event Properties

Event Properties are developer-defined properties associated with Custom Events. Once configured, you may use them to filter Event triggers and Cancellation Events in the Automation workflow. See: Event Triggers.

The table includes a maximum of 1,000 events. Narrow down your list by using the Search field. Results are updated dynamically.

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


Deleting an event property from this list means it will longer be available via the dashboard.

Deleting the event property from this list does not:

  1. Remove properties from your existing automation rules
  2. Remove the properties from the event itself.

  1. Click the Add Event Properties button.

  2. Type ahead to search custom events that occurred within the last 30 days, then click your selection from the listed results. If there are no results for your searched term, click the Use [search term] button to use the event name as typed. Then click the Next button.
  3. Optionally enter an event description, then enter a property and select its type from the dropdown menu.The selected type determines which operators are available to you in the dashboard. Choose Any, String, Number, Boolean, or Array. Select Any if the potential value for the property is unknown, or if more than one valid option exists.

    If you would like to add multiple properties to the event, click the Add Another button and continue with your specifications. Click the X at the end of any additional row to remove it.

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


You can add a maximum of 100 properties to an event.

Automation Limits

Automation Limits control over-notification to users who repeatedly meet Automation rule 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 Workflow: The last option in the Setup step of the Automation workflow.

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/disable.

  • 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 Ok, thanks. 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/disable. See Named Users 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 Target Specific Users and Tag Groups API Tutorial 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 below.

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.

Location Integrations

When sending an Automated message, you may choose to trigger sending the message based on location data. Location triggers require integration with either Gimbal or Radar.


See the Location Triggers guide for requirements, setup, and usage information for Gimbal.


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.


See the Location Triggers guide for requirements, setup, and usage information for Radar.

After the integration is configured, the Radar toggle controls seeing Radar location data in the dashboard. Toggle On or Off.

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.