Android SDK

Detailed technical documentation on the Lemnisk Android SDK to send data from your website to your destinations via Lemnisk.

This document acts as a reference for the Android SDK documentation. Please ensure that you have an agreed-upon Event Tracking Plan from your Lemnisk Customer Success Point of Contact in conjunction with this document for the correct and complete implementation.

What is the Android SDK?

The Lemnisk Android SDK allows you to track user event data from your Android app. The SDK can be easily imported into any Android app. Based on the data it receives from the user activity, it sends real-time personalized push notifications to the users about the services and products that our clients provide.

Version Details

Lemnisk's latest Android SDK version is 1.1.52, and supports Android 5 and above.

Installing and using the Lemnisk Android SDK

Prerequisites

• Lemnisk WriteKey

• Lemnisk Server URL

Step 1: Getting the SDK

In your build.gradle file, add the following dependency:

implementation 'co.lemnisk.app.android:AndroidSDK:1.1.52'

Step 2: Add Google Play Services to your app

Apps in the Google Play Store use the Google Advertising ID to uniquely identify devices. Therefore, to allow the Lemnisk SDK to use the Google Advertising ID, you need to integrate the Google Play Services.

Open your app/build.gradle and add the below dependency under dependencies:

    implementation 'com.google.android.gms:play-services-base:17.6.0'
    implementation 'com.google.android.gms:play-services-ads-identifier:16.0.0'

Step 3: Some Additional dependencies

Open your app/build.gradle and add the below dependency under dependencies:

//No need to add below two firebase dependencies if lemnisk push notifications are not required.
implementation platform('com.google.firebase:firebase-bom:28.2.0')
implementation 'com.google.firebase:firebase-messaging'

implementation group: 'joda-time', name: 'joda-time', version: '2.10.10'
implementation "androidx.lifecycle:lifecycle-extensions:2.2.0"
implementation 'com.google.code.gson:gson:2.3.1'
implementation 'org.apache.commons:commons-text:1.9'
implementation "androidx.work:work-runtime:2.7.1"

Manifest File Changes

In the Package Explorer, open the AndroidManifest.xml file and make the following changes:

<meta-data 
  android:name="Lemnisk.WRITE_KEY" 
  android:value="{WRITE_KEY}" />

<meta-data 
  android:name="Lemnisk.SERVER_URL" 
  android:value="{SERVER_URL}" />
  
<meta-data 
  android:name="Lemnisk.DEBUG_MODE" 
  android:value="{true/false}" />
  
<meta-data
  android:name="Lemnisk.ENABLE_PUSH" 
  android:value="{true/false}" />
  
<meta-data
  android:name="Lemnisk.ENABLE_ANALYTICS" 
  android:value="{true/false}" />
  
<!--  if you're not using App Push notifications capability you can Disable this.
 Disabling this otherwise may impact the push notifications deliverability. -->
<meta-data
  android:name="Lemnisk.ENABLE_PULL_NOTIFICATIONS"
  android:value="true" />

Replace WRITE_KEY and SERVER_URL with original values that you receive from our Lemnisk Account Manager.

DEBUG_MODE is used to show Lemnisk debug/error/info logs. Set this to false when going to production.

Step 3: Initialize the Android App SDK

Import the library for the classes you desire to use LemniskHelper library:

import co.lemnisk.app.android.LemniskHelper;

Add the below code to the onCreate method in your Application class:

@Override 
protected void onCreate(Bundle savedInstanceState) 
{
  //your code 
  //Initialize with lemnisk write key
  LemniskHelper.getInstance(getApplicationContext()).init(getApplication()); 
  //your code 
} 

Step 4: Add Proguard Rules

If your application uses Proguard, add following rule in proguard-rules.pro of your application.

-keep class androidx.lifecycle.DefaultLifecycleObserver

Android SDK Methods

1.identify() method

The identify() records user-specific information. In the Android SDK, we capture deviceID and use that as anonymousID to identify the user.

