Android

Overview

This client side android SDK contains helpful methods that can be used to track user properties, android push token and events from the frontend clients. With the help of this SDK, you will be able to trigger Communication directly from your app and render push notifications on android devices.

Before understanding how to track all user and event based information from frontend SDK, let's first understand

Installation

Step 1. Add the mavenCentral() repository to your build file.

allprojects {
        repositories {
            ...
            mavenCentral()
        }
    }

Step 2. Add the dependency

dependencies {
            implementation("com.suprsend:native:0.1.7")
    }

Initialization

To integrate SuprSend in your Android app, you will need to initialize the suprsend sdk in your application class.

class MyApplication : Application() {

    override fun onCreate() {
        SSApi.init(this,"APIKey", "APISecret")
        super.onCreate()
    }
}

📘

Note

SSApi.init(this,"APIKey", "APISecret") should be called before super.onCreate() of Application class

For initializing SDK, you need workspace key and workspace secret. You will get both the tokens from client dashboard. For more details, check the documentation on 'Workspaces'.

val ssApi = SSApi.getInstance()

User Identification

This section deals with methods that are specific to setting user identification - which is essential for sending and rendering android push notifications.

1. Identify

This method is used to identify users uniquely across devices and platforms using unique identifiers like user id or email, phone number, etc. which are unique to your system. Call this method as soon as you know the identity of user, that is after login authentication. If you don't call this method, user will be identified using distinct_id (uuid) that sdk generates internally.

When you call this method, we internally create an event called 'User Login'. You can see this event 'User Login' on SuprSend workflows event list and you can configure a workflow on it.

ssApi.identify(uniqueId)
 
//Example
ssApi.identify("291eaa13-62f5-4d52-b2dd");
ssApi.identify("[email protected]");

2. Reset

This will generates a new random distinct_id and clears all super properties. Call reset to clear data attributed to a user when that user logs out. This allows you to handle multiple users on a single device.

When you call this method, we internally create an event called 'User Logout'. You can see this event 'User Logout' on SuprSend workflows event list and you can configure a workflow on it.

ssApi.reset()

Methods to Set & Unset Communication Channels

You can send communication channel details of a user to the SuprSend SDK.
We will store the channel details in the user profile. This will allow us to send communications to a user on the channels available for that user whenever there is any communication trigger.

1. Email

a. Set Email:

This method is for setting a user email id associated with a user, which will be used to send email notifications from SuprSend. You can call this on signup, or whenever a user provides an email id.

b. Remove Email:

This method is for removing a user email id associated with a user. You can call this when a user updates his email id. You need not call this when a user unsubscribes from email notifications, as that is handled in user preferences.

ssApi.getUser().setEmail("[email protected]")
  
ssApi.getUser().unSetEmail("[email protected]")

2. SMS

a. Set mobile number for SMS

This method is for adding a mobile number which will be used to send SMS notifications to the user. You can call this on signup, or whenever a user provides a mobile number.

b. Remove mobile number for SMS

This method is for removing a phone number associated with a user. You can call this when a user updates his mobile number.

ssApi.getUser().setSms("91XXXXXXXXXX")
  
ssApi.getUser().unSetSms("91XXXXXXXXXX")

3. Whatsapp

a. Set mobile number for Whatsapp

This method is for adding a mobile number which will be used to send Whatsapp notifications to the user. You can call this on signup, or whenever a user provides a mobile number, when a user has agreed to receive Whatsapp.

b. Remove mobile number for Whatsapp

This method is for removing a phone number associated with a user. You can call this when a user updates his mobile number.

ssApi.getUser().setWhatsApp("91XXXXXXXXXX")
  
ssApi.getUser().unSetWhatsApp("91XXXXXXXXXX")

🚧

Country Code Mandatory

Make sure you are sending the country code when you are calling communication methods for SMS and Whatsapp.

4. Android Push

Refer to the next section for details.

Logging

Enable Logs

By default the logs of SuprSend SDK are disabled. We recommend you to enable the SDK logs by setting its value to VERBOSE. You can enable the logs just in debug mode while in development by below condition.

ssApi.setLogLevel(level: LogLevel)
  
if (BuildConfig.DEBUG)
  ssApi.setLogLevel(LogLevel.VERBOSE)
  
ssApi.setLogLevel(LogLevel.VERBOSE)
ssApi.setLogLevel(LogLevel.DEBUG)
ssApi.setLogLevel(LogLevel.INFO)
ssApi.setLogLevel(LogLevel.ERROR)
ssApi.setLogLevel(LogLevel.OFF)

Sending Events to SuprSend

You can also send Events from your app to SuprSend SDK, which can be used to trigger communications to a user. You can configure a workflow from SuprSend dashboard. Once a workflow is configured, whenever that event is received on the SuprSend SDK, the associated workflow will be triggered.

Below are the methods associated with sending events:

1. Track Event

This method is used to track an event

ssApi.track(eventName: String) //for single event
  
ssApi.track(eventName: String, properties: JSONObject) //for event with properties
  
//Sample to track an event
ssApi.track(eventName = "Home Screen Viewed")

//Sample to track an event with multiple properties
ssApi.track(
            eventName = "product_viewed",
            properties = JSONObject().apply {
              put("product_id", "P1")
              put("product_name", "Car")
              put("amount", 10000)
            }
        )

