Flutter SDK

Detailed technical documentation on the Lemnisk Flutter SDK to send data from your Flutter apps to your destinations via Lemnisk.

This document acts as a reference for the Flutter 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.

Lemnisk Flutter SDK can be used to track and send user events from your Flutter application to various destinations of your choice. These destinations can be configured in the CDP Dashboard. SDK also manages your push notifications via FCM and APNS.

Version Details

Lemnisk's latest Flutter SDK version is 1.1.0 and supports iOS 13, Android 5 and above.

Installing the Lemnisk Flutter SDK

Pre-requisites:

• Lemnisk WriteKey

• Lemnisk Server URL

Getting the SDK

Use the following command to add the Lemnisk flutter plugin to your App.

   flutter pub add lemnisk_flutter

This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get):

 dependencies:
   lemnisk_flutter: ^1.1.3

Steps for Android

Manifest File Changes

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

Add the below meta tags, replacing the placeholders with associated values given below:

<meta-data
	android:name="Lemnisk.WRITE_KEY"
	android:value="{Writekey}" />
	
<meta-data
	android:name="Lemnisk.SERVER_URL"
	android:value="{serverUrl}" />
	
<meta-data
	android:name="Lemnisk.DEBUG_MODE"
	android:value="{true/false}" /> 
	
<meta-data
 	android:name="Lemnisk.ENABLE_PUSH"
 	android:value="{true/false}" />
 
 <!-- Pull notifications: 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" />

The WriteKey and serverUrl will be provided by the Lemnisk Account Manager. DEBUG_MODEis used to show Lemnisk debug/error/info logs. Set this to false when for Production environments.

Configuring App Push 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 
        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 SDK method on every App launch

import 'package:lemnisk_flutter/flutter_wrapper_method_channel.dart';

//You can change the title and message as you need.
LemniskFlutter.registerForPushNotifications( "title", "message");

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

Steps for iOS

Integration through CocoaPods

CocoaPods is a dependency manager for Objective C & Swift projects and makes integration easier.

• If you don't have CocoaPods installed, you can do it by executing the following line in your terminal:

sudo gem install cocoapods

• If you don't have a Podfile, create a plain text file named Podfile in the Xcode project directory with the following content, making sure to set the platform and version that matches your main app, Notification Content Extension and Notification Service Extension. Add the below code in the Podfile

platform :ios, 'YOUR_TARGET_PLATFORM_VERSION'

target 'YOUR_TARGET_NAME' do  
    # Your App dependencies
end

# We will be adding following 2 extensions in the further steps given below
target 'NotificationContentExtension' do

  # Lemnisk Notification Content Extension
  pod 'Lemnisk-iOS-SDK', '3.9.6'
end

target 'NotificationServiceExtension' do

  # Lemnisk Notification Service Extension
  pod 'Lemnisk-iOS-SDK', '3.9.6'
end

Initializing the iOS SDK

• Import the Lemnisk SDK by using the following import statement in your AppDelegate or at the entry point of your App if it is iOS 15+

If the entry point is a .m file, use the following import statement.

Objective-C

#import <Lemnisk/Lemnisk.h>

Swift

import Lemnisk

If the entry point is a .mm file use the following instead

Objective-C

#import <Lemnisk/Lemnisk-Swift.h>

• In your AppDelegate or in the entry point file, please add the following code snippet in didFinishLaunchingWithOptions to initialise the Lemnisk SDK.

• Please enable Push Notifications and AppGroup capability from our Xcode Signing & Capabilities Tab and use the Same AppGroup for all the 3 targets (App, Notification Service Extension and Notification Content Extension). You can find the documentation here on how to enable AppGroup if you aren't familiar with this.

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
  {
    // Your code
    [[Lemnisk shared] setAppGroupIDWithGroupId:@"your app groupid"];  // This will be something like co.lemnisk.app.ios.bankingdemo
    [[Lemnisk shared] configureWithWriteKey:@"writeKey" serverUrl:@"xx-pl.lemnisk.co" launchOptions: launchOptions];
    // Your code
  }

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Your code
    Lemnisk.shared.setAppGroupID(groupId: "your app group id") // This will be something like co.lemnisk.app.ios.bankingdemo
    Lemnisk.shared.configure(writeKey: "<writeKey>", serverUrl: "<xx-pl.lemnisk.co>", launchOptions: launchOptions)
    // Your code
}

