map-o file-code-o arrow-directionplatform-webreach-project-type-boarding-passreach-project-type-couponreach-project-type-event-ticketreach-project-type-genericreach-project-type-gift-cardreach-project-type-loyalty-cardreach-project-type-member-card pictures more_vert chain keyboard_arrow_down keyboard_arrow_right

In This Section

Location Triggers

Location Triggers are an out-of-the-box way for you to send real-time Automated messages to your audience as they enter or exit a specific geographical location.

This document describes the location triggers and how to use them, as well as partner integration requirements and setup.

Key Terms

Automation
Automation is a set of conditions that must be met before the message is either sent or displayed.
Workflow
A workflow is a method of creating messages via the dashboard.
Location
A location is a logical place defined by a set of beacons and/or geofences. Locations are the logical entities that are signalled by devices and may be used to trigger Automated messages.
Attributes
Attributes are key/value pair metadata associated with a particular location, e.g., chain:BobsBurgers, has_blender:yes. Attributes must be defined and assigned to a particular location in the Gimbal system and synced with an Urban Airship account.
Beacon
A beacon represents a physical device used for proximity detection. Beacons may represent hardware implementing the iBeacon standard for use with iOS, or proprietary beacons (such as Gimbal beacons) for use with Android. Beacons may or may not have geolocation data associated with them.

Geofence
A geofence represents a fixed location representable by one or more points in the WGS coordinate system. Geofences can consist of a single point and a radius expressed in meters, defining a circular region, or a series of points defining a polygon.

Place
The Gimbal system refers to your app’s locations as Places. A Place is either a single geofence, one or more beacons, or one or more beacons and a geofence.

About

Location triggers are a more dynamic application of location-based notifications, moving beyond historical location and segmentation to real-time triggers based on users’ movements in and out of geofences and proximity to beacon signals.

Urban Airship location triggers rely on coordination between two technologies: Urban Airship Automation and integration with one of our location data partners.

Audience Segments

In addition to real-time automation triggers, Urban Airship’s location service records location events and stores them for later use when constructing segments for audience targeting. See Geographic Location Criteria for more information.

Triggers

In the Setup step of the Automation Workflow, you must choose which event type will trigger sending your message. There are three event triggers that use location data:

Location
The message is sent when a device enters or exits a specific geographical location.
Location Attributes
The message is sent when a device enters or exits a geographical location associated with predefined attributes.
Event
The message is sent when a specified Radar-based custom event occurs.

Location Data

Location data is provided via integration with Gimbal and/or Radar.

Gimbal

Gimbal sends their location data to Urban Airship via our Gimbal Adapters. An Urban Airship Gimbal Adapter is a drop-in class for iOS, Android, and Amazon that integrates Gimbal Places events with Urban Airship. The Gimbal data can then be used with the Location and Location Attributes triggers in the Automation workflow. See: Use Location Triggers below.

Radar

Radar sends location data to Urban Airship using our server-side Custom Events API. Whenever location events are generated, Radar will send custom events and properties to Urban Airship. This data can then be used with the Event trigger in the Automation workflow. See: Use Location Triggers below.

Set Up Gimbal Integration

Requirements

Urban Airship

  1. SDK version 6.0 or later: Download the latest stable SDK from appropriate Platform page.

  2. Account Entitlement: Account-level permissions apply, based on your pricing package. Contact your Urban Airship Account Manager with any questions related to pricing and entitlements for location and automation services.

Gimbal

  1. Gimbal Account: Register on gimbal.com.

  2. Gimbal SDK-enabled app: See Gimbal’s iOS and Android Developer Guides.

    • Minimum iOS requirement: v2.8.1 as of Feb 25, 2015.
    • Minimum Android requirement: v2.8.1 as of Feb 25, 2015.

Contact your Gimbal Account Manager with any questions.

Add Gimbal Adapters

Follow the installation instructions:

Configure Integration

