Create Contextual Interaction Rules

Create a new rule

Overview

ubudu SDK is able to execute all the Contextual Interaction Rules you define in ubudu Manager without the need to customize your application, or to download a new version of it.

A Contextual Interaction Rule consists of (1) Context and (2) Action(s). The Actions will trigger when and only when the Context is met.

Rules are :

  • Defined on ubudu Manager,
  • Then downloaded programmatically on the ubudu SDK,
  • Where they are evaluated and executed, whenever the smart device enters a beacon region.
  • Interaction logs are stored locally and uploaded programmatically onto the ubudu Manager.

Flow of execution

Note that the flow of execution is slightly different whether your app is in foreground or background.

SDK_execution_flow_scheme.png

As you can see, if you specify a server notification, then your server is going to be able to decide if the other actions associated to the rule should be executed or not. Based on the knowledge you have on your server, it may even decide to execute completely different actions.

The other important point to notice is that if the application is not in foreground when the rule triggers, then only the local notification is presented to the user. The other actions will be executed when the user clicks on the notification.

  • Login to ubudu Manager
  • Go to "**Beacon Interaction Rules**" section
  • Choose "**New beacon interaction**" on the page

Define rule identity

  • Name: choose a name for this rule , e.g. "Chocolate Special Offer in Scotland stores"
  • Application: choose out of the list the app you want to rule to work on, e.g. "Acme Loyalty App"
  • Group: choose if needed a Rule with which to share the Motion Behavior Counters. E.g. "don't push the Chocolate Special Offer in any store, if it has already been done once."

Define rule criteria

Criteria are multi-dimensional : space, time, person, behavior. And other real-time data could be added through integration, contact us if need be.

Proximity criteria

  • Monitoring method : Beacon if you want a rule targeting a specific location, or Region if you want a rule targeting a wider area.
    • A region is defined by its beacons' Proximity UUID, so when you are e.g. in a mall where all beacons share the same PUUID, you will be in the region while you see at least 1 beacon.
  • Beacon : select the beacon you want to target for this rule.
    • We recommend that you use the drop-down list instead of manually inputing a beacon PUUID/Major/Minor. If you havent yet, you need to add your beacons to the ubudu Manager through the Devices menu item.
  • Geofencing : this is not an option on this screen, but you can also create rules targeting GPS geofences, through the *Geofences" menu item.

User segment criteria

This powerful feature allows you to target specific users, i.e. to personalize your interactions on top of using context.

  • Dynamic tags: they are assigned at app level.
    • See Advanced App Customization article for details on how to code dynamic tags in your app.
  • Logical operators: you can create logical expression to be evaluated using a combination of dynamic tags, using operators such as "AND", "OR", and "( ...)". Examples:
    • "female" and "under_25".
    • ("female" and "under_25") or "under_20"

Time criteria

  • Validity schedule: define the start and end dates of rule validity
  • Active hours: define the days & hours of the week when the rule should be active.
    • A wizard provide some default settings
    • Caution : more than once, we've seen developer scratch their head while trying to understand why rules

