Benshi React Native (Android) SDK Setup - Loyalty

Benshi Android SDK Loyalty module consists of events for rewarding platforms. You need to implement this module if your app offers users some rewards, points on completing certain actions or achieving a certain milestone by using your app. To use the loyalty module you need to include the following dependency in your app-level build.gradle but make sure you have the core module already integrated.

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.

Getting Started

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 require the core to be integrated 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-loyalty": "<version_number>"
  }, 

for version_number please head to npm package.

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

npm install

This will install the loyalty npm package in the node modules 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-loyalty

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

To add the dependency, open your android folder in Android Studio and open the app-level build.gradle file. now in your dependencies add the following:

dependencies {

  implementation project(path: ':@benshi.ai_react-native-bsh-loyalty')

}

Please note that this package required you to already install and linked react-native-bsh-core package in your app or else the logs will not be triggered.

Tracking System Events

We have several predefined 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.

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

| Event Name | Calling in SDK | Description | | ---------- | --------------- | ---------------------------------------------------------------- | | Level | EventType.level | Track user's change of level. | | Milestone | EventType.milestone | Track user's achieving of certain level. | | Promo Event | EventType.promo | Track user's usage of promos in the app for items. |

To log loyalty events you need to import BsLoyalty main class and contents to support different actions:

import BshLoyalty from '@benshi.ai/react-native-bsh-loyalty';

Here BshLoyalty is the main class for all the loyalty-related events to help you implement logs in a functional approach. while rest are content classes to help you with actions for different logs. You can also pass strings instead of these content values but the params should be the same as provided in contents or else the log will not be triggered and an exception will be thrown by the SDK. BsLoyalty class contains a list of functions in the main module and every function has 2 extra params to help you, you can include them in the parent functions, one is meta which 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 param 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.

Usage for the above-mentioned events is given below:

Level Event

logLevelEvent is to log the update of user level. It required the user level before update and user level after the update. You need to pass module Id as well if the level update event is triggered because of the e-learning content block, any achievement in the e-learning platform.

• @param previous_level is required to set the previous score/level number for the user.
• @param new_level is required to set the new score/level number for the user. This can be from any source, e-learning or e-commerce, or even social.
• @param module_id is for specific use-case when an update of level is from e-learning. In such a case module id is required, otherwise, you can pass null for this as well.

let levelProperties = {
  previous_level: 89,
  new_level: 90,
  module_id: "testModuleId"
}
BshLoyalty.logLevelEvent(levelProperties)

Milestone Event

logMilestoneEvent is to log actions regarding milestones which can be when the user achieved a milestone.

• @param id is required for logging the milestone user achieved. The is should be in a string format and must be per the catalog provided.
• @param action is required to set the Action type for the Milestone event. SDK provides enum classes to support available log types. 1 main is achieved. SDK provides 2 approaches to log this event, one being enum type and the other being string type.

let milestoneProperties = {
  id: "testMilestoneId",
  action: MilestoneAction.Achieved
}

BshLoyalty.logMilestoneEvent(milestoneProperties)

MilestoneAction is required to set the Action type for the milestone event. SDK provides the enum class MilestoneAction to support available log types.

Achieved // for logging achieving of the milestone

Promo Event

logPromoEvent is to log the events associated of the promo lists and promo items and when they are clicked on.

• @param promoId is required to set the Id of the promo.
• @param action is required to set the action for the promo
• @param title is required to set the title of the promo (if any)
• @param type is required to set the type of the promo
• @param promoItemsList to add the whole list to the log at once, the format should be Array to log the event successfully.

let promoItem1 = {
    id: "ItemId1",
    type: PromoItemType.Drug
}

let promoProperties = {
    id: "promoId",
    action: PromoAction.Apply,
    title: "Buy 3 and get 10% off",
    type: PromoType.AddToCart,
    items: [promoItem1, promoItem2]
}

BshLoyalty.logPromoEvent(promoProperties)

PromoAction is required to set the Action type for the promo event. SDK provides the enum class PromoAction to support available log types.

View // for logging viewing of promo events when viewed in a list
Apply // for logging of promo when applied to an item/product

PromoType is required to set the type for the promo event. SDK provides the enum class PromoType to support available log types.

AddToCart // for logging when promo is meant to add the item to cart, purchasing 3 items to get discount
Coupon // for logging when promo is meant to apply coupon on the order to get discount

For implementation, you can also view the demo app.

Guidelines

• Including lifecycle components is required to use the SDK as SDK requires lifecycle components to listen for app events regarding app sessions and app moving to the 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 initialize the SDK in the Application 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.

Please feel free to drop in a few lines at [email protected] in case you have any further queries. We're always just an email away!