Benshi React Native (Android) SDK Setup - E-Commerce

Benshi Android SDK E-Commerce module consists of events for online marketplace platforms. You need to implement this module if your app offers e-commerce content that may include showcasing items to purchase, logging impressions, checking out events, and also events related to delivery as well. In order to use e-commerce, 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

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 require 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-e-com": "<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 e-com 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-e-com

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 app-level build.gradle file. now in your dependencies add the following:

dependencies {

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

}

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 e-commerce module:

| Event Name | Calling in SDK | Description | | ---------- | --------------- | ---------------------------------------------------------------- | | Item | EventType.item | Track user interactions with items of marketplace.| | Cart | EventType.cart | Track user interactions with the cart. | | Checkout | EventType.checkout | Track user interactions with checkout event happening inside the app. | | Delivery | EventType.delivery | Track events related with delivery of the order. | | Schedule Delivery | EventType.schedule_delivery | Track events related with scheduling delivery of the order. | | Cancel Checkout | EventType.cancel_checkout | Track events related with discarding a cart or cancelling an order after checkout |

To log e-commerce Events you need to import BshECom main class and contents to support different actions:

import BshECom from '@benshi.ai/react-native-bsh-e-com';

Here BsECom is the main class for all the e-commerce 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. BsECom 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:

Item Event

logItemEvent refers to an item in E-commerce. It can be called when a user taps on an item to view it in full screen and also when a user taps on the description of the item to view more details. This event refers to the item view log that reflects the user has seen a specific item or viewed its details.

• @param action is required to set Type for the type of log in this case, if a user is viewing an item or its details.
• @param item is required to pass the whole item as a JSON String object as well. You can use the POJO ItemModel to parse the data in the required format and pass that to this function as a string to log the event.
• @param search_id is used to associate the search id with the item being viewed by the user. It is required to track if the item is a result of some search performed by the user in the app.

let itemDetail = {
    id: "itemId",
    type: ItemType.Drug,
    quantity: 1,
    price: 1.45,
    currency: CurrencyCode.USD,
    stock_status: StockStatus.InStock,
    promo_id: "testPromoId"
}

export enum ItemType {
    Blood = "blood", // separate catalog Object
    Oxygen = "oxygen", // separate catalog Object
    Drug = "drug", // separate catalog Object
    MedicalEquipment = "medical_equipment" // separate catalog Object
}

let itemProperties = {
    action: ItemAction.View,
    item: itemDetail,
    search_id: null
}

let drugCatalogObject = {
    market_id: "MARKET_ID",
    name: "DRUG_NAME",
    description: "DRUG_DESCRIPTION",
    supplier_id: "SupplierId",
    supplier_name: "SupplierName",
    producer: "ProducerName",
    packaging: "Packaging",
    active_ingredients: active_ingredients[],
    drug_form: "TestDrugInformation",
    drug_strength: "TestDrugStrength",
    atc_anatomical_group: "AnatomicalGroup",
    otc_or_ethical: "OTC"
}

let bloodProperties = {
    market_id: "MARKET_ID",
    blood_component: "Platelets",
    blood_group: "A+",
    packaging: "Pint",
    packaging_size: 0.473,
    packaging_units: "L",
    supplier_id: "SupplierId",
    supplier_name: "SupplierName",
}

let oxygenProperties = {
    market_id: "MARKET_ID",
    packaging: "Cylinder",
    packaging_size: 5,
    packaging_units: "cubic meter",
    supplier_id: "SupplierId",
    supplier_name: "SupplierName",
}

let medicalEquipmentProperties = {
    name: "10ml Syringes and Needle",
    description: "10ml Syringes and Needle",
    market_id: "MARKET_ID",
    supplier_id: "SupplierId",
    supplier_name: "SupplierName",
    producer: "ProducerName",
    packaging: "carton",
    packaging_size: 50,
    packaging_units: "pks",
    category: "Syringe",
    
}

//Make sure that item type defined int he itemProperties is in accordance with the catalog provided otherwise an exception will be thrown.
BshECom.logItemEvent(itemProperties, drugCatalogObject)
BshECom.logItemEvent(itemProperties, bloodProperties)
BshECom.logItemEvent(itemProperties, oxygenProperties)
BshECom.logItemEvent(itemProperties, medicalEquipmentProperties)
BshECom.logItemEvent(itemProperties, null) // for cases where You don't have to send catalog information

