Engage Settings Menu Guide

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

Open your project from the dashboard, then click Settings 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. Click Update Project after making any changes. Delete your project by clicking Delete Project in the lower left corner.

  • Project name: Enter a descriptive name for your project.

  • Industry: Select an industry category. This is used for reporting.

  • Icon: Optionally upload your icon. This does not have to be the same icon you submit to app marketplaces, but that is the typical practice.

Team Access

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

Platforms

Add, manage, and remove the third-party messaging services you have configured for your project. If your account has been enabled for Apple News Push Notifications or Web Notify, configure them here.

Platforms that have not yet been configured appear greyed-out and have a Configure button. The button is labeled Edit if already configured.

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

Click Save after making your changes to a platform configuration.

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

  • iOS: If you have APNS configured for iOS, its expiration date is displayed, and you have the option to upload a new certificate.

  • Web Notify: Add Web Notify to your project, or edit an existing configuration. See: Configure Web Notify.

  • Apple News: Add Apple News to your project, or edit an existing configuration. See: Configure Apple News.

Open Channels

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

Add open channels to your project, or edit an existing configuration. See: Configure Open Channels.

Quickstart Guide

The Quickstart Guide walks you through the technical steps you need to perform in order to send your first push notification. Click the button for each configured platform, and the page will refresh with the relevant information.

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

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

Composer

Control features available in the dashboard workflows. Each feature is listed with a description and its minimum mobile SDK version. Toggle to enable/disable.

  • 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.

Note

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

Note

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

Note

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.

Create a new deep link:

  1. Click New Deep Link.

  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: { }. 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. Optionally check the box to allow a non-standard URL pattern.

  4. Click Save, or cancel to discard.
Warning

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.

Note

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

Note

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.

Create a new notification category:

  1. Click New Notification Category.

  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 Save, or cancel to discard.

In-App Message Design

Note

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 Save.

  • 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

Note

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

Default Design

Select a message style from the dropdown menu, then configure. Colors are entered as hexadecimal values. The default value for all color fields is white (#FFFFFF).

Background

  • 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, modal, or custom HTML 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 modal and custom HTML message layouts to fullscreen on small devices, e.g. mobile phones, maintaining the same button layout. Use this setting if you want your message to take over the entire screen on a phone but display as a modal on a tablet. The default display of custom HTML messages is modal. Check the box to enable.

Text

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.
    Tip

    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.

Buttons

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.
    Tip

    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.

Fonts

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.

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.

Note

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 Add a custom font stack.

  2. Enter a name for the font stack, enter a font name, then click Add. The name appears in the Font Family dropdown menu in In-App Automation. 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 Save, or cancel to discard.

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

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.

Advanced Options

Background Push

Note

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.

Missed Behavior

Specify how the message is handled when audience conditions are not fully met. Toggle to enable, then select from the dropdown menu.

  • Cancel: The message cannot be displayed again on the device, even if the message is edited.

  • Ignore: The message will not count toward the display limit set in Repeat this message, and the waiting period will not apply. The trigger event must occur again before the message is eligible for redisplay.

  • Penalize: The message will count toward the display limit set in Repeat this message, and the waiting period will apply. The trigger event must occur again before the message is eligible for redisplay.

Note

You can override this setting on a per message basis in the Settings step of the In-App Automation workflow.

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 Save.

Tip

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.

Note

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 New App Screen.

  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 Submit, 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.

Note

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.

Add new event properties:

  1. Click Add Event Properties.

  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 Use [search term] to use the event name as typed. Then click Next.

  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 Add Another and continue with your specifications. Click the X at the end of any additional row to remove it.

  4. Click Save, or Cancel to discard.

Note

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.

Add a limit:

  1. Click Add Limit.

  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 Add Limit and continue with your specifications. Two limits are the maximum.

  3. Click Save.

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

Note

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.


Predictive

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.
Note

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 Save. 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 » Open Channels.

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.

Note

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.

Connect Integrations

Connect is an add-on product. For existing integrations, see: Manage Connections.

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 Create Token.

  2. Enter a token name, then click Create Token.

  3. Copy the values, then click Ok, thanks. to close the window.
    Warning

    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 Revoke next to any token.

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

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.

Note

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 Create and push to a tag group 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

Warning

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 Create Tag Group.

  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 Save, or Cancel to discard.
Note

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

Note

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 Save, 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.

Gimbal

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

Note

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 Sync Now.

  • 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, then click Yes, remove or Nevermind to cancel.

Radar

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 configured in Settings » Platforms, not including Apple News.

Note

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 Send it!. Fields per platform are listed below.

iOS

  • 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.

Android

  • 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.