Skip to content

Home

Jump to bottom
zkovacs edited this page Aug 25, 2021 · 67 revisions

Contents

Note

This product is under development and currently it doesn't support all of the native Emarsys SDK features. At the moment it is capable of setting up the Emarsys SDK, handling push messages, displaying in-app messages and supports the interface for getting the current configuration. If you'd like to use this plugin, please start by contacting your Emarsys CSM.

What is the Emarsys SDK

The Emarsys SDK enables you to use Mobile Engage and Predict in a very straightforward way. By incorporating the SDK in your app, we, among others, support you in handling credentials, API calls, tracking of opens and events as well as logins and logouts in the app.

The Flutter plug-in for SAP Emarsys Customer Engagement

Note

The currently supported platforms are iOS and Android.

The Flutter plug-in for SAP Emarsys Customer Engagement is the official plug-in to help integrate Emarsys into your Flutter application. We have created a sample application to help in the integration and to give an example. The Flutter sample application is published here.

On this page we won't go into details about how the underlying Emarsys SDK works and how the supported features can be used. For more detailed information about the different features, please visit the documentation for the iOS SDK or the Android SDK.

As this plug-in uses the respective Emarsys iOS and Emarsys Android SDK, their requirements apply (iOS SDK Requirements, Android SDK Requirements)

Requirements

Android

  • The minimum Android version should be at least API level 21.
  • Requires compileSdkVersion 28 or higher.
  • Emarsys SDK is using AndroidX.

iOS

  • The iOS target should be iOS 11 or higher.
  • In order to be able to send push messages to your app, you need to have certifications from Apple Push Notification service (APNs).

1. First steps

1.1 Install the Emarsys SDK

To make the Emarsys SDK available for your project, you have to open the project's pubspec.yaml file and add this into the dependencies section:

emarsys_sdk: ^0.1.1

After our SDK as dependency has been added to the pubspec.yaml, you have to call flutter pub get in terminal to download the library.

The official pub.dev page of the plug-in is available here.

1.2 Setup the Emarsys SDK

To make the SDK usable in your project, you have to do a few initial steps in the native part.

Android

Extend from FlutterFragmentActivity instead of FlutterActivity in the android/app/.../MainActivity it is necessary for the SDK, to be able to show In-App and Push to In-App messages

To be able to receive push messages please see the following sections to enable support for Firebase and/or Huawei services.

Firebase

Add google-services to your android/app/build.gradle

apply plugin: 'com.google.gms.google-services'

Then specify your google-services version in your android/build.gradle, under buildscript/dependencies

classpath 'com.google.gms:google-services:<LATEST_VERSION>'

Copy your google-services.json to the android/app directory of your Flutter application.

Open the AndroidManifest.xml and add the following part in the application section:

<service android:name="com.emarsys.emarsys_sdk.api.EmarsysFirebaseMessagingService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Extend from FlutterFragmentActivity instead of FlutterActivity in the android/app/.../MainActivity it is necessary for the SDK, to be able to show In-App and Push to In-App messages

Huawei

Important Note: Push sending for Huawei is unavailable for devices below API level 22!

Emarsys SDK checks if the device has Google Play Services available and if not, it is considered as a Huawei device. Please note that as Google Play Services is not availeble with Huawei only integrations, Geofencing will not work!

Copy your agconnect-services.json to the android/app directory of your Flutter application.

Open the AndroidManifest.xml and add the following parts in the application section:

<meta-data
    android:name="com.huawei.hms.client.channel.androidMarket"
    android:value="false" />
<meta-data
    android:name="push_kit_auto_init_enabled"
    android:value="true" />
<service android:name="com.emarsys.emarsys_sdk.api.EmarsysHuaweiMessagingService">
    <intent-filter>
        <action android:name="com.google.huawei.MESSAGING_EVENT" />
    </intent-filter>
</service>

iOS

Open the iOS app in XCode and add the following capabilities to the applications target:

  • Push Notifications
  • Background Modes, with Background fetch, Remote Notifications, Background processing enabled

Then add a Notification Extension Service target to your project.

Extend your Podfile with:

target '<Your Notification Extension Service Name>' do
  use_frameworks!
  use_modular_headers!

  pod 'EmarsysNotificationService'
end

After a pod deintegrate and pod install extend your Notification Extension Service from EMSNotificationService

