❤
npm
Sign UpSign In

@rollershop/capacitor-emarsys-sdk
TypeScript icon, indicating that this package has built-in type declarations

1.2.1 • Public • Published

Capacitor Emarsys SDK

Maintenance npm

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

Table of Content

Helpful Links

SDK Versions

  • iOS: 3.7.0
  • 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:

Prop Type Description Since
mobileEngageApplicationCode string Emarsys App code, which is generated when the app is added to the account. 1.0.0
merchantId string Emarsys Predict Merchant ID (If the Predict feature is enabled on the Emarsys account). 1.0.0
consoleLogLevels {} The default console logging is only showing logs when you call an unallowed method. You are able to modify the allowed loglevels for console logging, by setting it during the setup. 1.0.0

Examples

In capacitor.config.json:

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

In capacitor.config.ts:

/// <reference types="@rollershop/capacitor-emarsys-sdk" />

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
  1. You may need to run pod install after it
  2. 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()

checkPermissions() => any

Check permission to receive push notifications.

Returns: any

Since: 1.0.0

requestPermissions()

requestPermissions() => any

Request permission to receive push notifications.

Returns: any

Since: 1.0.0

register()

register() => any

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: any

Since: 1.0.0

setContact(...)

setContact(options: SetContactOptions) => any

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.

Param Type
options SetContactOptions

Returns: any

Since: 1.0.0

setAuthenticatedContact(...)

setAuthenticatedContact(options: SetAuthenticatedContactOptions) => any

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.

Param Type
options SetAuthenticatedContactOptions

Returns: any

Since: 1.0.0

clearContact()

clearContact() => any

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.

Returns: any

Since: 1.0.0

getPushToken()

getPushToken() => any

Use this method to get the current push token.

Returns: any

Since: 1.0.0

clearPushToken()

clearPushToken() => any

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

Returns: any

Since: 1.0.0

pauseInApp()

pauseInApp() => any

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

Returns: any

Since: 1.0.0

isInAppPaused()

isInAppPaused() => any

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

Returns: any

Since: 1.0.0

resumeInApp()

resumeInApp() => any

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

Returns: any

Since: 1.0.0

trackItem(...)

trackItem(options: { itemId: string; }) => any

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

Param Type
options { itemId: string; }

Returns: any

Since: 1.0.0

trackCategory(...)

trackCategory(options: { categoryPath: string; }) => any

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.

Param Type
options { categoryPath: string; }

Returns: any

Since: 1.0.0

trackSearch(...)

trackSearch(options: { searchTerm: string; }) => any

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

Param Type
options { searchTerm: string; }

Returns: any

Since: 1.0.0

trackTag(...)

trackTag(options: { tag: string; }) => any

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

Param Type
options { tag: string; }

Returns: any

Since: 1.0.0

trackCard(...)

trackCard(options: CardItems) => any

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

Param Type
options CardItems

Returns: any

Since: 1.0.0

trackPurchase(...)

trackPurchase(options: Purchase) => any

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

Param Type
options Purchase

Returns: any

Since: 1.0.0

trackCustomEvent(...)

trackCustomEvent(event: CustomEvent) => any
Param Type
event CustomEvent

Returns: any

recommendProducts(...)

recommendProducts(options: RecommendedProductOptions) => any

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!

Param Type
options RecommendedProductOptions

Returns: any

Since: 1.0.0

trackRecommendationClick(...)

trackRecommendationClick(product: Product) => any

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.

Param Type
product Product

Returns: any

Since: 1.0.0

fetchMessages()

fetchMessages() => any

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

Returns: any

Since: 1.0.0

addTag(...)

addTag(options: InboxTag) => any

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

Param Type
options InboxTag

Returns: any

Since: 1.0.0

removeTag(...)

removeTag(options: InboxTag) => any

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

Param Type
options InboxTag

Returns: any

Since: 1.0.0

getApplicationCode()

getApplicationCode() => any

Provides what is the actual applicationCode set in the SDK.

Returns: any

Since: 1.0.0

setApplicationCode(...)

setApplicationCode(options: ApplicationCode) => any

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

Param Type
options ApplicationCode

Returns: any

Since: 1.0.0

getMerchantId()

getMerchantId() => any

Provides what is the actual merchantId set in the SDK.

Returns: any

Since: 1.0.0

setMerchantId(...)

setMerchantId(options: MerchantId) => any

Change the actual merchantId that is set in the SDK.

Param Type
options MerchantId

Returns: any

Since: 1.0.0

getContactFieldId()

getContactFieldId() => any

Provides what is the actual contactFieldId set in the SDK.

Returns: any

Since: 1.0.0

getHardwareId()

getHardwareId() => any

Provides what is the actual hardwareId set in the SDK.

Returns: any

Since: 1.0.0

getLanguageCode()

getLanguageCode() => any

Provides what is the actual language of the application.

Returns: any

Since: 1.0.0

getSdkVersion()

getSdkVersion() => any

Provides the actual sdkVersion

Returns: any

Since: 1.0.0

addListener('pushMessageEvent', ...)

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

Called when a event is received

Param Type
eventName 'pushMessageEvent'
listenerFunc (event: PushMessageEvent) => void

Returns: any

Since: 1.0.0

addListener('silentPushMessageInformation', ...)

