Advanced : custom events handling for Android SDK

Custom events handling

​
Contextual Interactions UbuduSDK delivers the event's notification and displays it automatically by default. It is however not always desirable as the developer might want to handle it in a completely custom way.

For example it might be good to first ask the user for permission to present the notification content before actually doing it. Another example is that the default open web url action is performed on a defalt native WebView activity that is built into the UbuduSDK so if developer wants to display it in his custom web view this is also where custom handling is needed.
These are just examples to justify the need of giving the developer an option to handle the event completely on his own.
​
However one important issue has to be handled carefully while custom handling the event which is notifying the SDK about it so the proper statistic log can be appended and posted to the back office.
Without it the application's statistics data will be corrupted as SDK will not log the actions of the notifications being opened by the users.
​
First thing is to disable automatic user notifications at the UbuduSDK configuration stage. This can be done as follows:
​
mBeaconManager.setEnableAutomaticUserNotificationSending(false);

This setting will disable automatic user notifications sending and in result the UbuduAreaDelegate method void ruleFiredForEvent(UbuduEvent event) will never be called and no actions will be executed. Instead of it the app's delegate will be notified about the event by boolean shouldNotifyUserForEvent(UbuduEvent event).
​

Should notify user

​
Delegate's shouldNotifyUserForEvent(UbuduEvent event) method asks the app if the user should be notified about the event. This method gives developer a chance to cancel the event execution and not count it in the limits. If the shouldNotifyUserForEvent returns false the SDK will drop the event and decrement its counter so the rule can be fired again when its proximity conditions are satisfied. If it returns true then the SDK calls the delegate's void notifyUserForEvent(UbuduEvent event) and appends an notify_user statistic log.
​
If the decision to drop the event has to be delayed because of some long lasting decision making operation then the UbuduDelayedCustomEventHandlingAreaDelegate delegate interface should be implemented instead of a default UbuduAreaDelegate. This delegate is just an extension of the default UbuduAreaDelegate that provides one more method:

/**
 * @param event    event
 * @param callback callback object to notify the SDK that the user should be notified about the event.
 */
void shouldNotifyUserForEvent(UbuduEvent event, UbuduAreaDelegateNotifyUserForEventCallback callback);

​
This method contains an instance of UbuduAreaDelegateNotifyUserForEventCallback callback interface in its arguments which can be used at any time to notify the UbuduSDK about the decision to notify user about event or not. When eventually the decision is made the following method should be called:

callback.shouldNotifyUser(true);

When the boolean argument is true then the SDK will append a notify_user log and call delegate's void notifyUserForEvent(UbuduEvent event) method. If the boolean argument is false then the SDK will just decrement event counter so the rule can be fired again when its proximity conditions are satisfied, no logs are appended.
​

Notify user for event

​
Whenever the shouldNotifyUserForEvent method returns true or callback.shouldNotifyUser(true) is called the SDK calls the delegate's void notifyUserForEvent(UbuduEvent event). In this method the developer should handle the presentation of the payload data and actions data to the user. The only thing that has to be done to keep the statistic logs consistent is to notify the SDK when the user has opened the notification (e.g. from the background) or actually seen the event's content. This can be done at any time by calling the following code:
​
mBeaconManager.actionsCustomExecutedForEvent(event); ​
where event is an UbuduEvent instance that came in the notifyUserForEvent method as argument. Calling this method will tell UbuduSDK to append open_notif type log and post it to the back office for application statistics.
​
Note: To make things easier the UbuduEvent object extends the android.os.Parcelable interface so it can be easily put as extra into an Intent object and be sent to another activity or set in the background notification's PendingIntent.

There is also an option to execute the event's actions in a default way by calling:
​
mBeaconManager.executeActionsForEvent(event); ​
This method will execute open web url/deeplink/Samsung Wallet actions in a default way (e.g. web url will be shown in a default native fullscreen WebView activity) and also append an open_notif log.