❗️

Naming Guideline

When you create an Event or a property, please ensure that the Event Name or Property Name does not start with $ or ss_, as we have reserved these symbols for our internal events and property names.

2. System Events tracked by SuprSend

There are some system events tracked by SuprSend SDK by default. These are some basic events, as well as events that are necessary for tracking notifications related activity (like delivered, clicked, etc).
You are not required to do anything here.

ssApi.getUser().setSuperProperty(key: String, value: Any) //for setting single super proerty
  
ssApi.getUser().setSuperProperties(jsonObject: JSONObject) //for setting multiple super proerties
  
//Sample for setting a single super property  
ssApi.getUser().setSuperProperty("Location", "XYZ")
ssApi.getUser().setSuperProperty("Pincode", 1234567)
ssApi.getUser().setSuperProperty("Amount", 99.99)
  
//Sample for setting multiple super properties
  
ssApi.getUser().setSuperProperties(JSONObject().apply {
    put("Location","XYZ")
    put("Pincode", 1234567)
    put("Amount", 99.99")
})

Method for unsetting a super property is below:

ssApi.getUser().unSetSuperProperty(key: String) 
  
//Sample  
ssApi.getUser().unSetSuperProperty(listOf("Location","Pincode","Amount"))

By default, SuprSend tracks some super properties with each events. The details are below:

Special Events

Special events are some best use case events defined by SuprSend. You could call these events with some of their pre-defined properties.

1. Purchase Made

You can call purchase made event if user is doing a transaction on your platform. You can pass property values like product id, product name, and amount in the event.

ssApi.purchaseMade(properties: JSONObject)
ssApi.purchaseMade(JSONObject().apply {
            put("product_id", "P1")
            put("product_name", "Car")
            put("amount", 10000)
        })

Flush Events

SuprSend SDK automatically flushes events at an interval of 5 seconds, and on certain activities like app minimizing, etc.
If you wish to flush a time sensitive event to SuprSend immediately, you can use the flush method.

suprSendApi.flush()

Advanced User Properties:

You can use SuprSend SDK to set advanced user properties, which will help in creating a user profile. You can use these properties create user cohorts on SuprSend's platform with future releases.

1. Set

Set is used to set the custom user property or properties. The given name and value will be assigned to the user, overwriting an existing property with the same name if present. It can take key as first param, value as second param for setting single user property or object for setting multiple user properties.

ssApi.getUser().set(key: String, value: Any) // for single property
ssApi.getUser().set(properties: JSONObject) // for multiple properties
  
//Example for setting single property
ssApi.getUser().set("prime_member_group","super")
ssApi.getUser().set("purchased_product",true)
ssApi.getUser().set("purchased_value", 2599.50)
  
//Example for setting multiple properties
ssApi.getUser().set(JSONObject().apply {
    put("prime_member_group", "super")
    put("purchased_product", true")
    put("purchased_value", 2599.50")
    })

❗️

Naming Guidelines

When you create a key, please ensure that the Key Name does not start with $ or ss_, as we have reserved these symbols for our internal events and property names.

2. Set Once

Works just like user.set, except it will not overwrite existing property values. This is useful for properties like First login date

ssApi.getUser().setOnce(key: String, value: Any) // for single property
ssApi.getUser().setOnce(properties: JSONObject)  // for multiple properties

//Sample for single property
ssApi.getUser().setOnce("first_login_at", "01-12-2021")

//Sample for multiple properties
ssApi.getUser().setOnce(JSONObject().apply {
    put("first_login_at", "01-12-2021")
    put("first_ordered_amount", "10000")
    put("first_ordered_product_name", "Car")
})

3. Increment

Add the given amount to an existing property on the user. If the user does not already have the associated property, the amount will be added to zero. To reduce a property, provide a negative number for the value.

ssApi.getUser().increment(key: String, value: Number) // for single property
ssApi.getUser().increment(properties: JSONObject) // for multiple properties
  
//Sample for single property  
ssApi.getUser().increment("login_count", 1)
ssApi.getUser().increment("amount", 45)
ssApi.getUser().increment("total", 1.5)
  
//Sample for multiple properties
ssApi.getUser().increment(
    mapOf(
        "login_count" to 1,
        "amount" to 45,
        "total" to 1.5
    )
)

4. Append

This method will append a value to the list for a given property.

ssApi.getUser().append(key: String, value: Any) // for single property
ssApi.getUser().append(properties: JSONObject) // for multiple properties
  
//Sample for single property 
ssApi.getUser().append("choices", "ABC")
  

//Sample for multiple properties
ssApi.getUser().append(JSONObject().apply {
    put("choices", "ABC")
    put("first_ordered_at","01-12-2021")
    put("first_ordered_amount", 4500.00)
})

5. Remove

This method will remove a value from the list for a given property.

ssApi.getUser().remove(key: String, value: Any)
  
//Sample
ssApi.getUser().remove("choices", "ABC")

6. Unset

This will remove a property permanently from user properties.

ssApi.getUser().unSet(key: String) // for single property
ssApi.getUser().unSet(keys: List<String>) // for multiple properties

//Sample for single property
ssApi.getUser().unset("prime_member_group")

//Sample for multiple properties
ssApi.getUser().unSet(listOf("prime_member_group","purchased_product","purchased_value"))