@rollershop/capacitor-emarsys-sdk v1.2.0

Capacitor Emarsys SDK

This Plugin is used as a wrapper for the Emarsys SDK.

Table of Content

• Helpful Links
• SDK Versions
• Install
• Setup
  • Initialize SDK
  • Examples
  • iOS
  • Android
• Flow
• In-App
• Predict
• DeepLink
• API
  • checkPermissions()
  • requestPermissions()
  • register()
  • setContact(...)
  • setAuthenticatedContact(...)
  • clearContact()
  • getPushToken()
  • clearPushToken()
  • pauseInApp()
  • isInAppPaused()
  • resumeInApp()
  • trackItem(...)
  • trackCategory(...)
  • trackSearch(...)
  • trackTag(...)
  • trackCard(...)
  • trackPurchase(...)
  • recommendProducts(...)
  • trackRecommendationClick(...)
  • fetchMessages()
  • addTag(...)
  • removeTag(...)
  • getApplicationCode()
  • setApplicationCode(...)
  • getMerchantId()
  • setMerchantId(...)
  • getContactFieldId()
  • getHardwareId()
  • getLanguageCode()
  • getSdkVersion()
  • addListener('pushMessageEvent', ...)
  • addListener('silentPushMessageInformation', ...)
  • removeAllListeners()
  • Interfaces
  • Type Aliases
• Changelog

Helpful Links

• iOS Library
• Emarsys Platform

SDK Versions

• iOS: 3.2.2
• Android: Not implemented

Install

npm install @rollershop/capacitor-emarsys-sdk
npx cap sync

Setup

Initialize SDK

The following options are available to initialize the SDK:

Examples

In capacitor.config.json:

{
  "plugins": {
    "Emarsys": {
      "mobileEngageApplicationCode": 'yourApplicationCode',
      "merchantId": 'yourMerchantId',
      "consoleLogLevels": ['info', 'debug', '...']
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capacitor/emarsys" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Emarsys: {
      mobileEngageApplicationCode: 'yourApplicationCode',
      merchantId: 'yourMerchantId',
      consoleLogLevels: ['info', 'debug', '...'],
    },
  },
};

export default config;

iOS

The following changes needs to be done in AppDelegate.swift:

1. Add import: import RollershopCapacitorEmarsysSdk
2. Extend the base class:

