Android
Complete Guide to Suprsend's Android SDK
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 beforesuper.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]");
Parameters | Type | Description |
---|---|---|
uniqueId | int, bigint, string, UUID | mandatory The id that uniquely identifies user across devices or between multiple logins. |
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
$
orss_
, 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.
Event Name | Description |
---|---|
$app_installed | $app_installed will get tracked when user launch his app for the first time. FYI cases in which it will also get called 1. When user lanches his app for first time. 2. When user uninstall the app and installs it again. 3. [Multiple device login ]When user launch app for first time on different devices. 4. When user clears the app cache and relaunches the app. |
$app_launched | $app_launched get tracked when user launches the app each time. |
$notification_delivered | $notification_delivered will get tracked when the suprsend notification payload gets received at sdk end. |
$notification_clicked | $notification_clicked will get tracked when user either click the notification body or any action button of notification. |
###3. Super Properties Super properties are data that are always sent with events data. These super properties will be send in each event after calling this method. Super properties will be stored in local storage, and will persist across invocations of app. There are some super properties that SuprSend SDK will send with each event by default. Developer can set other properties as super properties, which will go with each event.
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:
Super Property | Description | Sample Value |
---|---|---|
$app_version_string | Version of your app | 0.1 Stag Beta 31 |
$app_build_number | 2 | |
$os | Operating system of the user | android |
$manufacturer | Manufacturer of the user's device | OnePlus |
$brand | Brand of the user's device | OnePlus |
$model | Model of the user's device | GM1901 |
$deviceId | Device id | 89eead05a0150146 |
$ss_sdk_version | SuprSend SDK version | 0.1.31 |
$network | Network on which the user is | wifi |
$connected | Whether the user is connected to the network | true |
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")
})
Parameters | Type | Description |
---|---|---|
key | string | Mandatory This is property key that will be attached to user. Should not start with $ or ss_ |
value | any | Optional This will be value that will be attached to key property. |
JSONObject | object | Optional This is used in case of setting multiple user properties. |
Naming Guidelines
When you create a key, please ensure that the Key Name does not start with
$
orss_
, 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"))
Updated 5 months ago