Motion behavior criteria

  • Enter/Exit: choose whether the action should trigger when entering or exiting the area
  • Radius: define the dimension of the area (valid in beacon proximity mode, not region mode). We introduced two things to make dimension more accurate :
    • new ranges called Medium-Far and High-Far (configurable at Application level), as we found that iBeacon's Near and Far werent enough in many scenarios
    • the concept of Proximity Start-*Proximity End* to enable to include full perimeters within a given radius (as the default iBeacon's Near area excludes the very close positions).
    • Proximity Start : Immediate, Near, Medium-Far, Far or High-Far
    • Proximity End : Immediate, Near, Medium-Far, Far or High-Far ... Should always be higher than Proximity Start
  • Counters: we provide a number of counters to add more context to your interactions, and to also limit a user's exposure.
    • Min events: the minimum number of times a user has to enter/exit the area, before the action triggers. E.g. only push the Chocolate Special Offer to customers who visited the Sweets area of the store 3 times.
    • Min events period: allows to reset the Min events counter. E.g. only push the Chocolate Special Offer to customers who visited the Sweets area of the store 3 times in the past week.
    • Max events: the maximum number of times an action can be triggered when a user enters/exits the area. E.g. don't push the Chocolate Special Offer more than once to any user.
    • Max events period: allows to reset the Max events counter. E.g. don't push the Chocolate Special Offer more than once PER WEEK to any user.
    • Group Counters: allows to use the above min/max counters across a group of Rules.
    • Latch time: a time counter until the action triggers, while a user remains inside/outside the area. E.g. push the Chocolate Special Offer only to customers who spend 2 minutes in the Sweets area of the store.

Define rule action(s)

Server notification

When a rule triggers if you have specified a URL to be called (a server notification) then the SDK will start the execution procedure by making an HTTP request at this address. Depending on the response it receives, it will decide to continue the execution of all the actions of the rule (local notif, web page...) or to ignore the other actions and execute the ones returned by your server.
rules_action_server_notification.png

The JSON returned by your web service must be of the following form:

{
    "decision":"notify",
    "open_pbk":"https://example.com/passbook/pass_coupon_2014-02-20.pkpass",
    "open_url":"https://example.com/foo.html",
    "notify_user":"{\"alertBody\":\"Your message\",\"payload\": {\"foo_key\":\"bar_value\"} }",
}

The decision value can be:

  • "enable": Continue normal execution
  • "disable": Stop execution
  • "notify": Use actions returned in the response

Placeholders

The SDK can replace a set of predefined placeholders in the URL which allows you to enrich your URL with information about the context of execution of the rule.
The syntax to use is {placeholderName} which will be replaced by the corresponding value.
Example: https://example.com/your_webservice.json?event=enter&namespace={namespace}&ext_id={ext_id}

Available placeholders (for beacon, geofence, or both):

  • id (all) : the ubudu ID of the region (geofence or beacon).
  • namespace (all) : the namespace of the ubudu Application.
  • udid (all) : the unique identifier of the user, assigned by the ubudu SDK.
  • ext_id (all) : the user ID you specified in [UbuduSKD sharedInstance].user.userID. Empty if not specified.
  • proximityUUID (beacon) : the proximity UUID of the beacon that triggers the rule.
  • major (beacon) : the major of the beacon that triggers the rule.
  • minor (beacon) : the minor of the beacon that triggers the rule.
  • proximity (beacon) : the proximity of the rule that triggers, value can be 1 (immediate), 2 (near), 3 (far) or 0 (unknown).
  • lat (geofence) : the current latitude of the device.
  • lng (geofence) : the current longitude of the device.

The type key is also added to your URL with either the value geofence or beacon.

The example URL that is called on your server would look like : https://example.com/your_webservice.json?event=enter&namespace=634b207ee2f313c109c58675b44324ac2d41e61e&ext_id=your_id&type=beacon

Local notification

SDK posts a notification using the native system API. The message is the one you defined in the alertBody field in the back-office. You also can specify a custom payload with any information that you find useful (in JSON format) but you will need to handle the local notification action yourself in order to use the data. See the links at the bottom of this article for more information about this.

rules_action_local_notification.png

Placeholders

You can use placeholders in the form of {placeholder} in the notification message. The SDK will replace these placeholders by the corresponding value in the user properties you may have specified.
If the user property is not present, then the placeholder is not replaced.

Example: "*Hello {username}, check out the new collection in your store.*"
would become
"*Hello Jane Doe, check out the new collection in your store.*"

See "Advanced App Customization" article to learn how to set the user properties.

You can open any app on the smart device using an URL scheme.

Example : 'twitter://post?message=hello%20world&in_reply_to_status_id=1234...;. The object as a JSON representation to enable to handle different URL schemes depending on the device OS.

JSON schema:

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "genericURL": {
      "type": "string",
      "description": "IOS & Android. URL of the mobile deep link"
    },
    "iosURL": {
      "type": "string",
      "description": "IOS only. URL to be used on IOS. Ovewrite genericURL"
    },
    "androidURL": {
      "type": "string",
      "description": "Android only. URL to be used on Android. Ovewrite genericURL"
    }
  }
}

Open Web page

When you define an open web page action, the SDK will present the web page into a web view modally displayed within your app.

The page can be either online (use the http:// or https:// protocol) or in the application bundle (in this case use the file:// protocol in the URL).

rules_action_web_page.png

Open Passbook / Samsung Wallet

When you define an open Passbook action, the SDK will present the pass to the user that will be able to add it to its wallet.

The pass can be either online (use the http:// or https:// protocol) or in the application bundle (in this case use the file:// protocol in the URL).

rules_action_passbook.png

Add more actions for the same criteria

  • Click on the "Plus" button to add an extra action for the same set of criteria.