Note: Lemnisk account manager will provide you with the values for writeKey and serverUrl.

Register Lemnisk Notification tasks:

• You need to call below method before appLaunch sequence completes for example you can call it in didFinishLaunchingWithOptions method.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        //other code or lemnisk sdk initialization
        
        Lemnisk.shared.registerLemniskNotificationTasks()
        
        //other code or lemnisk sdk initialization
    }

• Enable remote notifications and Background fetch in Background modes capability of your main target as show below.

• Our background task identifier ("co.lemnisk.app.ios.refresh") needs to be added in info.plist as shown in below screenshot.

• This task helps in ensuring high push notifications deliverability.

• make sure to call registerForPushNotifications method only after this method is called.

• Important note: If you already have some BGApprefresh task that you registered for your app instead of registering this task please get in touch with our Customer success team.

If you want to show the Push Notifications permission authorization prompt from AppDelege itself, then you can use the following SDK API to show the same to the user. If you wish to show the otherization from your ReactJs using JavaScript then you can skip then and use the respective SDK method described in the later sections.

We recommend calling this SDK method on every App launch

if registerLemniskNotificationTasks is called then call registerForPushNotifications only after registerLemniskNotificationTasks is called.

Objective-C

[[Lemnisk shared] registerForPushNotifications];

Swift

Lemnisk.shared.registerForPushNotifications()

Please ignore any of the compilation errors at this point in time till the pod install the command is run, which we will do in later steps

If you are using multiple push providers and using SDK version >= 3.9.6 you need to follow below steps.

In your AppDelegate you need to enable swizzling for all and then only call our configure method.

And try to initialise our sdk after initialising any other sdk as we will be calling all the original methods that are swizzled so that it won't effect functionalities of other sdk's

Swift

// Your code
Lemnisk.shared.setSwizzleForAll(state: true)

//sdk intialization
Lemnisk.shared.setAppGroupID(groupId: "co.lemnisk.app.ios.bankingdemo")
Lemnisk.shared.configure(writeKey: "ABC2rj2", serverUrl: "https://xx-pl.lemnisk.co", notifcationCenterUrl: "https://xx-nc.lemnisk.co")
// Your code or any other lemnisk sdk configurations

Objective-c

// your code

[[Lemnisk shared] setSwizzleForAllWithState:YES];

//sdk intialization
[[Lemnisk shared] setAppGroupIDWithGroupId:@"your app groupid"];
[[Lemnisk shared] configureWithWriteKey:@"writeKey" serverUrl:@"xx-pl.lemnisk.co" notifcationCenterUrl:"<Notification center url>"];
// Your code or any other lemnisk sdk configurations

Rich Push Setup

From iOS 10+, we can show rich media Push Notifications with images, video, audio and a carousel. So please configure the below 2 extensions in your project if you don't have them already and configure Lemnisk SDK in them.

Notification Service Extension

We use Notification Service Extension to track the delivery of Push Notifications as well as downloading the Rich Media Push Notification attachments (image/video/audio etc.)

• Add a Notification Service Extension target to your project (File -> New -> Target -> Notification Service Extension)

Notification Service Extension Setup

• Define the name for the Notification Service Extension in the next step

Notification Service Extension Setup

Now please enable the AppGroup capability from our Xcode Signing & Capabilities Tab and use the same AppGroup for all the 3 targets (App, Notification Service Extension and Notification Content Extension). You can find the documentation here on how to enable AppGroup if you aren't familiar with this.

Now modify the NotificationService.swift to look like the following code.

Swift

