react-native-test-core v1.0.0-beta03

Benshi React Native (Android) SDK Setup

This documentation covers the steps to integrating SDK in your react native (android) apps. We’ll also discuss a few fundamentals of how the dashboard works in tandem with your app usage to view your users and engage them with contextually personalized messages.

There are two types of data we collect from the partner's side:

1. content data (static content / items in the app)
2. event data (event names, event details)

Content data are static data of certain content (e.g. video, audio, a product, etc.). Event data is time-series data generated by the user.

Getting Started

In order to create ease for partners, we have divided the SDK into multiple modules. Each module represents a specific app niche that partners can use based on their app category.

A list of these modules are:

1. Core

2. E-Learning

In order to use the SDK, Core is mandatory to include as it contains the elements regarding the basic app navigation and workflow including nudges. Moreover, all the modules requires Core to be integrated in order to successfully log the events.

The easiest way to integrate Benshi react native (android) SDK in your project is using an NPM package. Add dependencies of react native SDK in the dependencies section of your package.json of your project and Android Lifecycle Components in the app/build.gradle file.

"dependencies": {
    "@benshi.ai/react-native-bsh-core": "<version number>"
  },

After including the above, Open terminal/shell and go to your project directory and run:

npm install

This will install the core npm package in your node mosules of your project. Now you need to link this module with your android app, for this in the same terminal in your project directory run:

react-native link @benshi.ai/react-native-bsh-core

This will link your newly added module with your android app and you can also see the link in your andorid settings.gradle file.

As SDK requires app events to auto manage the logging of user sessions you also need to include android lifecycle dependency in your andorid app/build.gradle file. To add the dependecy, open your andorid folder in Android Studio and open app level build.gradle file. now in your dependencies add the following:

dependencies {

    //LifecycleComponents
    implementation 'androidx.lifecycle:lifecycle-process:2.3.1'
    implementation project(path: ':@benshi.ai_react-native-bsh-core')

}

Lifecycle components are required, if you already have them in your project you may skip them.

Initialization

Create an Application class in your project and include LifecycleEventObserver Components. Initialize Android SDK with your SDK Token from onCreate callback of your Application class as shown below.

public class MainApplication extends Application implements ReactApplication, LifecycleEventObserver {

    @Override
  public void onCreate() {
    super.onCreate();

      // to observe Application lifecycle events
      ProcessLifecycleOwner.get().getLifecycle().addObserver(this);

  }