Gimbal is the system of record for their location data, and all updates to places data are managed by Gimbal. In these steps you will enter your Gimbal Server API Key into your Urban Airship settings, then import your locations.

  1. Go to manager.gimbal.com/organizations.

  2. Copy the Server API Key for the Organization you want to use with Urban Airship.

  3. Choose your project from the Engage dashboard, then navigate to Settings » APIs & Integrations, and select Location Integrations from the menu.
  4. Paste your Gimbal Server API Key in the provided field, then click the Save button.

  5. Click the Sync Now button. This imports your Gimbal Places as Urban Airship locations so they can be used as location triggers.

    After the initial import is complete, your locations will automatically sync every 24 hours. The date, time, and time zone of the latest import is listed in the Gimbal section in Settings » APIs & Integrations » Location Integrations. You can also manually sync your locations at any time by clicking the Sync Now button.

Set Up Radar Integration

Requirements

Urban Airship

  1. SDK version 6.0 or later: Download the latest stable SDK from appropriate Platform page.

  2. Account Entitlements: Account-level permissions apply, based on your pricing package. Contact your Urban Airship Account Manager with any questions related to pricing and entitlements for location and automation services.

Radar

  1. Radar account: Register on radar.io.

  2. Account Entitlements: Per Radar’s integration documentaion, this is a premium integration, available only to Enterprise customers.

  3. Radar SDK-enabled app: See Radar’s SDK documentation.

Configure Integration

In these steps you will create an Urban Airship Custom Event Token, add the token and your Urban Airship app key to your Radar account, then enable the Radar integration in your Urban Airship project.

  1. Choose your project from the Engage dashboard, then navigate to Settings » APIs & Integrations, and select Custom Event Tokens from the menu.

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


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


  5. On the Radar Integrations page, under Urban Airship, set Enabled to Yes, and paste your Urban Airship app key and access token. Note that you can set separate API keys for the Test and Live environments.

  6. In the Engage dashboard again, navigate to Settings » APIs & Integrations » Location Integrations, and toggle the Radar integration to On.

Now Radar will send custom events and properties to Urban Airship for use with the Event trigger.

Use Location Triggers

  1. Choose your project from the Engage dashboard, then click the Create button, and select the Automation workflow.
  2. Enter a descriptive Automation Name, then select the Location, Location Attributes, or Event trigger.

Follow the steps below for each trigger type.

Location

You can select a maximum of 20 locations per automated message.

  1. Click the Select a Location button.
  2. Enter a search term in the box. Results, if any, display on the map and are listed in the Results tab.
    There are two types of locations available for selection: geofences and beacons. Click on a result for a detailed view of a location. If selecting a geofence, the map to the right will zoom to the selected location. Click and drag, and use the +/- zoom controls to change the displayed area.

  3. Check the box next to the location(s) you want to use as the message trigger.

  4. Review the locations on the Selections tab, click the X next to any location you’d like to remove, then click the Save & Continue button, or Cancel to discard.
    Your selected location(s) will be listed in the trigger selection pane. Click the X to remove a selection.
  5. Use the dropdown menu to choose whether to trigger when the user enters or exits a selected location.

See the full Automation workflow documentation to complete the remaining steps.

Location Attributes

You can add a maximum of 50 attributes per automated message.

  1. Enter a key/value pair for the location you want to use as the message trigger. If you would like to set multiple attributes, click the Add Another button and continue with your specifications. Click the X at the end of any additional row to remove it.

  2. Optionally add an alternative key/value pair by clicking the plus sign icon at the end of a row.
  3. Use the ALL/ANY dropdown menu to choose what criteria must be met.

    ALL = all criteria must be met (Boolean AND)
    ANY = any criteria must be met (Boolean OR)

    If set to ALL, attributes with alternatives use a Boolean OR operator. If set to ANY, attributes with alternatives use a Boolean AND operator.

    By default, the notification will be triggered if the location attributes meet ALL the attributes you entered.

    For example, if you selected ALL, with attributes half_off and has_cafe, you’d only reach users who entered or exited a location that met both of those conditions. If you selected ANY, you’d reach all users who entered a location running a half-off campaign as well as all users who entered a location that has a cafe.


  4. Use the dropdown menu to choose whether to trigger when the user enters or exits a location.