import UserNotifications
import Lemnisk

class NotificationService: UNNotificationServiceExtension {
    public override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        LemniskNotificationService.shared.setAppGroupID(groupId: "your app groupid") // This will be something like co.lemnisk.app.ios.bankingdemo that you have created above
        LemniskNotificationService.shared.didReceive(request, withContentHandler: contentHandler)
    }
    
    public override func serviceExtensionTimeWillExpire() {
        LemniskNotificationService.shared.serviceExtensionTimeWillExpire()
    }
}

If you have multiple push providers you can implement NotificationService as mentioned below.

import UserNotifications
import Lemnisk

class NotificationService: UNNotificationServiceExtension {

    var bestAttemptContent: UNMutableNotificationContent?
    var isLemPush: Bool?
    
    public override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {

        self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
        self.isLemPush = false
        
        var userInfo: [String: Any]? = bestAttemptContent?.userInfo as? [String: Any]

        if Lemnisk.shared.isLemniskPush(userInfo: userInfo) {
            self.isLemPush = true
            LemniskNotificationService.shared.setAppGroupID(groupId: "your app groupid")
            LemniskNotificationService.shared.didReceive(request, withContentHandler: contentHandler)
        }
        else{
            //other push provider code
        }
    }
    
    public override func serviceExtensionTimeWillExpire() {
        if(self.isLemPush == true){
            LemniskNotificationService.shared.serviceExtensionTimeWillExpire()
        }
        else{
            //other push provider code
        }
    }
}

Notification Content Extension

This extension can be used if you want to show a carousel slider in a Push Notification.

• Add a Notification Content Extension target to your project (File -> New -> Target -> Notification Content Extension)

Notification Content Extension

• Define the name for the Notification Content Extension in the next step.

• Make sure the deployment target for notification content is set to iOS 10

• Now please enable the AppGroup capability from our Xcode Signing & Capabilities Tab and use the same AppGroup for all the 3 targets (App, Notification Service Extension and Notification Content Extension). You can find the documentation here on how to enable AppGroup if you aren't familiar with this.
• Now modify the NotificationViewController.swift to look like the following code.

import UIKit
import UserNotifications
import UserNotificationsUI
import Lemnisk

class NotificationViewController:  LemniskNotificationViewController {

    override func viewDidLoad() {
        super.viewDidLoad();
    }

    override func didReceive(_ notification: UNNotification) {
        super.setAppGroupID(groupId: "your app groupid") // This will be something like co.lemnisk.app.ios.bankingdemo that you have created above
        super.didReceive(notification)
    }
}

Now install all the Lemnisk dependencies with the following command

pod install

Note: If you are running this for the first time then you may need to update the pod repositories by running:

pod install --repo-update

• This would install the Lemnisk framework along with the required dependencies for your app extension targets.

Changes in Frameworks, Libraries, and Embedded content for Notification Service Extension( only if sdk version <= 1.0.1)

For some reason, there is an issue with Pods being installed and Xcode reading it from the embedded pod's. And so we need to embed the LemniskRichNotification manually in the extension target's Frameworks, Libraries, and Embedded content and select Do Not Embed. You can refer to the same below.

• Now select Do Not Embed

Changes in Frameworks, Libraries, and Embedded content for Notification Content Extension( only if sdk version <= 1.0.1)

For some reason, there is an issue with Pods being installed and Xcode reading it from the embedded pod's. And so we need to embed the LemnsikNotificationContent manually in the extension targets Frameworks, Libraries, and Embedded content and select Do Not Embed. You can refer to the same below.

Now select Do Not Embed

Configuring App Groups

Please follow the following procedure if you are using the Xcode Auto Sign, otherwise please scroll below to add the App Groups manually via the Apple Developer Console.

With Xcode Auto Sign

• Go to App Groups capability from the Xcode’s Singing & Capabilities for all the targets (App, NotificationServiceExtension and NotificationContentExtension) as shown in the following screenshot.

