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.