API Reference

This page helps you to understand the types of events and how to send events to Contlo.

Analyzing events helps in understanding how users interact with an application. There are four types of events in the Contlo SDK:

System events

These events are fired automatically by the SDK.

  • App launched: This event is fired when the app is launched from the background or killed state.
  • App installed: This event is fired when a user installs or reinstalls the app, or clears app data, and launches it for the first time.
  • App backgrounded: This event is fired when the app is sent into the background state.
  • App updated: This event is fired when a user opens the app for the first time after updating.

Send system events to Contlo

To start sending system events to Contlo, follow the steps below:

  1. Navigate to the Android directory, and open root-level build.gradle file and add the following code:

allprojects {
	repositories {
			maven {
				url 'https://nexus.contlo.com/repository/contlo-android-sdk' }
	    }
}

  1. Go to your App directory, open the module build.gradle file and add the following dependency:

dependencies {
	implementation 'com.contlo:android-core:1.0.0'
}

  1. Open the main application file that represents the start of the application and import the following Conlto packages:
import com.contlo.core.lifecycle.ContloSDKLifecycleCallbacks
import com.contlo.core.main.Contlo
  1. To listen to the system events:
    1. Initialize the SDK using init() method with the following parameters:
      1. Context: Pass the application context as this keyword.
      2. API key: Pass the API key (created from the Contlo dashboard).

        📘

        Use the same API key that is used to initialize the React Native SDK.

    2. Add the registerActivityLifecycleCallbacks() method to listen to the system events.
import android.app.Application
import com.contlo.androidsdk.main.Contlo
import com.contlo.androidsdk.lifecycle.ContloSDKLifecycleCallbacks // import lifcycle callbacks

class ContloApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Contlo.init(this, "<API_KEY>")
        registerActivityLifecycleCallbacks(ContloSDKLifecycleCallbacks(applicationContext))
    }
}


Message events

These events are related to push notifications that are automatically sent to Contlo.

  • Mobile push received: This event is fired when the SDK receives the notification payload from Contlo.
  • Mobile push clicked: This event is fired when the user clicks the notification.
  • Mobile push dismissed - This event is fired when the user dismisses the notification or clicks the Clear all notifications button.

Custom Events

These events are your user journey events that you would track across the user journey. You can send these custom events to Contlo using the sendEvent() method. Refer to the code below:

Contlo.sendEvent("<event-name>")

You can send additional parameters in the sendEvent() method. Refer to the examples below:

Example 1: You can send events with custom properties. Refer to the code given below:

Contlo.sendEvent({
            "event": eventName,
            "properties": {
               "extraKey": "extraValue"
            }
        })

Example 2: You can also send profile properties to Contlo:

Contlo.sendEvent({
            "event": eventName,
            "properties": {
              "extraKey": "extraValue"
            },
            "profile_properties": {
              "firstName": "Contlo"
            }

        })

Charged event

This is a special event that captures details of customer purchases, including items, categories, transaction amount, transaction ID, and information about the respective user. Recording a purchase against a user marks them as a customer in Contlo. This enables you to compare your funnel reports between customers and non-customers.

Properties

The charged event has the following properties:

ParameterTypeDescription
event_idstringUsed to map the event.
transacation_valuestringThe total transaction amount attributed to the revenue.
variant_idstringThe corresponding variant(s) ID for which the transaction is taking place.
event_typestringType of event (Charged)
currencystringCurrency code of variant prices. Follows ISO 4217:2015 format.
transaction_idstringUnique identifier of the transaction.
emailstringEmail ID of the customer
phone numberstringPhone number of the customer.
product_idstringThe corresponding product (s) ID for which the transaction is taking place.
timeLongEpoch time in milliseconds.

Sample JSON:

{
   "event_id":95962,
   "event":"order_placed",
   "email":"[email protected]",
   "phone_number":"+911234567890",
   "properties":{
      "event_type":"charged",
      "transaction_value":6600,
      "transaction_id":"pay_N0km1m5ZSVp5kd",
      "order_id":"12344abc",
      "currency":"inr",
      "total_discount":123.34,
      "shipping_price":100.00,
      "subtotal_price":200,
      "total_tax":1234.00,
      "product_ids":[
         "20998",
         "18318",
         "18312"
      ],
      "collection_ids":[
         
      ],
      "variant_ids":[
         "20998INR",
         "18318INR",
         "18312INR"
      ],
      "product_prices":[
         100,
         200,
         300
      ],
      "product_quantities":[
         2,
         1,
         1
      ]
   },
   "device_event_time":1669899600000
}

Please note the following when sending a charge event:

  • Please send 0 if there is no discount/shipping price etc. and do not send null.
  • The total price is before adding the tax and discount.
  • Ensure to keep the products updated on Contlo to avoid any mismatch of product ID mapping.
  • No. of items in the arrays for product prices and quantity should be equal.