• Now search for App group and select App Groups

• Now create the required App Groups Id by inputting a value similar to your Bundle Id (need not be same as BundleId) which will have group. as the prefix

• Now finally select group id that we have just created

• Similarly, select the already created same AppGroup for the other two targets - Notification Service Extension and Notification Content Extension.

Now close and reopen your project's xc-workspace file and at this point in time, all the build errors should be resolved.

From Apple Developer Console

• Goto Identifiers tab in the Apple Developer Console and click on App Groups as shown in the below screenshot.

• Now tap + to create a new App Group

• Select App Groups on the next screen as shown below

• Now fill the Description and the Identifier (App Group name) and click Continue

• On the next screen, click Register

• Now go to Identifiers tab, click on your App Bundle identifier

• Now check on App Groups and click configure

• On the next step, select the group we have created in the previous step and click continue and then Save

• Now go to Profile tab and select your profile, if it shows invalid then click Edit and Save. Then download the file and use it in the Xcode.

• Finally in the Xcode, go to Singing & Capabilities as shown in the following screenshot

• Now search for App group and select App Groups

• Now select the App group that we have created earlier in the Apple Developer Console

• Now repeat steps 6-12 for App extension targets as well (Now go to Identifiers step above)

Info.plist Configuration

App

• Please add the Privacy - Tracking Usage Description key in your main app Info.plist as this will be used as a description while showing the Tracking description if you would want to enable the IDFA tracking.

• To enable/disable the IDFA tracking you can do so by adding the properties LemniskUseIDFA and LemniskShowIDFAPrompt as Boolean to your main app's Info.plist file.

Please find the description of above LemniskUseIDFA and LemniskShowIDFAPrompt below

• LemniskUseIDFA - Will grant IDFA usage to Lemnisk

• LemniskShowIDFAPrompt - To whether ask the user for Tracking permission or not

Notification Content Extension

1. Please update the Notification Content Extension Info.plist's UNNotificationExtensionCategory to Array and add the required categories from the following entries.

   i. carousel

2. Add the following properties under NSExtensionAttributes

   i. Add property UNNotificationExtensionDefaultContentHidden as String and set its value to YES

   ii. Add property UNNotificationExtensionUserInteractionEnabled as Boolean and set its value to true

3. Add the following property under NSExtension

   i. Add property NSExtensionPrincipalClass as String and set its value to $(PRODUCT_MODULE_NAME).NotificationViewController as it will specify not to use the default mainInterface storyboard that will be created by Xcode but use the custom view specified by NotificationViewController.

   ii. Delete the property NSExtensionMainStoryboard , as the properties NSExtensionPrincipalClass and NSExtensionMainStoryboard are mutually exclusive.

Initializing the Lemnisk Flutter SDK

Once the SDK is added, you need to initialize the Flutter SDK.

• Import the SDK wherever you'd like to use it in your Flutter codebase

import 'package:lemnisk_flutter/flutter_wrapper_method_channel.dart';

SDK API Methods

Push Notification Authorization Prompt

If you want to show the Push Notification Authorization Prompt from your Flutter code on any screen from your dart code, then you can call the following SDK API. Given you haven't already called this from your AppDelegate.

We recommend calling this method on every app launch.

LemniskFlutter.registerForPushNotifications(null, null);

Screen

The screen call lets you record whenever a user sees a screen, in your mobile app, along with any properties about the screen.

Usage:

LemniskFlutter.screen('screen_name', {properties}, {otherIds})

Example:

LemniskFlutter.screen("home", {
  "variation": "carousel",
  "buttons": 2
 }, {
	"trackerId": "6791c47a-0178-47bc-8711-86a2c67b2255"
})

Identify

The identify call lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about the user, like their email, mobile, any other id etc.

Usage:

LemniskFlutter.identify('userId', {traits}, {otherIds})

Example:

LemniskFlutter.identify('crmid1234', {
	"firstName": "John",
	"lastName": "Miller",
	"gender": "Male",
}, {
	"email": "[e-mail]"
})

