sdk

Meiro SDK is an Android library that provides a simple way to interact with Meiro Data Platform. It is written in Kotlin but is usable from Java projects as well.

Installation

Define a dependency in your build.gradle file.

implementation("io.meiro:sdk:x.y.z")

⚠️ Note: This SDK uses desugaring to use Java 8+ types on older Android versions. This requires your application to specify desugaring as well. Check official documentation how to integrate it.

Getting Started

To use the SDK it must first be initialized

MeiroSdk.init(
    context = applicationContext,
    configuration = Configuration(
        endpoint = "https://my.meiro.me.endpoint/",
        appId = getResources().getString(R.string.google_app_id),
    )
)

this call must be performed only once, usually in the Application.onCreate class.

The Context instance is stored in the SDK. To avoid memory leaks, never pass any Activity or other instances than Application instance to the SDK.

Configuration

Configuration object is used to configure the SDK. It has the following properties:

data class Configuration(
    // Meiro Data Platform endpoint
    val endpoint: String,
    // application id. If you are using Firebase, you should use `R.string.google_app_id`
    val appId: String,
    // if enabled, includes additional logs. Should be disabled in production
    val debugMode: Boolean = false,
    // push notifications configuration
    val pushNotifications: PushNotificationsConfiguration = PushNotificationsConfiguration(),
    // if enabled, automatic tracking of events will be performed
    val automaticTrackingEnabled: Boolean = true,
    // language of the application. Used if you want to target users by language
    val language: String? = null,
    // Firebase project id. If you are using Firebase, you should use `R.string.project_id`
    val firebaseProjectId: String? = null,
)

data class PushNotificationsConfiguration(
    // Whether push notifications handling is enabled or not
    val pushEnabled: Boolean = true,
    // Accent color of push notification icon and buttons. A color value, 
    // not resource id, is expected here, e.g. context.resources.getColor(R.color.something)
    var accentColor: Int? = null,
    // Channel name for push notifications. Only for API level 26+.
    var channelName: String = "Meiro",
    // Channel description for push notifications. Only for API level 26+.
    var channelDescription: String = "Notifications",
    // Channel ID for push notifications. Only for API level 26+.
    var channelId: String = "meiro_notifications",
    // Icon to be showed in push notifications. A drawable resource id expected.
    @DrawableRes
    var pushIconResId: Int? = null,
)

Automatic Events Tracking

If Configuration.automaticTrackingEnabled SDK performs automatic tracking of the following events:

• Application Foregrounded

• Application Backgrounded

• Screen views (see #screen-tracking for details)

• App installed event

Google Advertising ID tracking

If Configuration.automaticTrackingEnabled each event contains Google Advertising ID. This feature automatically adds com.google.android.gms.permission.AD_ID permission to the merged manifest. If you want to disable this feature, you can remove the permission by adding the following code to your AndroidManifest.xml:

<uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove" />

Screen Tracking

By default the SDK tracks screen open events for Activities and Fragments. If you are using compose-navigation there is built-in extension on NavController that allows you to track screen open events.

import io.meiro.sdk.autoTrackScreenViews

...
navController.autoTrackScreenViews()

If you don't use any of the before mentioned navigation libraries, you can manually track screen open events:

MeiroSdk.trackScreenView(name = "screen_name", properties = mapOf("product_id" to "1"))

Push Messaging

Meiro platform supports sending push notifications to users. This SDK handles push notifications displaying and tracking.

If your application does not use Firebase Cloud Messaging, the SDK will automatically register the FirebaseMessagingService and will handle displaying of the push notifications.

If you are already using Firebase Cloud Messaging, you need to perform the following:

• Pass the FCM token to the SDK by calling MeiroEvents.setFcmToken(token). This should happen in onNewToken method of subclass of FirebaseMessagingService.

• Override onMessageReceived method of FirebaseMessagingService and check whether the received message is Meiro message and then pass it to the SDK to perform the displaying. The code may look something like this

 override fun onMessageReceived(message: RemoteMessage) {
    super.onMessageReceived(message)
    if (MeiroNotifications.isMeiroMessage(message)) {
        MeiroNotifications.show(
            context = this,
            message = message
        )
    } else {
        ...
    }
}

The SDK does not handle requesting for the android.Manifest.permission.POST_NOTIFICATION permission for Android 33+. You need to request this permission for the SDK to be able to display push notifications.

Clicking the push notification may result in three scenarios based on a defined action property:

• app - default launcher activity will be opened

• browser - url will be opened in the browser

• deeplink - deeplink will be opened. In this case the application need to write a logic to register and handle the deeplink

In all three scenarios all of the properties from the data object of the push notification will be passed to the opened activity. In a case of nested objects the structure is represented as a JSON string.

Existing apps with Firebase Cloud Messaging

If you are already using Firebase Cloud Messaging in your app, you need to pass the FCM token to the SDK after the app start. This can be done by calling

FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
  MeiroSdk.setFcmToken(token)
}

eg. in Application.onCreate method.

Audience API

The SDK provides a simple way to interact with Meiro Data Platform Audience API. By calling the MeiroEvents.audience method the MeiroAudience instance is returned which contains wbs method encapsulating the Audience WBS API.

fun wbs(
    instance: String,
    parameters: Map<String, String> = emptyMap(),
    segment: Int? = null,
    callback: ResultCallback
)

This method accepts mandatory instance argument representing your instance name in a CDP. You can pass optional parameters and the segment attributes to the request. The result is received through a callback property.

In onSuccess method you will receive a MeiroAudienceResult object containing the parsed returned_attributes and data properties of a response JSON. Type of these properties is JSONObject so it allows dynamic returned types.

In onError you may receive any exception that occurred during the request. There is predefined MeiroAudienceError exception informing about known error such as 404 - Customer not found.

Logging

MeiroSdk.init method accepts an optional logger parameter. By default it uses Android Log class with MeiroSDK tag. If you want to use a custom logger, you can implement MeiroLogger interface and pass your instance to the init method.

Offline support

All of the events are tracked in real time. In a case of missing internet connection, events are stored in a queue for 24h. Once the device is connected to the internet, events are automatically sent to the server.