Urban Airship

Integrations:

Integration 1 - Location Based Push

Integration 2 - Segments based on Location History

To use Plot Projects and Urban Airship together, we present in this section two possible integrations: the first one is used for sending real-time location-based push messages, while the second one is used to create audiences based on the location history of devices.

Integration 1: Location Based Push

Using Plot Projects and Urban Airship together allows you to add a location-intelligence layer to your marketing campaigns by targeting your users based on the places they visit. You can, for example, automatically send push notifications to users when they approach or enter a Walmart.

You create and save your automatic messages in the Urban Airship dashboard as described in the following sections.

Set up a Listening Campaign in the Plot Projects dashboard

Plot Projects offers a Geo SDK that easily connects to the Urban Airship SDK (see paragraphs below). Once this is done you can create Listening Campaigns in the Plot Projects dashboard that track when a user visits a location.

The first step is to create the locations you want to track. This can be a single location like a Walmart store:

Single location

Or a large set of locations:

Multiple locations

Once your locations are set up, you can create a Plot Projects Listening Campaign defining the event to be tracked after visiting the designated location(s).

When creating the campaign, set the field ‘Listening campaign Data’ with the event name.

user_enters_walmart

Urban Airship Dashboard

That’s it, you’ve finished setting up the location campaigns! Users can now be automatically targeted with push notifications.

Plot Projects Listening Campaigns have many options, including:

  • Trigger on geofences, polygons and/or beacons.
  • Trigger on geofence enter, exit or dwell.
  • Define opening hours per location.
  • Define start and end dates of the campaign.
Integrating into your app

Now that your Listening Campaign is set up, your app can be location-aware and track the visit events in Urban Airship. This integration guide is designed for Android, but also works for other supported platforms of the Plot SDK. You can find iOS documentation here After completing the integration guide, if a user enters a Walmart store, Plot triggers an Urban Airship event that results in the Urban Airship dashboard as below:

Urban Airship events

As a result, you can use the events created to send real-time messages to users when they approach this location. Do this by creating an automated message in the Urban Airship dashboard, as shown below, and setting the event as the message's trigger:

Urban Airship messages

Start with the Plot Projects integration guide and the Urban Airship integration guide. After integrating both libraries, you can track geotrigger events from Plot Projects in Urban Airship.

To receive geotrigger events from Plot Projects, create a class that extends GeotriggerHandlerBroadcastReceiver. To track the geotrigger event you call the Urban Airship API from that class.

public class MyGeotriggerHandlerBroadcastReceiver extends GeotriggerHandlerBroadcastReceiver {
    private static final String LOG_TAG = "MyGeotriggerHandler";
    @Override
    public List<Geotrigger> handleGeotriggers(List<Geotrigger> list) {
        for (Geotrigger geotrigger: list)
            try {
                String key = geotrigger.getData();

                CustomEvent.Builder builder = new CustomEvent.Builder(key);

                builder.create().track();

                Log.d(LOG_TAG, "sent event: " + key);

            } catch (Exception e) {
                // handle exception
            }
        return list;
    }
}

The MyGeotriggerHandlerBroadcastReceiver, presented above, records an event for Urban Airship using the data field set in the Plot Projects dashboard as event name. It also adds a tag with the event name.

To let Android find the receiver, add it to AndroidManifest.xml

<receiver
    android:name=".MyGeotriggerHandlerBroadcastReceiver"
    android:permission="false">
    <intent-filter>
        <action android:name="${applicationId}.plot.HandleGeotriggers" />
    </intent-filter>
</receiver>

What's next

Users are now targeted to receive a push message that was set based on the tracked event, in the Urban Airship dashboard. You can now create location-based marketing campaigns for these users.

Integration 2: Segments based on Location History

Using Plot Projects and Urban Airship together allows you to add a location-intelligence layer to your marketing campaigns by segmenting your users based on the places they visit. You can, for example, create an audience of users who visited a Walmart.

You create and save your audiences in the Urban Airship dashboard as described in the following sections.

Set up a Listening Campaign in the Plot Projects dashboard

Plot Projects offers a Geo SDK that easily connects to the Urban Airship SDK (see paragraphs below). Once this is done you can create Listening Campaigns in the Plot Projects dashboard that track users' location history.

The first step is to create the locations you want to track. This can be a single location like a Walmart store:

Single Location

Or a large set of locations:

Multiple Locations

Once your locations are set up, you can create a Plot Projects Listening Campaign defining the event to be tracked in the SDK and which will define the audience you’d like users to be added after visiting the designated location(s).

When creating the campaign, set the field ‘Listening campaign Data’ with the tag value

visited_walmart

Listening Campaign

That’s it, you’ve finished setting up the location campaigns! Users can now be automatically added to the corresponding audience in your Urban Airship dashboard.

Plot Projects Listening Campaigns have many options, including:

  • Trigger on geofences, polygons and/or beacons.
  • Trigger geofence on enter, exit or dwell.
  • Define opening hours per location.
  • Define start and end dates of the campaign.
Integrating into your app

Now that your Listening Campaign is set up, your app can be location-aware and use the events created in the Plot Projects dashboard to tag users as members of an audience in Urban Airship. This integration guide is designed for iOS and Android, but also works for other supported platforms of the Plot SDK. After completing the integration guide, if a user enters a Walmart store, Plot adds an Urban Airship tag to the user that results in the Urban Airship dashboard.

After setting a tag for the users that visited a location, you create and save an audience based on this tag, in the Urban Airship dashboard:

Create Segment

Start with the Plot Projects integration guide and the Urban Airship integration guide. After integrating both libraries, you can add tags based on geotrigger events from Plot Projects using the Urban Airship API.

To receive geotrigger events from Plot Projects, create a class that extends GeotriggerHandlerBroadcastReceiver. To add the corresponding tag, you call the Urban Airship API from that class.

public class MyGeotriggerHandlerBroadcastReceiver extends GeotriggerHandlerBroadcastReceiver {
    private static final String LOG_TAG = "MyGeotriggerHandler";
    @Override
    public List<Geotrigger> handleGeotriggers(List<Geotrigger> list) {
        for (Geotrigger geotrigger: list)
            try {
                String key = geotrigger.getData();

                UAirship.shared().getPushManager().editTags().addTag(key).apply();

            } catch (Exception e) {
                // handle exception
            }
        return list;
    }
}

The MyGeotriggerHandlerBroadcastReceiver, presented above, sets a tag in Urban Airship using the data field set in the Plot Projects dashboard as a tag name.

To let Android find the receiver, add it to AndroidManifest.xml

<receiver
    android:name=".MyGeotriggerHandlerBroadcastReceiver"
    android:permission="false">
    <intent-filter>
        <action android:name="${applicationId}.plot.HandleGeotriggers" />
    </intent-filter>
</receiver>

What's next

Users are now added automatically to the corresponding audiences in the Urban Airship dashboard. You can now create location-based marketing campaigns for these audiences. For instance, sending a push message to users who have visited a Walmart store at some point in the past.

Combined Integration

Apart from the aforementioned integrations used separately, it is also possible to combine them. This allows you to send both real-time Location Based Push Notifications and push messages to an Urban Airship Audience created based on Location History Events. For instance, send a specific Push Notification to users that enter a Walmart and that have visited a Walgreens in the last 7 days.