See the full Automation workflow documentation to complete the remaining steps.

Event

These steps are a version of the Custom Event trigger documentation, with the options and settings relevant to the Radar integration.

See Radar Events and Properties below for available trigger and filter terms.

Type ahead to search custom events, then click to select from the listed results. All Radar events have the prefix radar in the name, e.g., radar_geofence_entered.


If you would like to set multiple Event triggers, click the Add another button and continue with your specifications. Multiple events are handled as a Boolean OR.

Filter

Optionally trigger only when a specified property of a location is met. Each Radar location event has associated properties that may be used as filters. For example, you can choose to trigger an automated message when a user enters a Radar geofence (radar_geofence_entered) with a confidence property (radar_confidence) value of Medium.

  1. Click the ADD PROPERTIES/VALUES button.

  2. Click the Add Property button.
  3. Click Search for Properties to see a list of available related properties, click to select, then complete the filter. An operator will pre-populate for most properties. If not, make your selection from the dropdown menu.
    Equals (string): Enter the appropriate identifier as shown in your Radar dashboard.

    Equals: Select Low, Medium, or High. This is used for radar_confidence only.

    Enter a numeric value for:
    Greater than
    Greater than or equal to
    Equals (number)
    Less than or equal to
    Less than

  4. Optionally add an alternative by clicking the plus sign icon at the end of a row.
  5. Use the ALL/ANY dropdown menu to choose what criteria must be met.
    ALL = all criteria must be met (Boolean AND)
    ANY = any criteria must be met (Boolean OR)

    If set to ALL, filters with alternatives use a Boolean OR operator. If set to ANY, filters with alternatives use a Boolean AND operator.

    If you would like to set multiple filters, click the Add Property or Add Event Value button again and continue with your specifications. Click the X at the end of any additional row to remove it.

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


See the full Automation workflow documentation to complete the remaining steps.

Radar Events and Properties

Use the following terms when searching for and filtering Radar events. See Radar’s documentation for additional detail.

Each event is followed by its associated properties and each property’s acceptable value.

Geofences

radar_geofence_entered
radar_geofence_description: String
radar_geofence_tag: String
radar_geofence_external_id: String
radar_confidence: Low, Medium, or High
radar_geofence_exited
radar_geofence_description: String
radar_geofence_tag: String
radar_geofence_external_id: String
radar_confidence: Low, Medium, or High
radar_duration: A number, in minutes

Insights

radar_home_entered
radar_confidence: Low, Medium, or High
radar_home_exited
radar_confidence: Low, Medium, or High
radar_office_entered
radar_confidence: Low, Medium, or High
radar_office_exited
radar_confidence: Low, Medium, or High
radar_traveling_started
radar_confidence: Low, Medium, or High
radar_traveling_stopped
radar_confidence: Low, Medium, or High

Places

radar_place_entered
radar_place_name: String
radar_place_chain_slug: String
radar_place_chain_name: String
radar_place_categories: String
radar_place_facebook_id: String
radar_confidence: Low, Medium, or High
radar_place_exited
radar_place_name: String
radar_place_chain_slug: String
radar_place_chain_name: String
radar_place_categories: String
radar_place_facebook_id: String
radar_confidence: Low, Medium, or High
radar_duration number: A number, in minutes

Never miss out on product updates

Click "Allow" in the browser prompt in the upper left hand corner of your browser.

Next, we'll allow you to choose what sort of notifications you'd like to receive.

Choose your notification topics

Product Subscription Options

    Platform Subscription Options