Usage:

lemniskClient.identify(userId, traits, otherIds);

Example:

LemniskHelper lemniskClient = LemniskHelper.getInstance(getApplicationContext());
AttributeBuilder traits = new AttributeBuilder.Builder()
.addAttribute("key1", "value1")
.addAttribute("key2", "value2")
.addAttribute("key3", "value3")
.build();

AttributeBuilder otherIds = new AttributeBuilder.Builder()
.addAttribute("otherId", "otherId_value")
.build();

lemniskClient.identify("user_id", traits, otherIds);

2.screen() method

The screen() method is used to record the screen details whenever a user sees any screen on the application.

Usage:

lemniskClient.screen(screenName, properties, otherIds);

Example:

LemniskHelper lemniskClient = LemniskHelper.getInstance(getApplicationContext());

AttributeBuilder properties = new AttributeBuilder.Builder()
.addAttribute("key1", "value1")
.addAttribute("key2", "value2")
.addAttribute("key3", "value3")
.build();

AttributeBuilder otherIds = new AttributeBuilder.Builder()
.addAttribute("otherId", "otherId_value")
.build();

lemniskClient.screen("MainActivity", properties, otherIds);

3.Track() method

Every action of the user can be tracked through the track method. Each of these activity is called an event.

Usage:

lemniskClient.track(name, properties, otherIds);

Example:

LemniskHelper lemniskClient = LemniskHelper.getInstance(getApplicationContext());

AttributeBuilder properties = new AttributeBuilder.Builder()
.addAttribute("product_id", "product_001")
.build();

AttributeBuilder otherIds = new AttributeBuilder.Builder()
.addAttribute("otherId", "otherId_value")
.build();

lemniskClient.track("Product Added", properties, otherIds);

App Events

Event Name	Description	Manual Firing
Application Installed	This event is automatically fired when the user installs an application.	NO
Application Opened	This event is automatically fired when the user opens an application.	NO
Application Updated	This event is automatically fired when the application gets updated.	NO
Application Backgrounded	This event is automatically fired when a user backgrounds the application.	NO
Application Uninstalled	This event should be sent when a user uninstalls the application.	NO
Application Session Started	This event is automatically fired when a user spends over 10 seconds on the app.	NO
Application Session Concluded	This event is automatically fired when a user is inactive for 20 minutes on the app.	NO
Application Crashed	This event should be sent when your application crashes.	YES

SDK Methods

trackAppEventCrashed() method

The trackAppEventCrashed() method is used to send crash report data whenever the application crashes.

Usage

lemniskClient.trackAppEventCrashed(crashReport)

Example

LemniskHelper lemniskClient = LemniskHelper.getInstance(getApplicationContext());

String crashReport = "Exception:java.lang.RuntimeException in SampleActivity";

lemniskClient.trackAppEventCrashed(crashReport);

Push Notifications

Lemnisk clients that are running Android app push notifications are requested to provide the required FCM project credentials, to assist in migration to FCM HTTP v1 API by end of May 2024.

This is explained here.

Lemnisk sends push notifications to Android devices using Firebase Cloud Messaging.

Add Firebase SDK

• Lemnisk account manager will provide google-services.json. This google-services.json needs to be placed at root level in the app module.

• Gradle changes

Project-level build.gradle (/build.gradle):

buildscript { 
    dependencies { 
        // Add this line classpath 
        'com.google.gms:google-services:4.3.3' 
    } 
}

App-level build.gradle (<project>/<app-module>/build.gradle):

dependencies { 
    // Add this line compile 
    'com.google.firebase:firebase-core:17.4.2' 
} ...
 
// Add to the bottom of the fileapply plugin: 
'com.google.gms.google-services'

Manifest Changes

In the Package Explorer open the AndroidManifest.xml of your Android project and make the following changes:

Add the following meta-tags

<meta-data 
    android:name="Lemnisk.NOTIFICATION_ICON" 
    android:resource="{NOTIFICATION_ICON}" />
