In order to be able to gain insight into the effectiveness of a campaign it is necessary to be able to track the user journeys that have been triggered. In order to allow this user journey to be reported on the TapPoint SDK provides reporting hooks.
Reporting Hooks are APIs that allow an application to inform the TapPoint SDK when significant steps in the user journey are taken as a result of a beacon interaction.
Whenever these hooks are used TapPoint SDK sends a reporting event back to TapPoint, by combining this data with the data automatically reported by the TapPoint SDK the value of a campaign on the proximity network and can be proven.
The events that can be reported via the reporting hooks are:
| Hook | Description |
| User Notified | The user has been notified of the occurrence of the trigger, for example via a notification or some other UI element within the app. |
| User Selected | After being notified about the occurrence of a trigger, the user chose to find out more information. |
| User Converted | After "clicking-through" on the notification the user has taken an action that is significant to the application such as making a purchase. |
The interpretation of when the user has completed these actions is left up to the developer.
The reporting hooks are used via the Report Trigger Event API of the Reporting Manager that is documented in more detail here
Android Reporting Manager - Trigger Event API
iOS Reporting Manager - Trigger Event API
It's important when analyzing the reporting data for a campaign that the user journey can be associated with an individual user and there is some context to the actions that they took.
The source for this information is likely to be within the back-end system that holds an app data, in order to provide a link between data held on TapPoint and data in this external system reporting hooks can optionally have references to the external system attached to them.
By setting an external user reference all events reported by the TapPoint SDK will be associated with that reference, this allows the events to be tied to an individual.
An external user reference can be set by using the Set External User Reference API of the Reporting Manager.
iOS Reporting Manager - External User Reference API
Android Reporting Manager - External User Reference API
Setting an external user reference is optional and need only be done once on start-up of the app.
Setting an external event reference adds context to the actions taken by a user and allow these actions to be associated with data within an app or from an external system.
An external event reference can be added to an event by using an override of the Report Trigger Event API of the Reporting Manager.
iOS Reporting Manager - Trigger Event with External Reference API
Android Reporting Manager - Trigger Event with External Reference API
Adding an external event reference is optional on an event by event basis.
Presented below are code snippets showing how reporting hooks can be utilized in an app along with external references to report on the user journey.
In this example a BroadcastReceiver has previously been configured to call notifyUserAboutTrigger for each detected Trigger on receipt of the ACTION_TRIGGERS_DETECTED intent.
public void notifyUserAboutTrigger(Trigger trigger) {
// ...Generate a notification based on the triggers payload, attach the trigger object
// to the notification so it can be used when the user clicks it and use the contentIntent
// to detect when they click it...
ReportingManager reportingManager = Reporting.getReportingManager(getApplicationContext());
reportingManager.reportTriggerEvent(TriggerEventType.USER_NOTIFIED, trigger.getTriggerId());
}
public void processNotificationClick(Trigger trigger) {
// ...Extract the trigger from the notification and take whatever action is necessary when the user
// clicks the notification...
ReportingManager reportingManager = Reporting.getReportingManager(getApplicationContext());
reportingManager.reportTriggerEvent(TriggerEventType.USER_SELECTED, trigger.getTriggerId());
}
In this example NSNotificationCenter has been used to ensure processDetectedTrigger is called on receipt of a PRXTriggersDetectedNotification notification.
- (void)configureExternalUserReference
{
[[PRXReporting sharedReportingManager] setExternalUserReference:@"5785475b-beae-4810-bb9f-a4dbbd7f85c2"];
}
- (void)processDetectedTrigger:(NSNotification *)notification
{
NSLog(@"TapPoint Triggers Detected!");
PRXTrigger *trigger = [notification.userInfo objectForKey:PRXDetectedTriggerNotificationKeyForTrigger];
// ...Generate a notification based on the trigger, attach the trigger object
// to the notification so it can be used when the user clicks it...
[[PRXReporting sharedReportingManager] reportTriggerEvent:PRXTriggerEventTypeUserNotified
triggerID:trigger.identifier
externalEventReference:@"2 for 1 on Crisps"];
}
- (void)processNotificationClick:(PRXTrigger *)trigger
{
PRXTrigger *trigger = [notification.userInfo objectForKey:PRXDetectedTriggerNotificationKeyForTrigger];
// ...Extract the trigger from the notification and take whatever action is necessary when the user
// clicks the notification...
[[PRXReporting sharedReportingManager] reportTriggerEvent:PRXTriggerEventTypeUserSelected
triggerID:trigger.identifier
externalEventReference:@"2 for 1 on Crisps"];
}
- (void)processUserCrispPurchase:(PRXTrigger *)trigger
{
PRXTrigger *trigger = [notification.userInfo objectForKey:PRXDetectedTriggerNotificationKeyForTrigger];
// ...The user has been converted and made a purchase...
[[PRXReporting sharedReportingManager] reportTriggerEvent:PRXTriggerEventTypeUserConverted
triggerID:trigger.identifier
externalEventReference:@"2 for 1 on Crisps"];
}
To provide app developers with the ability to report on events to specific to their app, we have introduced custom reporting hooks. These work much in the same way as any other reporting event where the event name and data can be specified.
For example, if a consumer were to enter a vehicle (such as a bus), the custom reporting hooks could be used to report the consumers known journey information.
In this example the custom reporting hook is used to report information about a users journey.
private void sendCustomEvent(Context context) {
Map reportingData = new HashMap();
reportingData.put("busId", "23");
reportingData.put("busRoute", "Kings Cross");
ReportingManager reportingManager = Reporting.getReportingManager(context);
reportingManager.reportUserEvent("Vehicle Entered", reportingData);
} - (void)sendCustomEvent
{
NSDictionary* customProperties = @{@"busId" : @"23", @"busRoute": @"Kings Cross"};
[[PRXReporting sharedReportingManager] reportUserEvent:@"Vehicle Entered" customProperties: customProperties];
}