Benshi React Native (Android) SDK Setup - Payments

Benshi Android SDK Payments 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 payments 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-payments": "<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 payments 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-payments

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-payments')

}

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 payments module:

| Event Name | Calling in SDK | Description | | ---------- | --------------- | ---------------------------------------------------------------- | | Deferred Payment | EventType.deferred_payments | Track user payment status when they undergo processing or processed. | | Payment Method Event | EventType.payment_method | Track user payment status when the payment is selected. |

To log payments events you need to import BshPayments main class and contents to support different actions:

import BshPayments from '@benshi.ai/react-native-bsh-payments';

Here BsPayments is the main class for all the payments-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. BsPayments 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:

Deferred Payment Event

logDeferredPaymentEvent is to log events for payments when they undergo processing and processed completed or canceled. This log is for use cases where we have Buy Now and Pay Later which means that customers can buy the items now and pay the amount on a later date.

• @param id is required to set the id for the payment in the log, Id should be in string and must be per the catalog provided.
• @param order_id is required to set the order id the payment is associated to.
• @param action is used to specify the action performed on the payments screen, there can be multiple types of actions that can include init payment process, cancel payment processing, or upload the receipt to a bank deposit. By default, SDK provides an enum class to use as PaymentAction.
• @param account_balance is required to log the current balance of the user. Amount format should be per the currency selected.
• @param payment_amount is required to log the total price of the payment being logged. Amount format should be per the currency selected.
• @param currency is required to log the currency for the payment logged. Currency should be in ISO 4217 format. For ease, SDK provides the enums to log the currency so that it would be easy to log. You can also use the string function to provide the currency.
• @param is_successful is required to set the value if the payment was successful or not.

let deferredPaymentProperties = {
  id: "testPaymentId",
  order_id: "testOrderId",
  action: DeferredPaymentType.PaymentProcessed,
  type: PaymentMethod.BankTransfer,
  account_balance: 88,
  payment_amount: 33,
  currency: CurrencyCode.USD,
  is_successful: true
}

BshPayments.logDeferredPaymentEvent(deferredPaymentProperties)

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

PaymentProcessed // for logging if the payment is processed

For ease, SDK provides the enums to log the currency using enum CurrencyCode to ensure ISO 4217 is followed. You can also use the string function to provide the currency.

Payment Method Event

logPaymentMethodEvent is to log events for payments. Which method of the payment is selected for the order.

• @param orderId is required to set the id for the order in log, Id should be in string and must be in accordance to the catalog provided.
• @param type is required to set the type of the payment is being selected. By default SDK provides an enum class to use as PaymentAction.
• @param payment_amount is required to log the total price of the payment being logged. Amount format should be per the currency selected.
• @param currency s required to log the currency for the payment logged. Currency should be in ISO 4217 format. For ease, SDK provides the enums to log the currency so that it would be easy to log. You can also use the string function to provide the currency.

let paymentMethodProperties = {
    /**
     * this `order_id` will map with the IDs
     * within both `Checkout` and `Delivery` events
     */
    order_id: "testOrderId",
    type: PaymentMethod.BankTransfer,
    payment_amount: 1400,
    currency: CurrencyCode.USD
}

BshPayments.logPaymentMethodEvent(deferredPaymentProperties)

PaymentMethod is required to set the method type selected for the payment event. SDK provides the enum class PaymentMethod to support available log types.

BankTransfer // for payments when it is a direct bank transfer
Cheque  // for payments when it is cheque deposit
CashOnDelivery // for payments when it is cash on delivery
Credit // for payments when it is purchase order on credit
Pos // for payments when it is point of sale purchase
BankCard // for payments made via bank cards: debit or credit card
Other // for payments made via any other payment method not listed above.

For ease, SDK provides the enums to log the currency using enum CurrencyCode to ensure ISO 4217 is followed. You can also use the string function to provide the currency.

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!