addListener(eventName: 'silentPushMessageInformation', listenerFunc: (information: SilentPushMessageInformation) => void) => any

Called when a silent push message is received

Param Type
eventName 'silentPushMessageInformation'
listenerFunc (information: SilentPushMessageInformation) => void

Returns: any

Since: 1.0.0

removeAllListeners()

removeAllListeners() => any

Remove all native listeners for this plugin.

Returns: any

Since: 1.0.0

Interfaces

PermissionStatus

Prop Type Since
receive PermissionState 1.0.0

TokenResult

Prop Type Since
token string 1.0.0

SetContactOptions

Prop Type Since
contactFieldValue string 1.0.0

SetAuthenticatedContactOptions

Prop Type Since
openIdToken string 1.0.0

CardItems

Prop Type
items {}

CardItem

Prop Type Since
itemId string 1.0.0
price number 1.0.0
quantity number 1.0.0

Purchase

Prop Type Since
orderId string 1.0.0

CustomEvent

Prop Type Description Since
name string The eventName 1.0.0
attributes { [key: string]: string; } The event attributes 1.0.0

RecommendedProductOptions

Prop Type Description Default Since
logic RecommendedProductLogic The logic that should be used. 1.0.0
filter {} You can filter product recommendations with the SDK. There are two types of filters: Exclude or Include. In every case there are four types of comparators you can use to compare your chosen field to the value. This is an optional parameter. 1.0.0
limit number You can limit the number of recommended products received by defining a limit. 5 1.0.0
availabilityZone string You can personalize the recommendation further by setting the availabilityZones parameter of the recommendation, to only recommend the locally available products. This is an optional parameter. 1.0.0

RecommendedProductSearchLogic

Based on searchTerm

Prop Type Since
type 'search' 1.0.0
value string 1.0.0

RecommendedProductCartLogic

Based on cartItems

Prop Type Since
type 'cart' 1.0.0
value {} 1.0.0

RecommendedProductRelatedLogic

Based on itemViewId

Prop Type Since
type 'related' 1.0.0
value string 1.0.0

RecommendedProductCategoryLogic

Based on categoryPath

Prop Type Since
type 'category' 1.0.0
value string 1.0.0

RecommendedProductAlsoBoughtLogic

Based on itemViewId

Prop Type Since
type 'also_bought' 1.0.0
value string 1.0.0

RecommendedProductPopularLogic

Based on categoryPath

Prop Type Since
type 'popular' 1.0.0
value string 1.0.0

RecommendedProductPersonalLogic

Based on based on current browsing and activity

Optionally based on the variants

Prop Type Since
type 'personal' 1.0.0
value {} 1.0.0

RecommendedProductHomeLogic

Based on most recent browsing behaviour

Optionally based on the variants

Prop Type Since
type 'home' 1.0.0
value {} 1.0.0

RecommendedProductValueFilter

Prop Type Description Since
filterType RecommendedProductFilterType 1.0.0
comparatorType RecommendedProductValueFilterComparatorType isValue: checking if the field is matching the value, hasValue: One of the field values is equal to expectation value (applicable only to fields containing multiple values) 1.0.0
field string 1.0.0
value string 1.0.0

RecommendedProductArrayFilter

Prop Type Description Since
filterType RecommendedProductFilterType 1.0.0
comparatorType RecommendedProductArrayFilterComparatorType inValues: any of the values has a match with the field, overlapsValues: One or more of the field values are found in expectation values (applicable only to fields containing multiple values) 1.0.0
field string 1.0.0
value {} 1.0.0

RecommendedProducts

Prop Type Since
products {} 1.0.0

Product

Prop Type Since
productId string 1.0.0
title string 1.0.0
linkUrl string 1.0.0
customFields { [key: string]: any; } 1.0.0
feature string 1.0.0
cohort string 1.0.0
imageUrl string 1.0.0
zoomImageUrl string 1.0.0
categoryPath string 1.0.0
available number 1.0.0
productDescription string 1.0.0
price number 1.0.0
msrp number 1.0.0
album string 1.0.0
actor string 1.0.0
artist string 1.0.0
author string 1.0.0
brand string 1.0.0
year number 1.0.0

InboxTag

Prop Type Since
tag string 1.0.0
messageId string 1.0.0

ApplicationCode

Prop Type Since
applicationCode string 1.0.0

MerchantId

Prop Type Since
merchantId string 1.0.0

ContactFieldId

Prop Type Since
contactFieldId number 1.0.0

PushMessageEvent

Prop Type Since
eventName string 1.0.0
data {} 1.0.0

PluginListenerHandle

Prop Type
remove () => any

SilentPushMessageInformation

Prop Type Since
campaignId string 1.0.0

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

/@rollershop/capacitor-emarsys-sdk/

    Package Sidebar

    Install

    npm i @rollershop/capacitor-emarsys-sdk

    Repository

    github.com/roller-ecom/capacitor-emarsys-sdk

    Homepage

    github.com/roller-ecom/capacitor-emarsys-sdk#readme

    Weekly Downloads

    78

    Version

    1.2.1

    License

    MIT

    Unpacked Size

    144 kB

    Total Files

    43

    Last publish

    Collaborators

    • samydoesit
    • roller-shop
    Try on RunKit
    Report malware