ItemViewAction is required to set the log type for the item event. It is used to log the type of event, impression, view, or detail. SDK provides enum ItemViewAction to support available log types.

Impression // for logging impression on the item, be it in search or home screen.
View // for logging view on the item.
Detail // for logging event in case a user taps to view the description of the item.
AddToFavorite // for logging event in case of adding an item to the favorite list.
RemoveFromFavorite // for logging event in case of removing an item from the favorite list.
AddToReminder // for logging event in case of adding an item to the reminder list.
RemoveFromReminder // for logging event in case of removing an item from the reminder list.
RemoveFromReminderAuto // for logging event in case of item is auto-removed by the system from reminder list.

You are also required to set the item details in the ItemModel event to log the properties of the item being viewed. Inside the ItemModel currency code needs to be from the provided enum CurrencyCode and for similarly for the status as StockStatus to log the current status of the item.

Impression Listener

Benshi React native SDk currently supports RecyclerListViewScreen for the impression listener as it helps in recycling the views and improving performance. To start with the implementation,, you need to first map your list in the format required by the SDK.

var contentList = YOUR_LIST.map((product, index) => ({
        item_properties: {
            id: product.id,
            price: product.price,
            currency: CurrencyCode.IDR,
            quantity: product.quantity,
            type: ItemType.Drug,
            stock_status: StockStatus.InStock,
            promo_id: "testPromoId"
        },
        catalog_properties: { // can be DrugProperties or Medical Equipment Properties
            market_id: "id",
            name: "MedName",
            description: "testItemDescription",
            supplier_id: "SupplierId",
            supplier_name: "SupplierName",
            producer: "testProducerName",
            packaging: "10ML",
            active_ingredients: active_ingredients_array,
            drug_form: "",
            drug_strength: "",
            atc_anatomical_group: "",
            otc_or_ethical: ""
          }
      }));

then on your _lonVisibleIndicesChanged call the impression listener and pass the contentList:

const _lonVisibleIndicesChanged = (all, now, notNow) => {
        BshECom.logItemImpressionEvent(
                "collectionId",now,
                contentList, "searchId",
            );
      }

    return (
      <View style={styles.container}>
            <RecyclerListView rowRenderer={_renderRow} dataProvider={dataProvider}
                              layoutProvider={_layoutProvider}
                              onVisibleIndicesChanged={_lonVisibleIndicesChanged}
                              />
        </View>
    );

Impression listener will auto track the elements shown on the screen and log the impression events and also for the redundant scroll impressions.

Cart Event

logCartEvent is used to log the events related to the cart. You can use this event to log when an item was added or removed from the cart.

• @param id used to log the cartId the event is logged for. It is recommended to include the cartId for individual cart or user so that they can be tracked.
• @param action is required to pass the actions for the cart the logged is triggered on. By default, the SDK provides 2 main list actions for e-commerce apps. Which includes addItem and removeItem.
• @param item is used to pass the whole item as a JSON String object as well. You can use the POJO ItemModel to parse the data in the required format and pass that to this function as a string to log the event.
• @param cart_price is required to log the total price for the cart being logged. Details about the cart are to be provided in the catalog.
• @param currency is required to log the currency for cart price being logged. Details about the cart are to be provided in the catalog.

let cartProperties = {
    id: "testCartId",
    action: CartAction.AddItem,
    item: itemDetail,
    cart_price: 1.45,
    currency: CurrencyCode.USD,
}

BshECom.logCartEvent(cartProperties)

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

AddItem // for loging adding of item in cart
RemoveItem // for loging removing of item in cart

You are also required to set the item details in the ItemModel event to log the properties of the item being viewed. Inside the ItemModel currency code needs to be from the provided enum CurrencyCode to insure ISO 4217 and for similarly for the status as StockStatus to log the current status of the item.

Checkout Event

logCheckoutEvent is to track the success/failed use cases for the order placement. it can track KPIs for the order being placed based on the ratio of how many orders were successful and how many were not and what are the order aspects.

• @param id is for the orderId being placed. In case of not being placed and not having a valid orderId, you can pass the cartId instead.
• @param cart_id used to log the cartId the event is logged for. It is recommended to include the cartId for individual cart or user so that they can be tracked.
• @param is_successful is for the order if it was placed successfully or not.
• @param cart_price is required to log the total price of the order being logged. The price format should be in accordance with the currency selected.
• @param currency is required to log the currency for the order logged. Currency should be in ISO 4217 format. For ease, SDK provides the enums CountryCode to log the currency so that it would be easy to log. You can also use the string function to provide the currency.
• @param items_list can be used to add the item being ordered to the checkout list. Order items should be in a valid format. With elements of the order Object as OrderItem(itemID, price, quantity, promoId) Promo Id can be an empty string or no value at all if the item does not have a promo offer that is obtained by the user. You can add multiple addOrder functions to one checkout event to include all the items in the order.
• @param cart_id is the id for the cart checkout out.