<meta-data 
    android:name="Lemnisk.NOTIFICATION_ICON_SMALL" 
    android:resource="{NOTIFICATION_ICON_SMALL}" />

• NOTIFICATION_ICON is displayed at the left of a notification

• NOTIFICATION_ICON_SMALL is displayed in the notification bar. This should be white icon on a transparent background

Refer to Android Notifications and Style Icons for more details.

Add the following services for receiving the FCM token and messages.

<service
	android:name="co.lemnisk.app.android.push.LemFirebaseMessagingService">
        <intent-filter>
		<action android:name="com.google.firebase.MESSAGING_EVENT"/>
	</intent-filter>
</service>

<service
	android:name="co.lemnisk.app.android.push.LemFirebaseInstanceIdService">
	<intent-filter>
		<action android:name="com.google.firebase.INSTANCE_ID_EVENT"/>
	</intent-filter>
</service>

Mandatory intent service for doing the heavy lifting

<service 
   android:name="co.lemnisk.app.android.push.LemIntentService"
   android:exported="false"
>
</service>

To support app-based deep link from Android 11 and onwards, following permission needs to be added to AndroidManifest.xml of the app.

AndroidManifest.xml

<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>

OPT-IN for Push Notifications

If you are targeting Api level >= 33 then you must ask user permission for push notifications at runtime. For that you can call the below function at appropriate place in your app.

We recommend calling this method on every app launch

LemniskHelper lemniskClient = LemniskHelper.getInstance(getApplicationContext());

//you need to provide the Activity in which you want to ask for permission.
lemniskClient.registerForPushNotifications(MainActivity.this, "title", "message");

//if you don't provide the title and message default values will be given.
lemniskClient.registerForPushNotifications(MainActivity.this);

FCM Auth 2.0 Credentials

FCM deprecated legacy APIs for HTTP and requires OAuth 2.0 authorization for sending push notifications. In order to generate Auth2.0 access token we need following credentials from the clients FCM project.

1. FCM Project Id

This can be retrieved from Project settings -> General -> Project ID

2. Generate Private Key

To authenticate a service account and authorise it to access Firebase services, you must generate a private key file in JSON format.

To generate a private key file for your service account:

1. In the Firebase console, open Settings > Service Accounts.

2. Click Generate New Private Key, then confirm by clicking Generate Key.

3. Securely store the JSON file containing the key.

Please share the above two credentials with lemnisk.

Running Marketing Channels on WebView

If you are using WebView in your Android app and want to run marketing channels such as On-site Notification, Banner Personalization and Notification Bot, you need to call the below method in your app:

LemniskHelper.getInstance(this).setDeviceIdToWebview(webView,domain);

Parameter	Data Type	Description
​webView	​WebView instance	​Webview instance you want to use
​domain	String	Domain of the website where you want to run the marketing channels

Example:

LemniskHelper.getInstance(this).setDeviceIdToWebview(myWebsiteWebView,"https://xyz.com");

FAQs

Q1. What is the Android version required to set up the Lemnisk Android App SDK?

Minimum Android 5.0 (minAppSDKVersion = API level 21)

Q2. Can Lemnisk Android App SDK be used with Kotlin?

Yes, our Android App SDK can be used with Kotlin as well.

Q3. Can I use the library with Maven?

Yes.

Q4. I need to check the logs. Where should I look?

We can filter with the string "Lemnisk" among the application logs.

Q5. How does the SDK handle different client/server errors?

It prints error messages for both client/server in the logs, but nothing will be visible to the end-user.

Q6. Which all Android permissions are required for the SDK to run smoothly?

android.permission.INTERNET

Q7. Does the SDK also support tracking events from wearables and TV that run on Android?

SDK is not yet tested for wearables. We have it in our Product Roadmap.

Contact Us

If you have an unanswered question or to know more about the Lemnisk Android SDK you can contact us.