Event Data Enrichment - iOS
Overview
The modules in the Oracle CX Mobile SDK can help you capture user behavior data in the form of events. Events captured by a module can be enriched by adding additional data points to further refine the context around which the event occurred. The Core module acts like a central module that other modules in the Oracle CX Mobile SDK can subscribe to and observe. Whenever the Core module receives an event that is subscribed by the other modules, all the subscribing modules are notified. The modules that subscribed for events from the Core module are called observing modules or Observers.
The Core module includes the ability to act as an Observable that publishes events as and when they are generated/received. Observers subscribe to Observable and get notified when an event is generated/received. Every event generated by the modules in the SDK has its Group name. This Group name plays a vital role while subscribing.
The Core module provides an interface called ORAEventListener that gives an ability to subscribe for events. These Observers override the onEventFound method where the add or update or deleting of data will be carried out.
Implementing Process Communication Queues
The Core module has the capability to act as an Observable and provides an interface that gives the ability to Observe. The Core module provides ORABaseDataCollector.addEventListener() method which registers the Observer on the Observable. Before registering, we have to set the Priority for the listener. The Priority parameter is a positive integer that ranges from 1 to 16, where 1 is the highest priority and 16 is the lowest priority. Any value passed that is out of range, is considered as least priority.
Register or Add Observers
-
Add event listeners aka Observers by invoking the 'addEventListener' method. This method is available in the 'ORABaseDataCollector' class.
ModuleListener *moduleListener = [[ModuleListener alloc] init];
[[ORACoreDataCollector sharedCollector] addEventListener: moduleListener
withName:@"ModuleListener"
withEventGroup:@[ORA_EG_INTERACTION, ORA_EG_SCREEN, ORA_EG_CUSTOM]
andPriority:1];
let moduleListener = ModuleListener()
ORACoreDataCollector.shared().addEventListener(moduleListener, withName: "ModuleListener", withEventGroup: [ORA_EG_INTERACTION, ORA_EG_SCREEN, ORA_EG_CUSTOM], andPriority: 1)
In the above snippet, the ModuleListener is the subclass of ORAEventListener interface. The ModuleListener subclass has a method onEventFound that must be overridden. This method accepts one parameter NSDictionary which is a generated event and returns an updated event object.
- (void)onEventFound:(NSDictionary *)event
withCompletion:(void (^)(NSDictionary * _Nonnull))completion {
NSMutableDictionary *newEvent = [[NSMutableDictionary alloc] initWithDictionary:event];
[newEvent setValue:@"MODULE LISTENER ADDED EVENT" forKey:@"moduleListner"];
completion(newEvent);
}
func onEventFound(_ event: [AnyHashable : Any]?, withCompletion completion: @escaping ([AnyHashable : Any]) -> Void) {
var newEvent = event
newEvent["moduleListner"] = "MODULE ADDED EVENT"
completion(newEvent)
}
Requirements for adding an event listener.
-
A unique identifier for the module.
-
For every listener we register, we must provide a unique name as an identifier. The identifier is important for registering or de-registering an observer. The name string must be passed in the addEventListener() method.
Note: Listener name must be alphanumeric only.
-
Every event that is captured belongs to some category. This category is called 'Group'. While subscribing to an observable, we register to listen to all the events which belong to a group. So we need to pass a valid group name as a parameter in addEventListener() method. The valid group names for the events captured by the Core module are listed in 'ORAEventGroup' class.
An observer can register to listen to events from multiple groups, by sending an array of group names in the method argument.
Sample code snippet with Group name
Subscribing to a single group
NSArray *group = @[ORA_EG_INTERACTION];
let group = [ORA_EG_INTERACTION]
Subscribing to multiple groups
NSArray *group = @[ORA_EG_INTERACTION, ORA_EG_SCREEN, ORA_EG_CUSTOM];
let group = [ORA_EG_INTERACTION, ORA_EG_SCREEN, ORA_EG_CUSTOM]
Subscribing to all events
NSArray *group = @[ORA_EG_TYPE_ALL];
let group = [ORA_EG_TYPE_ALL]
Remove or Deregister observers
To de-register observers we need to invoke the remove method on the ORACoreDataCollector object.
[[ORACoreDataCollector sharedCollector] removeEventListener:@"moduleListner"];
ORACoreDataCollector.shared().remove(listener: "moduleListner")