Track

The track call lets you record any actions your users perform, along with any properties that describe the action.

Usage:

LemniskFlutter.track('eventName', {properties}, {otherIds})

Example:

LemniskFlutter.track('Product View', {
	"productName": "iPhone 13",
	"productCategory": "Mobiles",
	"price": "799",
	"currency": "USD",
}, {
	"email": "[e-mail]"
})

Parameter	Type	Description
eventName	String	The name of the event you’re tracking

Running Marketing Channels on WebView

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

Example:

LemniskFlutter.setDeviceIdToWebview('.google.com') //pass the domain of your webview

Parameter	Type	Description
domain	String	Domain of your webView

Configuring APNS Certificates

Lemnisk would need the cert.pem and key.pem files generated for your application to be able to send the App Push Notifications.

Following is the procedure to generate the cert.pem and key.pem files.

Generating the CSR and p12

Open Keychain Access on your Mac (it is in Applications/Utilities) and choose the menu option Request a Certificate from a Certificate Authority

You should now see the following window:

1. Enter your email address here.

2. Enter your application name here, for example, I have entered "LemniskDemo". You can type anything you want here, but choose something descriptive. This allows us to easily find the private key later.

3. Check Saved to disk and click Continue.

If you go to the Keys section of Keychain Access, you will see that a new private key has appeared in your keychain.

Right-click on the new private key and choose Export.

Save the private key as LemniskDemoKey.p12 and enter a passphrase. (Do choose a passphrase that you can recall! Or you won’t be able to use the private key later.)

So log in to the Apple developer console & follow the below steps:

Generating the aps cert

Assuming you have already created the Identifier for your app bundle id, now navigate to the Certificates section in the developer console. Click on the + next to Certificates

Choose the Apple Push Notification service SSL (Sandbox & Production) option and click on Continue

Now select the App Id from the already registered (of your app) list in the Identifier section and then click on Continue

Now click on Choose File and select the CSR file that we have generated above and click on Continue

Now we have successfully generated the aps.cer file, click on Download to download the cer file. Let’s say the downloaded file name is aps.cer

Generating the PEM file

So now we have three files:

1. The CSR

2. The private key as a p12 file (LemniskDemoKey.p12)

3. The SSL certificate (aps.cer)

You have to convert the certificate and private key into a format that is more usable. Because our server will need the cert.pem and key.pem file to deliver the push notification, now we will generate them by using the following procedure.

We are going to use the command-line OpenSSL tools for this. Open a Terminal and execute the following steps.

Convert the .cer file into a .pem file:

$ openssl x509 -in aps.cer -inform der -out LemniskDemoCert.pem

Convert the private key’s .p12 file into a .pem file:

$ openssl pkcs12 -nocerts -out LemniskDemoKey.pem -in LemniskDemoKey.p12

 Enter Import Password: 

 MAC verified OK
 
 Enter PEM pass phrase: 

 Verifying - Enter PEM pass phrase: 

You first need to enter the passphrase for the .p12 file so that openssl can read it. Then you need to enter a new passphrase that will be used to encrypt the PEM file.

Note: if you don’t enter a PEM passphrase, openssl will not give an error message but the generated .pem file will not have the private key in it.

Now let’s try to test whether the certificate works, by using our SSL certificate and private key:

$ openssl s_client -connect gateway.push.apple.com:2196 -cert LemniskDemoCert.pem -key LemniskDemoKey.pem

    Enter pass phrase for LemniskDemoCert.pem:

Now please share the following with your account manager for us to be able to send push notifications

1. cert.pem and key.pem (Generated above)

2. passphrase (if any given in the above steps)

3. bundle identifier of the app

FAQs

Q1. What is the minimum Android and iOS versions supported by the Lemnisk Flutter SDK?

Ans: iOS 13 and Android 5.0 or higher is supported.

6. Contact Us

To know more about the Lemnisk Flutter SDK you can contact us.