Oracle Help Center | Oracle Responsys Mobile App Platform Cloud Service title

Geofences and Beacons

Responsys offers a location-based marketing feature that enables marketers to create marketing campaigns to target mobile app users in near real time based on their geographic location. This offering leverages Geofences and Beacons to send Mobile App Messages (Push / In-app / Message Center), SMS, and Email notifications to end users.

BEFORE YOU BEGIN:

Platform-specific topics: This topic provides information common to all platforms. To view information for the platform(s) you support for your mobile app, refer to the topics for each supported platform:

Solution Description

This solution works by declaring location-related rules for apps built with the Responsys Push SDK and a Geofence and Beacon Location Provider's SDK. Here's an overview of the Design Time phase and the Execution Time phase.

Design Phase

Implementing this feature requires the following steps performed by app developers and marketers:

  1. Decide and configure the Geofence and Beacon locations with your Marketing and App Team.
  2. (Optional) Define up to 5 custom key-value pairs. This enables marketers to send additional custom data into Programs and Campaigns. For example, marketers may want to store specific coupon codes based on the location of the Geofence. The Responsys Account Administrator must also define these custom event fields within Responsys. We will explain optional data use cases later in this topic.
  3. App developers add the location provider's SDK to their mobile app and completes the required configuration.
  4. App developers update their mobile app to the latest SDK (at minimum must be 19A/6.40).
  5. App developers develop the app layer/integration code to receive the Geofence Event and trigger the Responsys SDK’s Geofence Events APIs.
  6. Marketers design campaigns and program orchestration. Programs begin with a starting event of a Geofence or Beacon entry or exit.

Execution Phase

The execution phase follows this sequence of events:

  1. A marketer defines the locations to setup Geofences and Beacons.
  2. When an app user enters or exits the proximity of a Geofence or Beacon, an event is triggered.
  3. On the user's mobile device the Location Provider's SDK will raise an event. The mobile app raises the corresponding Responsys Geofence/Beacon event API.
  4. The Responsys SDK will then send the event to Responsys.
  5. Responsys will process the event.
  6. The event enters Responsys Program Orchestration.
  7. Marketers then send an email or SMS notification to the user as part of their campaign.

Here's a diagram illustratrating the execution phase.

Now that we've given you an overview of the design and execution phases, we will now explain the implementation steps in detail, so you can learn how to implement a Geofence/Beacon solution similar to this.

Implementation

Step 1 - Decide and Configure Geofences and Beacons

Marketers must plan the geographic locations best suited for Geofences and Beacons. Using retail as an example, a store location might be a good location for a Geofence. Marketers will log into their Location Provider's application to setup their Geofences and Beacons.

Here's an example configuring Geofences and Beacons using Bluedot. We are setting up a Geofence for one of our retail stores named Durham Denim, located in Redwood City. We are also adding custom fields such as CITY, COUPON_CODE, DISCOUNT, and STORE_NAME which will enable us to send more data into Responsys thereby giving us the ability to customize the message we send to our end users. This will be explained in greater detail in Step 2.

See your Location Provider's documentation for instructions on how to setup and configure your Geofences and Beacons.

Step 2 (Optional Step) - Defining custom key-value pairs

Custom key-value pairs enable marketers to send additional data from the Geofences and Beacons into Responsys Programs and Campaigns. This extends the capabilities of the out-of-the-box solution and tailors it to your needs.

As shown in the screenshot in Step 1, we have added the custom variables CITY, STORE_NAME, COUPON_CODE, and DISCOUNT.

Some reasons you might want to define custom key-value pairs include:

To setup custom key-value pairs:

  1. Define key-value pairs in the setup of your Geofences and Beacons with your location provider. Using Bluedot as an example, Value pairs are STRING data types, with a maximum length of 256 characters for both the Key and Value.
  2. In Responsys, the Responsys Account Administrator must define custom event fields in the Manage events UI under Tools > Manage events. These will represent the custom key-value pairs. All data types are supported. Screenshot of adding custom variables in the REI interface

