Getting started with the Android SDK

setup Converted. In SDK so you can start to Know what your customers do before and after visiting your offline stores. Leverage data and learn what their behavior looks like.

Installation

The Android SDK is compatible with apps supporting Android API level 17 and above. Apps can be written using Kotlin or Java 8.

Getting started with the Android SDK requires five steps:

  1. Adding the dependency to your Gradle files.

  2. Initialize the SDK with your secret key.

  3. Authenticate user by Sending user data for segmentation.

  4. Initialize the Notifier and configure it.

  5. Start location tracking.

  6. Track user events and actions through you app.

Step 1: Adding the dependency

Once you acquire a username and password from Converted.In, you can access the repository that has the SDK. Add the following snippet to your root build.gradle file and you will be able to resolve the library.

allprojects {
repositories {
maven {url "http://jfrog.converted.in:80/artifactory/new-sdk/"}
}
}

Then, in the build.gradle file for the project for which you would like to include the SDK, add:

dependencies {
implementation 'in.converted:convertedinsdk:1.0.0'
}

Step 2: Initialize the SDK

Use the following code to initialize the SDK in your Application's onCreate method.

you can optionally set the log level toDEBUGto receive more detailed logs while you're developing and persist them on disk.

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.init {
application = this@App
secretKey = "YOUR_SECRET_KEY"
apiKey= "YOUR_CLIENT_ID"
debuggable = true
}
JAVA
ConvertedInSdk.init(
this,
"YOUR_CLIENT_ID",
"YOUR_SECRET_KEY",
false // DEBUG Level
);

Step 3: Initialize and Configure the Notifier

Your app should and must implement FCM In order for the Notifier to work properly. If your app is not implementing FCM please click here to get to the FCM setup guide.

Please follow the below steps to get the Notifier up and running: 1. Add the notification configuration to your Application's onCreate method using the example below.

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.notifier.configNotification {
smallIcon = R.drawable.ic_notification
color = R.color.colorAccent
visitActivityTarget = MainActivity::class.java
}
JAVA
ConvertedInNotifierConfig config = new ConvertedInNotifierConfig();
// pass the notification icon
config.setSmallIcon(R.mipmap.ic_launcher);
// pass your app's main activity
config.setVisitActivityTarget(MainActivity.class);
ConvertedInNotifierConfig.notifier().configNotification(config);

2. setup updating the user's FCM token whenever a new token is generated for the user you need to pass it to the SDK After you've obtained it. add the following line to your onNewToken implementation:

KOTLIN
JAVA
KOTLIN
override fun onNewToken(newToken: String) {
super.onNewToken(newToken)
ConvertedInSdk.auth.updateUserFcmToken(newToken)
}
JAVA
@Override
public void onNewToken(String token) {
ConvertedInSdk.auth().updateUserFcmToken(token);
}

3. setup handling when the user receives a notification whenever the user receives a new message you need to pass the message data to the SDK to handle certain action passed on the message's type. add the following line to your onMessageReceived implementation:

KOTLIN
JAVA
KOTLIN
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
ConvertedInSdk.notifier.onMessageReceived(remoteMessage.data)
}
JAVA
@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
ConvertedInSdk.notifier().onMessageReceived(remoteMessage.getData());
}

Step 4: Sending the user data

In order to create a user profile for our segmentation you need to pass the user's data to the SDK. Use the following snippet and add it in your MainActivity'sonCreate method to send the user data.

We check for you if the user data was sent before or not, so no worries about this

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.auth.setUserData {
id = "user_id"
gender = UserGender.MALE
countryCode = "20"
email = "example@email.com"
birthday = "1/1/1990"
name = "John Doe"
fcmToken = token
}
JAVA
//create a new user instance
ConvertedInUser user = new ConvertedInUser();
// set the user related data
user.setId("user_id");
user.setGender(UserGender.FEMALE);
user.setCountryCode("20");
user.setEmail("example@email.com");
user.setBirthday("1/1/1990");
user.setName("John Doe");
user.setFcmToken(token);
// pass the created user to the SDK
ConvertedInSdk.auth().setUserData(user);