let checkoutProperties = {
    id: "testOrderId", // order id
    cart_id: "testCartId",
    is_successful: false, // is checkout successful?
    cart_price: 5.90, // total checkout price
    currency: CurrencyCode.USD, // checkout price currency
    items_list: [itemDetail1, itemDetail2], // order list in the checkout
    cart_id: "testCartId" // cart id
}

BshECom.logCheckoutEvent(checkoutProperties)

You are also required to set the item details in the ItemModel event to log the properties of the item being viewed using an array or order items. Inside the ItemModel currency code needs to be from the provided enum CurrencyCode to insure ISO 4217 and for similarly for the status as StockStatus to log the current status of the item.

if any item in the items list contains the type as blood or oxygen then you need to provide meta corresponding to that item.

let bloodMetaProperties = {
    cross_matching: false,
    temperature_strips: true,
    extra_tests: true,
    reason: "General Surgery"
}

let oxygenMetaProperties = {
    order_type: "refill",
    reason: "General Surgery"
}

// and can be used in the item object as:
let itemDetail = {
    id: "itemId",
    type: ItemType.Blood,
    quantity: 1,
    price: 1.45,
    currency: CurrencyCode.USD,
    stock_status: StockStatus.InStock,
    promo_id: "testPromoId",
    meta: bloodMetaProperties
}

Delivery Event

logDeliveryEvent is used to log the status of the delivery. It can be used to log the delivered status of the order or partial order. Details about the items in the specified delivery should be provided in the catalog.

• @param id is required to pass the deliveryId and should be a valid for the checkout in that specific delivery.
• @param order_id is required to associate the delivery event with the order. OrderId should be a valid orderId and can be tracked from the checkout.
• @param action is required to set the delivery action for the log. For the order being prepared for delivery or left the shipment center or delivered to the customer.

let deliveryProperties = {
    id: "TestDeliveryId",
    order_id: "TestOrderId",
    action: DeliveryAction.Delivered,
}

BshECom.logDeliveryEvent(deliveryProperties)

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

Schedule Delivery Event

logScheduleDeliveryEvent is used to log the status for the delivery. It can be used to log the delivered status of the order or a partial order. Details about the items in the specific delivery should be provided in the catalog.

• @param order_id is required to associate the delivery event with the order. OrderId should be a valid orderId and can be tracked from the checkout.
• @param is_urgent sUrgent is to mark the log if the delivery is scheduled to be an immediate or emergency delivery.
• @param action is required to set the delivery action for the log. For the order being prepared for delivery that if the item is being scheduled or updated in terms of delivery elements
• @param delivery_ts The timestamp in time in milliseconds format for the date and time for which the delivery is set to be scheduled

let scheduledDeliveryProperties = {
    order_id: "testOrderId",
    is_urgent: false,
    action: ScheduledDeliveryAction.Schedule,
    delivery_ts: "1665442861000"
}

BshECom.logScheduleDeliveryEvent(scheduledDeliveryProperties)

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

Schedule, // to use when delivery is scheduled for the first time
Update // to use when the already scheduled delivery is being updated

Cancel Checkout Event

logCancelCheckoutEvent is used to log the event when the order/cart is canceled.

• @param id can be used to log the orderId and cartId the event is logged for. This should be in accordance to the type provided in the log and should represent the actual element being cancelled/discarded.
• @param type is the type of checkout element being canceled, cart or order
• @param itemsList is required to provide the list of item types that are present in the order being cancelled.
• @param reason is required to define the reason for which the item is being cancelled.

let itemTypeObject1 = {
    id: "itemId1",
    type: ItemType.Drug
}

let cancelCheckoutProperties = {
    id: "testOrderID", //OR "testCartId"
    type: CancelType.Order,
    items_list: [itemTypeObject1, itemTypeObject2],
    reason: "Process too long"
}

BshECom.logCancelCheckoutEvent(cancelCheckoutProperties)

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

Cart, // to use when you are discarding a cart
Order // to use when you are canceling an already placed order.

For implementation, you can also view the demo app.

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 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!