Here we've added the following custom variables: CITY, COUPON_CODE, DISCOUNT, and STORE_NAME. These data types are Text, but all data types are supported. See Steps 6 to 6.3 to learn how to use these variables in Program and Campaigns.

Step 3 - Add the Location Provider SDK to Mobile apps

App developers must add their Location Provider's SDK to their mobile apps. See your Location Provider's SDK documentation for instructions.

Step 4 - Update Apps to the Latest SDK Version

App developers must update mobile apps to the latest Responsys Push SDK. At minimum, the SDK must be at least version 19A/6.40, but we always recommend using the latest SDK version. Refer to our SDK Support Policy to learn more about SDK support. You can download the latest SDK from Github.

Step 5 - Develop the App Layer Code

App developers must ensure when a Geofence or Beacon event occurs:

  1. App receives the Geofence Event raised by the Geofences Events SDK
  2. App raises a Geofence Event to Responsys by calling the Responsys SDK's Geofence Events API
  3. App passes all relevant parameters for the Geofence Event while calling the Responsys SDK's Geofence Events API. This includes any custom key-value pairs that the app wants to use in Responsys.
  4. Any custom key-value pairs are sent to Responsys.

There are currently 4 APIs:

App developers can learn how to call these APIs by referring to the platform specific topics:

Step 6 - Create Campaign and Program Orchestration

Marketers can then create Programs with Geofence or Beacon events as the starting node.

Example: To demonstrate how marketers can use this feature, we will walkthrough creating an example campaign with a personalized push message with the custom key-value pairs we created in Step 2. The campaign will send a push message to users with a coupon code that is personalized to the Geofence. Next, we will create a Program using a Geofence entry event as the starting node to then send a push notification (containing the campaign and coupon code we created earlier).

In Programs there are 4 events available to marketers:

Step 6.1 Creating a Campaign

For this example we will create a Push Campaign. For information on how to create and design a campaign, see the Oracle Responsys Help Center.

Step 6.2 Personalizing the Push Message
  1. From the campaign workbook, click Data Sources.
  2. Enter the event variables you want to use in the Alias column. There are two types of variables: standard variables (listed in the Responsys Help Center) and custom variables (explained in step 2 above). In this example we want to personalize the Campaign with the event variables:
    • The standard variable RSYS_GEN_FENCE_NAME.
    • The custom variable CITY.
    • The custom variable COUPON_CODE.
    • The custom variable DISCOUNT.
    • The custom variable STORE_NAME.
  3. Click Save.
  4. Click Create Message or Edit message.
  5. When designing your message, click Insert Personalization Token.
  6. Expand DynamicVariable and select the event variable you want to include. Continuing our example we'll start by selecting the COUPON_CODE variable.
  7. Click OK. Repeat these steps to personalize your push message.

Here's an example of our finished personalized push message.

The example below demonstrates how you can personalize the title, using the DISCOUNT and CITY variables.

Step 6.3 Creating a Program

In this program, we will only send the user a push message if they enter the Geofence for the Redwood City Durham Denim store. If this criteria is met, the user enters our program and will be sent our personalized push message (containing our coupon code). For our program, we will use a Geofence Entry event as the starting node, a Data Switch, and a Send Push Campaign event. For more information on how to create and design a program, see the Oracle Responsys Help Center.

Clicking Settings > Tracking and variables > Event Variables will display all Event Variables you can use in your program. This includes Standard Event Variables as well as the Custom Event Variables we defined in step 2.

Next, we'll configure our Data switch so that if Program variable conditions are matched, the program sends contacts to Option 1.

The Filter Designer will open, and we'll configure our Data switch so that if the RSYS_GEN_FENCE_NAME matches Redwood City, contacts will flow into Option 1 which will send users a push notification (the same campaign we created earlier with our store coupon code).

This is a basic example you can use as a starting point to understand how you can use Geofence and Beacon event variables in your programs.