Step 5: Setting up Location Awareness

Once the SDK is initialized and configured you need to start the location tracking by calling the following the line in your MainActivity'sonCreate method.

We handle asking the user for the location permission.

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.locationTracker.start(this)
JAVA
ConvertedInSdk.getLocationTracker().start(this);

In case that you want to handle asking the user for the location permission you will need to override the onRequestPermissionsResult method in the activity where you ask your user for the location permission and call the following method passing the required params.

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.locationTracker
.onRequestPermissionsResult(requestCode, permissions, grantResults)
JAVA
ConvertedInSdk.getLocationTracker()
.onRequestPermissionsResult(requestCode, permissions, grantResults);

for stopping the tracking simply call the following line:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.locationTracker.stop
JAVA
ConvertedInSdk.getLocationTracker().stop();

Step 6: Track user events

We have around 14 events that need to be implemented to be logged across the user's life cycle within the app. Here are the events

  • App launch.

  • Sign in.

  • Sign up.

  • Sign out.

  • Basket view.

  • View item.

  • Add item to basket.

  • Remove an item from basket.

  • Transaction confirmation.

  • Search.

  • Promo redeemed.

  • Feedback.

You need to log the user events across the app by adding each event as follows:

App launch

Implement this event in your MainActivity'sonCreate and pass the current timestamp to log whenever the user opens the app as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.appLaunch()
JAVA
ConvertedInSdk.events().appLaunch();

Sign in

Implement this event after the user is successfully signed in as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.signIn()
JAVA
ConvertedInSdk.events().signIn();

Sign up

Implement this event after the registration or signing in for the first time as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.signUp()
JAVA
ConvertedInSdk.events().signUp();

Sign out

Implement this event after the user signs out as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.signOut()
JAVA
ConvertedInSdk.events().signOut();

Basket view

Implement this event whenever the user views the basket and pass the basket id as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.viewBasket(12)
JAVA
ConvertedInSdk.events().viewBasket(12);

View item

Implement this event whenever the user views an item that can be added to the basket and pass the item id as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.viewItem(12)
JAVA
ConvertedInSdk.events().viewItem(12);

Add item to basket

Implement this event whenever the user adds an item to the basket and pass the basket id and the item id as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.addItemToCart {
itemId = 12
basketId = 30
}
JAVA
ConvertedInSdk.events().addItemToCart(12,30);

Remove item from basket

Implement this event whenever the user views the basket and pass the basket id as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.removeItemFromCart{
itemId = 12
basketId = 30
}
JAVA
ConvertedInSdk.events().removeItemFromCart(12,30);

Transaction confirmation

Implement this event after the user successfully completes a payment and pass the order id and the basket id as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.transactionConfirmation {
basketId = 12
orderId = 30
}
JAVA
ConvertedInSdk.events().transactionConfirmation(12, 30);

Implement this event whenever the user searches for an item and pass the search query as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.search("Running Shoes")
JAVA
ConvertedInSdk.events().search("Running Shoes");

Promo redemption

Implement this event whenever the user redeems a promo code successfully and pass the promo string and it's value as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.promoRedeemed {
amount = 200.0
promoCode = "COVID19"
}
JAVA
ConvertedInSdk.events().promoRedeemed("COVID19", 200.0);

Order feedback

If you have implemented a feedback activity or you take the user's feedback in any form just log it by passing the order id and the feedback questions and answers as follows:

KOTLIN
JAVA
KOTLIN
ConvertedInSdk.events.orderFeedback {
order_id = 2
feedback_list = listOf(
Feedback("Quality of the product", 1.0),
Feedback("Quality of sales team", "needs to be better")
)
note = "this is a note"
}
JAVA
ConvertedInSdk.events().orderFeedback(2, new ArrayList<Feedback>(), "");