    /*
        In onStateChanged() function include the following function to auto track events related to app and activity lifesycle.
    */
    @Override
    public void onStateChanged(@NonNull LifecycleOwner source, @NonNull Lifecycle.Event event) {
        BsLogCore.benshiInit(this, event);
    }

Benshi Android SDK requires SDK key in order to log event. To do so, you need to create SDK key from the Benshi Platform and pass it to the SDK using the app's Manifest file as meta-data like below:

<meta-data android:name="ai.benshi.android.sdk.APPLICATION_KEY"
            android:value="<SDK_KEY_HERE>" />

Benshi Android SDK also allows you to update track events after the user’s usage session is over. SDK sends the events whenever the app goes into background. This helps in not overloading the user’s phone while in use. SDK handles the events even in offline mode and ensures that they get uploaded to the portal whenever the user connects to the internet. SDK also auto logs the App Open, close and background events so, you don't have to implement those.

Don't forget to include android:name=".MyApplication" in your manifest's application tag.

Android SDK - Core - Event Tracking

Benshi Android SDK automatically starts tracking user data (e.g., Upload/download speed, OS version, device IDs) and engagement with the basic setup above. This data can be stored on the device and uploaded in batches to reduce network and power usage, and to increase the likelihood of successful uploads while you can also upload the events as soon as they happen. The upload is done when the user device session ends. SDK also starts tracking user sessions with this basic setup.

Each event can further be understood in the context of its attributes which includes details like time, upload/download speed, device details, locale, online/offline usage, screen time, interactions and so on. This enables you to gain in-depth insights into user interactions across your app. You can also leverage this data to segment users, personalize messages and configure campaign targeting.

Let’s take a look at the general structure of the attributes sent using that SDK:

For example, if a user needs to click on a product to view its details, then it is advisable to track this action as the event, product viewed as it brings them a step closer to making a purchase.

To log CoreEvents you need to import Core main class and contants to support different actions:

import {BsCore, IdentityAction, MediaType, MediaActions, SearchType, TrackType} from '@benshi.ai/react-native-bsh-core';

Here BsCore is the main class for all the core related events to help you imlepment logs in a function approach. while rest are contant classes to help you with actions for different logs. You can also pass strings instead of these contant values but the params shouls be same as provided in contants or else the log will not be triggered and an exception will be thrown by the SDK. BsCore class contains a list of functions in the core module and every function has 2 extra params to help you, you can include them in the parent functions, one is meta whoch you can use to pass data you want to the SDK but remember to pass it in as key-value pair and convert that to JSON string so that it may be parsed with the rest of the SDK content. the last parm is the updateImmediately boolean which helps you to send a specific log as soon as it happens as by default SDK logs the events at the end of the session in a batch.

SDK events are divided into 2 main categories: User Events and System Events.

Tracking User Events

SDK automatically starts detecting the users across your platforms as soon as they're integrated. These visitors are classified as Unknown Users and Known Users.

Let's walk you through this:

Unknown Users

Each time a new user uses your app, they are tracked as anonymous users in your dashboard and an Unknown User Profile is created for them. The Android SDK automatically assigns them a unique ID (based on their device ID) and starts populating their user profile with all their data (System Events).

Known Users (Identity Events)

As and when the users share details that help you identify them in your platform, you can assign them a unique ID (Your Platform based UserId) to track them as Known Users. This user is now stored in our database as the ‘Identified/Registered’ ones. A new user profile is created for them that contains all their data from the previous anonymous user profiles, too merged with the new account.

Implementation

To Log identity events which involves events regarding the user of the app such as register, login or logout you can use Identity log events that are divided into 3 different types. For convenience, you can use IdentityAction.{action name} in the log function. examples are:

• IdentifyAction.register for new user (sign up)
• IdentityAction.login for login (sign in)
• IdentityAction.logout for logout (sign out)

Identity events are used to log user related events that represents user register events, user login events and user logout events. SDK will store the userId provided in the identity events and log the remaining events with that userId. So you don't have to provide the userId again. In case of logout event, SDK will auto erase all of the stored data including the userId. Identity events requires 2 main params:

@param userId is the user id that is using the app, userId should be the id from your platform that is assigned to the user. @param identityAction enum is the identity Action that defines whether the user is logging in or a new user or logging out.

/*
You can log the register event as:
*/
BsCore.logIdentityEvent("appUserId", IdentityAction.register)

/*
You can Log sign in of the user, use the below, you don't need to call the login on splash screen or everytime the user opens the app.
*/
BsCore.logIdentityEvent("appUserId", IdentityAction.login)

/*
You can also set use the Logout event as:
*/
BsCore.logIdentityEvent("appUserId", IdentityAction.logout)

appUserId is required to identify the user based on the userID. You only need to provide this Id once and afterwards the SDK will be responsible for storing and passing the userID with log events. One important thing to note here is that calling the logout action will remove any data stored by the SDK including the userID but only after successfully uploading the existing data to the backend.

Tracking System Events

We have several pre-defined actions that users can perform while interacting with your app. These actions are referred to as System Events that help in tracking elements on your app with user interaction. Some of these events are automated so that you don’t have to spend time integrating them.

Here's a list of System Events that can be tracked using Core module:

Examples for above-mentioned events with both approaches are given below:

Page Event

To Log page/screen change events.

By default, SDK auto listens for Activity changes in the app along with session timings that implicates how log a user spends on an activity, but you can also log any specific event you want to track using below approach:

@param pagePath is for the page path, where the page/screen is inside the code packages. @param pageName is the page name, the name of the class. @param duration is the duration (in seconds, integer) the user spent on that page, it is ideal to log this event when user moves to the next page so that you can track the time user spent on the page.

BsCore.logPageEvent("pagePath", "pageTitle", 5) // 5 is the number of secoonds user spent on that activity.

Media Events

Media event can be used to log events regarding media, for logging the user interaction with the media controls. For example video, image and audio. you can track different interaction events based on your implementation like when the user plays or pauses the video or audio, if they seeks the video or audio to a certain time frame or if they watched the video or finished listening the audio. Params details are as below:

@param mediaId is for the mediaId used in your system, should be a string. @param mediaType enum is for the media type that if it is a video, audio or image. @param mediaAction enum is for the actions performs on the media, it includes play, pause, seek and finish. For Image media type the default media action is play which represents image open event. The same will be used if user swipes in a fullscreen image browser. @param time is the timeframe in millisecond for the video and audio, this is the actual time of the media when the event is triggered.

BsCore.logMediaEvent("mediaId", MediaType.video, MediaActions.pause, currentSeekTime) // currentSeekTime is the timeInMillis for the video/audio current timeframe.

MediaType is required to define the type of media being interacted with. It is required to define if the media interacted with is an audio, is a video or an image. SDK provides enum MediaType to use for media types.

image // for image media type
video // for video media type
audio // for audio media type

MediaAction is required to log the interaction action with the media. SDK provides enum MediaAction to support mediaActions and are defined in 4 different actions.

play // to log the start of the media like video or audio or even opening the image.
pause // to log the pause event for the audio and video media types.
seek // to log the seek event when the user interacts with the seek bar of the video.
finish // to log the finish event of the media.

Search Events

You can use search event to track how search returns results based on user queries and what items user are searching for. It supports all the module available by benshi i.e. general, e-learning, e-commerce etc. You also need to log the Ids in the form of string list to log what results are returned by the search and in case of no result found, you can log with an empty list. Search also supports filters if any applied to the search by the user which are supported in the app. You can provide these filters in the form of hashMap formatted as <String, String>

@param searchType enum is for the module the search is used in, e-commerce, e-learning, ... @param query is for the search query which the user is searching for. @param result_ids is the list of result ids returned in the search, can be an empty list in case of no results returned. @param filter is the filters applied on search, filters should be mapped as a hashmap data type with <String, String> format. in case the search does not offer any filters you can also send null in place of the filter param.

BsCore.logSearchEvent(SearchType.e_learning, "Search Query", resultIds, filters)

Track Events

To log user interactions with custom components inside the app. Track events is required to log events related to UI elements, viewing a list, viewing an item and also if user taps on an external link. There are 3 types of track at the moment which included view list, view item and opening an external link

@param trackType is for the providing the type of track being logged. For Track events you need to set the track type to differentiate among multiple track types. TrackType can be viewing a list of elements, tapping an item from the list to view more details on that but in such case passing the item id is required to log the event. @param itemId is required to set the item Id for the item being viewed. It is required if the track type is view_item. For others, you may skip this.

BsCore.logTrackEvent(TrackType.view_item, "itemId")

TrackType is for providing the type of track being logged. For Track events you need to set the track type to differentiate among multiple track types. TrackType can be viewing a list of elements, tapping an item from the list to view more details on that but in such case passing the item id is required to log the event.

view_list // for viewing a list of elements
view_item // for viewing a specific element
external_link // for opening an external link to provide more information

For implementation, you can also view the dmeo app.

Android SDK - Nudge

With Nudges, you can utilize experiment based data-driven insights and predictions for individual behaviors towards shaping strategies for collective behaviors. Nudges help you to interact with your users. You can use nudge to send push notifications, in-app messages or use other methods to interact with your users.

App publishers can send them at any time; even if the recipients aren’t currently engaging with the app or using their devices. You can start sending Push Notifications to your users via Benshi platform after initializing the SDK. No separate configuration is required to integrate nudges. SDK will listen for the nudges on its own and also log the user behaviour based on the nudge Id that if the user opened the nudge or discarded that.

Guidelines

• Including lifecycle components is required in order to use the Sdk as SDK requires lifecycle components to listen for app events regarding app sessions and app moving to background.
• Anything you include in the meta will be sent to the backend and be visible in the log monitoring section, but it will not be processed.
• Custom Event Attributes can be of these data types: String, Number, Boolean, Date, List, Map.
• Make sure to include your SDK key in the manifest of your Android App so that SDK can have that while initialization or else it would through an IllegalAccessException.
• Make sure to initialise the SDK in the Applicaion class or else if you trigger SDK events without that it will through RuntimeException.
• updateImmediately is an optional param, by default its value is true. You can decide for each event if it needs to be updated immediately, or it can wait until the end of the app session.
• Please ensure consistent usage of the names of Custom Events in meta and their Custom Attributes across all your apps (Android, iOS) and website.
• Please use the same name conventions as provided by the enums if you choose to pass strings as values or else the event will be discarded and an IllegalArgumentException will be thrown.
• Nudges may not be delivered to apps which were put into background restriction by the user (such as via: Setting -> Apps and Notification -> app-name -> Battery). Once your app is removed from background restriction, new messages to the app will be delivered as before. In order to prevent lost messages and other background restriction impacts, make sure to avoid bad behaviors listed by the Android vitals effort. These behaviors could lead to the Android device recommending to the user that your app be background restricted. Your app can check if it is background restricted using: isBackgroundRestricted().
• In cases where user resticted the app to show push notifications for the whole app or blocked the benshi notification channel, the SDK will log blockevent for that nudge.

Please feel free to drop in a few lines at support@benshi.ai in case you have any further queries. We're always just an email away!