class AppDelegate: EmarsysDelegate {
...

Rich Push Notifications

Push notification could show media content and action buttons besides the title and body. Push notifications with these types of contents are called Rich Notifications.

Setup:

1. Add a new Notification Service Extension target to your project
   • Guide
   • Name: NotificationService
   • Language: swift
   • If Xcode ask's you tu change the scheme, deny it
2. Navigate to your App's main Podfile and add at the bottom of the file:

target "NotificationService" do
  pod 'EmarsysNotificationService'
end

3. You may need to run pod install after it
4. Open the NotificationService.swift and replace the content with:

import EmarsysNotificationService

class NotificationService: EMSNotificationService {
}

Android

Android is not supported at the moment...

Flow

You need to call register on every app start! This is required, because it could be that the push token has changed and because of the implemented queue. Stacked Messages are send after the register completes to make sure we receive events that were emitted while the app was killed.

Before the register call the listeners should be added.

Example of a PushService.ts:

import { Emarsys } from '@rollershop/capacitor-emarsys-sdk';

public init() {
  Emarsys.addListener('pushMessageEvent', message => {
    // do something
  });
  // add other listeners
  
  Emarsys.register().then(response => {
    // do something with the token (if required)
  });
}

This init() function needs to be called on every app start. Remember that requestPermissions() also needs to be called (if not granted yet), so call that in a good moment as well.

In-App

Because this Plugin is for Capacitor, Inline In-App Messages can't work.

They work by being loaded into a specific view by an id. Because Capacitor works by only having one view with the webview which contains the sources of the inner "website", there are no views where a Inline In-App message could be load into.

Predict

To use the Predict functionality, you have to setup your merchantId during the initialization of the SDK.

At the current time Predict does not support authenticating users with Open ID Connect, identifying a contact with setAuthenticatedContact will disable the usage of Predict features!

DeepLink

In order to track email link clicks that open the application directly with the Emarsys SDK, read here.

API

• checkPermissions()
• requestPermissions()
• register()
• setContact(...)
• setAuthenticatedContact(...)
• clearContact()
• getPushToken()
• clearPushToken()
• pauseInApp()
• isInAppPaused()
• resumeInApp()
• trackItem(...)
• trackCategory(...)
• trackSearch(...)
• trackTag(...)
• trackCard(...)
• trackPurchase(...)
• recommendProducts(...)
• trackRecommendationClick(...)
• fetchMessages()
• addTag(...)
• removeTag(...)
• getApplicationCode()
• setApplicationCode(...)
• getMerchantId()
• setMerchantId(...)
• getContactFieldId()
• getHardwareId()
• getLanguageCode()
• getSdkVersion()
• addListener('pushMessageEvent', ...)
• addListener('silentPushMessageInformation', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check permission to receive push notifications.

Returns: Promise<PermissionStatus>

Since: 1.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permission to receive push notifications.

Returns: Promise<PermissionStatus>

Since: 1.0.0

register()

register() => Promise<TokenResult>

Register the app to receive push notifications.

This method will resolve with the push token or reject if there was a problem. It does not prompt the user for notification permissions, use requestPermissions() first.

Returns: Promise<TokenResult>

Since: 1.0.0

setContact(...)

setContact(options: SetContactOptions) => Promise<void>

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

Without contact identification all tracked events will be linked to an anonymous contact in Mobile Engage and will rely on visitor cookies in case of Predict.

Since: 1.0.0

setAuthenticatedContact(...)

setAuthenticatedContact(options: SetAuthenticatedContactOptions) => Promise<void>

After the application setup is finished, you can use this method to identify the user with an openIdToken.

Without contact identification all tracked events will be linked to an anonymous contact in Mobile Engage and will rely on visitor cookies in case of Predict.

Since: 1.0.0

clearContact()

clearContact() => Promise<void>

When the user signs out, this method should be used.

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.

Since: 1.0.0

getPushToken()

getPushToken() => Promise<TokenResult>

Use this method to get the current push token.

Returns: Promise<TokenResult>

Since: 1.0.0

clearPushToken()

clearPushToken() => Promise<void>

Use this method to remove the push token of the contact.

Since: 1.0.0

pauseInApp()

pauseInApp() => Promise<void>

When a critical activity starts and should not be interrupted by In-App, pause In-App messages.

Since: 1.0.0

isInAppPaused()

isInAppPaused() => Promise<{ isPaused: boolean; }>

Use this method to check if in app messages are paused.

Returns: Promise<{ isPaused: boolean; }>

Since: 1.0.0

resumeInApp()

resumeInApp() => Promise<void>

In order to show In-App messages after being paused, use the resume method.

Since: 1.0.0

trackItem(...)

trackItem(options: { itemId: string; }) => Promise<void>

If an item was viewed use the trackItemView method with an itemId.

Since: 1.0.0

trackCategory(...)

trackCategory(options: { categoryPath: string; }) => Promise<void>

When the user navigates between the categories you should call trackCategoryView in every navigation. Be aware to send categoryPath in the required format. Please visit Predict's documentation for more information.

Since: 1.0.0

trackSearch(...)

trackSearch(options: { searchTerm: string; }) => Promise<void>

To report search terms entered by the contact use trackSearchTerm method.

Since: 1.0.0

trackTag(...)

trackTag(options: { tag: string; }) => Promise<void>

To report search terms entered by the contact use trackSearchTerm method.

Since: 1.0.0

trackCard(...)

trackCard(options: CardItems) => Promise<void>

When you want to track the cart items in the basket you can call this method with a list of CartItems.

Since: 1.0.0

trackPurchase(...)

trackPurchase(options: Purchase) => Promise<void>

To report a purchase event you should call this method with the items purchased and with an orderId.

Since: 1.0.0

recommendProducts(...)

recommendProducts(options: RecommendedProductOptions) => Promise<RecommendedProducts>

With the Emarsys SDK you can ask for product recommendations based on different recommendation logics.

This method is also going to track the value attached to the logic on the backend, so no additional tracking needed when using recommendations!

Returns: Promise<RecommendedProducts>

Since: 1.0.0

trackRecommendationClick(...)

trackRecommendationClick(product: Product) => Promise<void>

The Emarsys SDK doesn't track automatically recommendationClicks, so you have to call manually trackRecommendationClick when an interaction happens with any of the recommended products.

Since: 1.0.0

fetchMessages()

fetchMessages() => Promise<any>

In order to receive the messageInbox content, you can use this method.

Returns: Promise<any>

Since: 1.0.0

addTag(...)

addTag(options: InboxTag) => Promise<void>

To label a message with a tag, you can use this method. (for example: "READ", "SEEN" etc)

Since: 1.0.0

removeTag(...)

removeTag(options: InboxTag) => Promise<void>

To remove a label from a message, you can use this method.

Since: 1.0.0

getApplicationCode()

getApplicationCode() => Promise<ApplicationCode>

Provides what is the actual applicationCode set in the SDK.

Returns: Promise<ApplicationCode>

Since: 1.0.0

setApplicationCode(...)

setApplicationCode(options: ApplicationCode) => Promise<void>

If any error occurs during the change process, the Mobile Engage feature will be turned off.

Since: 1.0.0

getMerchantId()

getMerchantId() => Promise<MerchantId>

Provides what is the actual merchantId set in the SDK.

Returns: Promise<MerchantId>

Since: 1.0.0

setMerchantId(...)

setMerchantId(options: MerchantId) => Promise<void>

Change the actual merchantId that is set in the SDK.

Since: 1.0.0

getContactFieldId()

getContactFieldId() => Promise<ContactFieldId>

Provides what is the actual contactFieldId set in the SDK.

Returns: Promise<ContactFieldId>

Since: 1.0.0

getHardwareId()

getHardwareId() => Promise<{ hardwareId: string; }>

Provides what is the actual hardwareId set in the SDK.

Returns: Promise<{ hardwareId: string; }>

Since: 1.0.0

getLanguageCode()

getLanguageCode() => Promise<{ languageCode: string; }>

Provides what is the actual language of the application.

Returns: Promise<{ languageCode: string; }>

Since: 1.0.0

getSdkVersion()

getSdkVersion() => Promise<{ sdkVersion: string; }>

Provides the actual sdkVersion

Returns: Promise<{ sdkVersion: string; }>

Since: 1.0.0

addListener('pushMessageEvent', ...)

addListener(eventName: 'pushMessageEvent', listenerFunc: (event: PushMessageEvent) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Called when a event is received

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 1.0.0

addListener('silentPushMessageInformation', ...)

addListener(eventName: 'silentPushMessageInformation', listenerFunc: (information: SilentPushMessageInformation) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Called when a silent push message is received

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all native listeners for this plugin.

Since: 1.0.0

Interfaces

PermissionStatus

TokenResult

SetContactOptions

SetAuthenticatedContactOptions

CardItems

CardItem

Purchase

RecommendedProducts

Product

RecommendedProductOptions

RecommendedProductSearchLogic

Based on searchTerm

RecommendedProductCartLogic

Based on cartItems

RecommendedProductRelatedLogic

Based on itemViewId

RecommendedProductCategoryLogic

Based on categoryPath

RecommendedProductAlsoBoughtLogic

Based on itemViewId

RecommendedProductPopularLogic

Based on categoryPath

RecommendedProductPersonalLogic

Based on based on current browsing and activity

Optionally based on the variants

RecommendedProductHomeLogic

Based on most recent browsing behaviour

Optionally based on the variants

RecommendedProductValueFilter

RecommendedProductArrayFilter

InboxTag

ApplicationCode

MerchantId

ContactFieldId

PluginListenerHandle

PushMessageEvent

SilentPushMessageInformation

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

RecommendedProductLogic

RecommendedProductSearchLogic | RecommendedProductCartLogic | RecommendedProductRelatedLogic | RecommendedProductCategoryLogic | RecommendedProductAlsoBoughtLogic | RecommendedProductPopularLogic | RecommendedProductPersonalLogic | RecommendedProductHomeLogic

RecommendedProductFilter

RecommendedProductValueFilter | RecommendedProductArrayFilter

RecommendedProductFilterType

'include' | 'exclude'

RecommendedProductValueFilterComparatorType

'isValue' | 'hasValue'

RecommendedProductArrayFilterComparatorType

'inValues' | 'overlapsValues'

Changelog

The full Changelog is available here