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 your 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/android/"}
    }
}

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.

ConvertedInSdk.init {
    application = this@App
    secretKey = "YOUR_SECRET_KEY"
    apiKey= "YOUR_CLIENT_ID"
    debuggable = true
}

ConvertedInSdk.init(
    this,
    "YOUR_CLIENT_ID",
    "YOUR_SECRET_KEY",
    false // DEBUG Level
);

Step 3: Initialize and Configure the Notifier

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.

ConvertedInSdk.notifier.configNotification {
    smallIcon = R.drawable.ic_notification
    color = R.color.colorAccent
    visitActivityTarget = MainActivity::class.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:

override fun onNewToken(newToken: String) {
    super.onNewToken(newToken)
    ConvertedInSdk.auth.updateUserFcmToken(newToken)
  }

@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 actions passed on the message's type. add the following line to your onMessageReceived implementation:

override fun onMessageReceived(remoteMessage: RemoteMessage) {
    super.onMessageReceived(remoteMessage)
    ConvertedInSdk.notifier.onMessageReceived(remoteMessage.data)
}

@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.

ConvertedInSdk.auth.setUserData {
    id = "user_id"
    gender = UserGender.MALE
    countryCode = "20"
    email = "example@email.com"
    birthday = "1/1/1990"
    name = "John Doe"
    fcmToken = token
}

//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.

ConvertedInSdk.locationTracker.start(this)

ConvertedInSdk.getLocationTracker().start(this);

In case 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.

ConvertedInSdk.locationTracker
        .onRequestPermissionsResult(requestCode, permissions, grantResults)

ConvertedInSdk.getLocationTracker()
      .onRequestPermissionsResult(requestCode, permissions, grantResults);

for stopping the tracking simply call the following line:

ConvertedInSdk.locationTracker.stop

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:

ConvertedInSdk.events.appLaunch()

ConvertedInSdk.events().appLaunch();

Sign in

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

ConvertedInSdk.events.signIn()

ConvertedInSdk.events().signIn();

Sign up

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

ConvertedInSdk.events.signUp()

ConvertedInSdk.events().signUp();

Sign out

Implement this event after the user signs out as follows:

ConvertedInSdk.events.signOut()

ConvertedInSdk.events().signOut();

Basket view

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

ConvertedInSdk.events.viewBasket(12)

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:

ConvertedInSdk.events.viewItem(12)

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:

ConvertedInSdk.events.addItemToCart {
      itemId = 12
      basketId = 30
    }

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:

ConvertedInSdk.events.removeItemFromCart{
      itemId = 12
      basketId = 30
    }

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:

ConvertedInSdk.events.transactionConfirmation {
      basketId = 12
      orderId = 30
    }

ConvertedInSdk.events().transactionConfirmation(12, 30);

Search

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

ConvertedInSdk.events.search("Running Shoes")

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:

ConvertedInSdk.events.promoRedeemed {
      amount = 200.0
      promoCode = "COVID19"
    }

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:

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"
    }

ConvertedInSdk.events().orderFeedback(2, new ArrayList<Feedback>(), "");