Skip to content

Home

Jump to bottom
David Schuppa edited this page Jun 17, 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

Note

This step will change when the plug-in is available on pub.dev.

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

emarsys_sdk:
    git:
      url: https://github.com/emartech/flutter-plugin-for-sap-emarsys-customer-engagement.git
      ref: master

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.

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

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.EmarsysMessagingService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

iOS

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(<contactFieldId: int>, <applicationCode: String>));

  runApp(MyApp());
}

1.3 setContact

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

Emarsys.setContact(<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.

Emarsys.push.pushSendingEnabled(true);

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