# Manage your rules (mobile proximity tracking)

Proximity enables you to trigger the right message or service to the right customer at the right time and location.

There is a wide range of possibilities : providing premium services, sending content or promotions, etc.

It can be set in different modes : push, pull, delayed or invisible.

# Rules

Ubudu SDK is able to execute all the proximity (or contextual interaction) rules you define in our Manager without the need for customizing your application, or downloading a new version of it.

A proximity Rule consists of

• context
• actions

The Actions will trigger when and only when the Context is met.

Rules are :

• Defined on the Manager,
• Then downloaded programmatically by our Proximity SDK (iOS or Android available on Github)
• Where they are evaluated and executed, whenever the smart device enters a beacon region.
• Interaction logs are stored locally and uploaded programmatically onto the Manager.

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 the 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 Manager and go to "Beacon Interaction Rules" section

Then choose "New beacon interaction".

## 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 haven't done so yet, you will need to add your beacons to the 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 provides some default settings
• Caution : more than once, we've seen developers scratch their heads while trying to understand why rules wouldn’t trigger. Often, they were just testing outside the active hours for the rule.

### 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 _were not 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)

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.

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",
}


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=634b207ee2f313c109c58675b44324ac2d41e61e&ext_id=your_id&type=beacon

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

![](/assets/"ré"réimport.png)

Placeholders

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

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 a 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",
"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).

### 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).