import UserNotifications
import EmarsysNotificationService

class NotificationService: EMSNotificationService {
}

You have to extend your AppDelegate from our EmarsysAppDelegate class to make the SDK usable and add this code part: GeneratedPluginRegistrant.register(with: self) to the first line of your didFinishLaunchingWithOptions method. So without any further modifications, your whole class should look like this:

import UIKit
import Flutter
import emarsys_sdk

@UIApplicationMain
@objc class AppDelegate: EmarsysAppDelegate {
    
    override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        GeneratedPluginRegistrant.register(with: self)
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}

Flutter

To be able to use the SDK in your project import the Emarsys plugin like in the following example

import 'package:emarsys_sdk/emarsys_sdk.dart';

Then in the main method after the WidgetsFlutterBinding.ensureInitialized(); line you have to setup the Emarsys SDK with config:

IMPORTANT

Please make sure that WidgetsFlutterBinding.ensureInitialized(); has been added to the first line of the main method.

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  Emarsys.setup(
      EmarsysConfig(<applicationCode: String>));

  runApp(MyApp());
}

1.3 setContact

After application setup is finished, you can use setContact method to identify the user with a contactFieldId and a contactFieldValue.

Emarsys.setContact(<contactFieldId: int>, <contactFieldValue: String>);

1.4 clearContact

When the user signs out, the clearContact method should be used:

Note

You only need to call clearContact when you explicitly want to sign out the contact from Emarsys even if the user isn’t logged in into your application.

Emarsys.clearContact();

Push

2.1 pushSendingEnabled

Note

By default the Flutter plug-in will set pushSendingEnabled to true, to ensure that the application will be able to receive remote notifications.

Currently the plug-in doesn't support Huawei Push Kit, only Firebase!

Emarsys.push.pushSendingEnabled(true);

To be able to show push notifications, the Android notification channels has to be set since API level 26 (Oreo). To make integration easier with the SDK we've created a wrapper around the Notification Channels API.

Emarsys.push.registerAndroidNotificationChannels([
    NotificationChannel(
        id: "ems_sample_news",
        name: "News",
        description: "News and updates go into this channel",
        importance: NotificationChannel.IMPORTANCE_HIGH),
    NotificationChannel(
        id: "ems_sample_messages",
        name: "Messages",
        description: "Important messages go into this channel",
        importance: NotificationChannel.IMPORTANCE_HIGH),
  ]);

2.2 pushEventStream

Unlike the native Emarsys SDK, you can't register eventHandlers, but can react to an event by subscribing to event streams:

Emarsys.push.pushEventStream.listen((event) {
    print(event.name);
    print(event.payload);
});

2.3 silentPushEventStream

Unlike the native Emarsys SDK, you can't register eventHandlers, but can react to an event by subscribing to event streams:

Emarsys.push.silentPushEventStream.listen((event) {
    print(event.name);
    print(event.payload);
});

3. Config

Config can be used to access information about the values set in the Emarsys SDK.

3.1 applicationCode

Provides what is the actual applicationCode set in the SDK.

Emarsys.config.applicationCode();

3.2 contactFieldId

Provides what is the actual contactFieldId set in the SDK.

Emarsys.config.contactFieldId();

3.3 hardwareId

Provides what is the actual hardwareId set in the SDK.

Emarsys.config.hardwareId();

3.4 languageCode

Provides what is the actual languageCode set in the SDK.

Emarsys.config.languageCode();

3.5 notificationSettings

Provides what is the actual notificationSettings set in the SDK.

This method will return with a NotificationSettings object, which contains the current notification settings, based on which platform your application runs at the moment.

Emarsys.config.notificationSettings();

3.6 sdkVersion

Note

This isn't the Flutter plug-in version.

Provides what is the actual native sdkVersion set in the SDK.

Emarsys.config.sdkVersion();

3.7 flutterPluginVersion

Note

This isn't the native Emarsys SDK version.

Provides what is the actual flutterPluginVersion.

Emarsys.config.flutterPluginVersion();

4. Data flows in the plugin

Using this Flutter plug-in means that the automated tracking of the respective Android and iOS Emarsys SDK features will also be active. Details of this are documented for Android and iOS. In addition when the Emarsys.setup method is called, the Flutter plug-in will submit an Emarsys custom event reporting that the setup was called from Flutter.

Clone this wiki locally