Integrate a third party analytics tool

The Ubudu SDK generates and logs a lot of events related to the beacons that are seen, geofences crossed, rules and actions executed, etc. All these data can be analysed in order to get insights and understand better the behaviour of your application users, and how well your context aware application behaves.

By default these events are sent asynchronously to the Ubudu platform. If no internet connection is available at the time the event occurs then the record is stored in a local database and sent later, when a working connection is available again.

Read Using data collected by the platform to analyse conversion funnel in proximity to Beacons to get a quick overview of the available events.

The Ubudu manager performs a few analyses of these logs and generates some basic graphs but can be quite limited for deeper analyses and complex needs.

Third party tool integration

If you want to take advantage of an existing logs/events analysis tool it is possible to plug the Ubudu events into this third party tool.

iOS

The iOS Ubudu SDK provides, since its version 1.14, a method in the UbuduSDKDelegate that is invoked each time a new event is generated. Just implement it and map the received events (see format of the event data below) to a format suitable for your tool, then forward the data to it.

- (void)ubudu:(UbuduSDK *)ubuduSDK didLogEvent:(NSDictionary *)event atTime:(NSDate *)eventDate;

Android

An equivalent feature for the Android SDK should be available in a following update.

Detail of the events

The event object is a key-value dictionary and contains the data of the event, the eventDate is the date and time at which the event was generated.

Example of event structure:

{ "type" : "trigger",
  "area_type" : "beacon",
  "trigger" : "on_entry",
  "beacon_id" : 598,
  "rule_id" : 7815 }

The first field to check is under the "type" key. It indicates what the received event is, and so which additional data can be expected.

The values possible for the "type" key are:

  • "region"
  • "view"
  • "trigger"
  • "action"
  • "open_notif"

The following sections describe in details the available data for each type of event.

Region event

{ "type" : "region",
  "area_type" : "beacon",
  "trigger" : "on_entry",
  "proximity_uuid" : "F2A74FC4-7625-44DB-9B08-CB7E130B2029" }
  • area_type: in iOS SDK v1.14 always "beacon" (geofences do not generate region events).
  • trigger: Depending if the device entered or exited the beacon region:
    • "on_entry"
    • "on_exit"
  • proximity_uuid: the UUID of the monitored beacon region.

View event

{ "type" : "view",
  "area_type" : "beacon",
  "trigger" : "on_entry",
  "proximity_uuid" : "F2A74FC4-7625-44DB-9B08-CB7E130B2029",
  "major" : 500,
  "minor" : 101 }
  • area_type:
    • "beacon" if a beacon has been seen.
    • "geofence" if a monitored geofence has been entered.
  • trigger: Depending if the beacon appeared or disappeared of sight of the device:
    • "on_entry"
    • "on_exit"
  • proximity_uuid: the UUID of the monitored beacon region.

Only if "area_type" contains "beacon" :

  • major : Major of the beacon.
  • minor : Minor of the beacon.

Trigger event

{ "type" : "trigger",
  "area_type" : "beacon",
  "trigger" : "on_entry",
  "beacon_id" : 598,
  "geofence_id" : 1245,
  "rule_id" : 7815 }
  • area_type: "beacon" or "geofence", depending of the type of interaction that triggered.
  • trigger: Depending if the rule triggered on entry or on exit:
    • "on_entry"
    • "on_exit"
  • rule_id: ID of the rule of the interaction that triggered.

Only if "area_type" contains "beacon" :

  • beacon_id: ID of the beacon interaction that triggered.

Only if "area_type" contains "geofence" :

  • geofence_id: ID of the geofence interaction that triggered.

Action event

An action event is logged for each executed action within a rule being executed.

{ "type" : "action",
  "area_type" : "beacon",
  "action" : "notify_user",
  "beacon_id" : 598,
  "geofence_id" : 1245,
  "rule_id" : 7815 }
  • area_type: Same as above.
  • action: Type of the executed action, can be:
    • "notify_server": Executed a server notification action
    • "notify_user": Executed a local notification action
    • "open_url": Opened a web page
    • "open_pbk": Opened a passbook / Samsung Wallet coupon
    • "open_deep_link": Opened a deep link
  • beacon_id: Same as above (present only if "area_type" = "beacon")
  • geofence_id: Same as above (present only if "area_type" = "geofence").
  • rule_id: Same as above.

Notification opened event

{ "type" : "open_notif",
  "area_type" : "beacon",
  "beacon_id" : 598,
  "geofence_id" : 1245,
  "rule_id" : 7815 }
  • area_type: Same as above.
  • beacon_id: Same as above (present only if "area_type" = "beacon")
  • geofence_id: Same as above (present only if "area_type" = "geofence").
  • rule_id: Same as above.

Integration Example: Google Analytics on iOS

- (void)ubudu:(UbuduSDK *)ubuduSDK didLogEvent:(NSDictionary *)event atTime:(NSDate *)eventDate
{
    // Event type and area type keys are always available
    NSString *eventType = event[@"type"];
    NSString *areaType = event[@"area_type"];
    
    NSString *areaID = nil;
    if ([areaType isEqualToString:@"beacon"]) {
        areaID = event[@"beacon_id"];
    } else if ([areaType isEqualToString:@"geofence"]) {
        areaID = event[@"geofence_id"];
    }
    
    NSString *action = nil;
    NSString *label = nil;
    
    // Send only events related to rule execution to GA
    if ([eventType isEqualToString:@"trigger"]) {
        action = @"Rule Trigger";
        // Label example: "Trigger: beacon interaction (1234) - rule (4567) - on_entry"
        label = [NSString stringWithFormat:@"%@ interaction (%@) - rule (%@) - %@", areaType, areaID, event[@"rule_id"], event[@"trigger"]];
    } else if ([eventType isEqualToString:@"action"]) {
        action = @"Action Executed";
        // Label example: "Action: beacon interaction (1234) - rule (4567) - notify_user"
        label = [NSString stringWithFormat:@"%@ interaction (%@) - rule (%@) - %@", areaType, areaID, event[@"rule_id"], event[@"action"]];
    } else if ([eventType isEqualToString:@"open_notif"]) {
        action = @"Notification Opened";
        // Label example: "Notif Opened: beacon interaction (1234) - rule (4567)"
        label = [NSString stringWithFormat:@"%@ interaction (%@) - rule (%@)", areaType, areaID, event[@"rule_id"]];
    }
    
    if (action != nil) {
        id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];
        [tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"Contextual Interaction"  // Event category (required)
                                                              action:action                     // Event action (required)
                                                               label:label                      // Event label
                                                               value:@1] build]];               // Event value
    }
}