1.2.1 • Published 10 months ago

@rollershop/capacitor-emarsys-sdk v1.2.1

Weekly downloads
-
License
MIT
Repository
github
Last release
10 months ago

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:

PropTypeDescriptionSince
mobileEngageApplicationCodestringEmarsys App code, which is generated when the app is added to the account.1.0.0
merchantIdstringEmarsys 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.

ParamType
optionsSetContactOptions

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.

ParamType
optionsSetAuthenticatedContactOptions

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.

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

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

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

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

ParamType
optionsCardItems

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.

ParamType
optionsPurchase

Returns: any

Since: 1.0.0


trackCustomEvent(...)

trackCustomEvent(event: CustomEvent) => any
ParamType
eventCustomEvent

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!

ParamType
optionsRecommendedProductOptions

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.

ParamType
productProduct

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)

ParamType
optionsInboxTag

Returns: any

Since: 1.0.0


removeTag(...)

removeTag(options: InboxTag) => any

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

ParamType
optionsInboxTag

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.

ParamType
optionsApplicationCode

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.

ParamType
optionsMerchantId

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

ParamType
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

ParamType
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

PropTypeSince
receivePermissionState1.0.0

TokenResult

PropTypeSince
tokenstring1.0.0

SetContactOptions

PropTypeSince
contactFieldValuestring1.0.0

SetAuthenticatedContactOptions

PropTypeSince
openIdTokenstring1.0.0

CardItems

PropType
items{}

CardItem

PropTypeSince
itemIdstring1.0.0
pricenumber1.0.0
quantitynumber1.0.0

Purchase

PropTypeSince
orderIdstring1.0.0

CustomEvent

PropTypeDescriptionSince
namestringThe eventName1.0.0
attributes{ key: string: string; }The event attributes1.0.0

RecommendedProductOptions

PropTypeDescriptionDefaultSince
logicRecommendedProductLogicThe 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
limitnumberYou can limit the number of recommended products received by defining a limit.51.0.0
availabilityZonestringYou 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

PropTypeSince
type'search'1.0.0
valuestring1.0.0

RecommendedProductCartLogic

Based on cartItems

PropTypeSince
type'cart'1.0.0
value{}1.0.0

RecommendedProductRelatedLogic

Based on itemViewId

PropTypeSince
type'related'1.0.0
valuestring1.0.0

RecommendedProductCategoryLogic

Based on categoryPath

PropTypeSince
type'category'1.0.0
valuestring1.0.0

RecommendedProductAlsoBoughtLogic

Based on itemViewId

PropTypeSince
type'also_bought'1.0.0
valuestring1.0.0

RecommendedProductPopularLogic

Based on categoryPath

PropTypeSince
type'popular'1.0.0
valuestring1.0.0

RecommendedProductPersonalLogic

Based on based on current browsing and activity

Optionally based on the variants

PropTypeSince
type'personal'1.0.0
value{}1.0.0

RecommendedProductHomeLogic

Based on most recent browsing behaviour

Optionally based on the variants

PropTypeSince
type'home'1.0.0
value{}1.0.0

RecommendedProductValueFilter

PropTypeDescriptionSince
filterTypeRecommendedProductFilterType1.0.0
comparatorTypeRecommendedProductValueFilterComparatorTypeisValue: 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
fieldstring1.0.0
valuestring1.0.0

RecommendedProductArrayFilter

PropTypeDescriptionSince
filterTypeRecommendedProductFilterType1.0.0
comparatorTypeRecommendedProductArrayFilterComparatorTypeinValues: 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
fieldstring1.0.0
value{}1.0.0

RecommendedProducts

PropTypeSince
products{}1.0.0

Product

PropTypeSince
productIdstring1.0.0
titlestring1.0.0
linkUrlstring1.0.0
customFields{ key: string: any; }1.0.0
featurestring1.0.0
cohortstring1.0.0
imageUrlstring1.0.0
zoomImageUrlstring1.0.0
categoryPathstring1.0.0
availablenumber1.0.0
productDescriptionstring1.0.0
pricenumber1.0.0
msrpnumber1.0.0
albumstring1.0.0
actorstring1.0.0
artiststring1.0.0
authorstring1.0.0
brandstring1.0.0
yearnumber1.0.0

InboxTag

PropTypeSince
tagstring1.0.0
messageIdstring1.0.0

ApplicationCode

PropTypeSince
applicationCodestring1.0.0

MerchantId

PropTypeSince
merchantIdstring1.0.0

ContactFieldId

PropTypeSince
contactFieldIdnumber1.0.0

PushMessageEvent

PropTypeSince
eventNamestring1.0.0
data{}1.0.0

PluginListenerHandle

PropType
remove() => any

SilentPushMessageInformation

PropTypeSince
campaignIdstring1.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

1.2.1

10 months ago

1.2.1-beta.5

10 months ago

1.2.1-beta.6

10 months ago

1.2.1-beta.1

2 years ago

1.2.1-beta.2

2 years ago

1.2.1-beta.3

2 years ago

1.2.1-beta.4

2 years ago

1.2.0

3 years ago

1.1.0

3 years ago

1.0.0

3 years ago

1.0.0-beta.2

3 years ago

1.0.0-beta.3

3 years ago

1.0.0-beta.1

3 years ago