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.

Location Triggers introduce 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 the Gimbal Platform. This document covers the integration, installation, and setup requirements needed to start using Location Triggers.

Account and SDK Setup

In order to get started using Location Triggers, make sure you have all the necessary account entitlements and software installed for both Urban Airship and Gimbal.

Urban Airship

Urban Airship SDK version 6.0 or later.

Location Triggers require Urban Airship SDK 6.0 or later. Download the latest stable SDK from appropriate Platform page.

Urban Airship Gimbal Adapters

The Urban Airship Gimbal Adapter is a drop-in class for iOS, Android, and Amazon that allows users to integrate Gimbal Place events with Urban Airship. See Urban Airship Gimbal Adapters below for details.

Urban Airship 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.

Gimbal

Gimbal Account

Register here.

Create a Gimbal SDK-enabled app

See the 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.

Urban Airship Gimbal Adapters

The Urban Airship Gimbal Adapters provide a convenient bridge between Gimbal’s Places definitions and Urban Airship’s automated messaging services. These adapters are designed to be dropped into an existing project and enable Gimbal location events to directly interface with Urban Airship.

iOS

The iOS Gimbal Adapter installation instructions are in the iOS Gimbal Adapter section of the UA Extensions GitHub repo.

Android

The Android Gimbal Adapter installation instructions are in the Android Gimbal Adapter section of the UA Extensions GitHub repo.

Gimbal Setup

Gimbal is the system of record for 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 app from the Urban Airship dashboard, then navigate to Settings » APIs and Integrations, and click the Gimbal tab.
  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 on the Gimbal tab in Settings » APIs and Integrations. You can also manually sync your locations at any time by clicking the Sync Now button.

Use Location Triggers

Once your locations are defined on the Gimbal side and synced with your Urban Airship account, you’re ready to create Automated messages using location triggers.

  1. Choose your app from the Urban Airship dashboard, then click the Create New button, and select the Automation composer.
  2. Enter a descriptive Automation Name, then select the Location trigger.
  3. Use the dropdown menu to choose whether to trigger when the user enters or exits a location, then click the Select a location button.
  4. 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.
  5. Check the box next to the location(s) you want to use as the message trigger.
  6. 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.

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

See the full Automation Composer documentation to complete the remaining composer steps.

Terminology

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.

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.

FAQ

Q: What’s the difference between Urban Airship’s location service and Location Triggers?A: 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. Location Triggers make use of real-time exit/entry data for geofences and proximity (beacon) devices. This data can then be used as triggering information in Automated messages.