@rollershop/capacitor-emarsys-sdk

v1.2.1

Published

4 days ago

Capacitor Plugin that wraps the Emarsys SDK

Downloads

1,593

0High
0Medium
0Low

samydoesit

roller-shop

capacitor plugin native push notifications emarsys sdk

Capacitor Emarsys SDK

Maintenance

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:

Add import: import RollershopCapacitorEmarsysSdk
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:

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
Navigate to your App's main Podfile and add at the bottom of the file:

target "NotificationService" do
  pod 'EmarsysNotificationService'
end

You may need to run pod install after it
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

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 | ------------------------ | | productId | title | linkUrl | customFields | feature | cohort | imageUrl | zoomImageUrl | categoryPath | available | productDescription | price | msrp | album | actor | artist | author | brand | year | Since | ------------------------------------ | ----- | | string | 1.0.0 | | string | 1.0.0 | | string | 1.0.0 | | { [key: string]: any; } | 1.0.0 | | string | 1.0.0 | | string | 1.0.0 | | string | 1.0.0 | | string | 1.0.0 | | string | 1.0.0 | | number | 1.0.0 | | string | 1.0.0 | | number | 1.0.0 | | number | 1.0.0 | | string | 1.0.0 | | string | 1.0.0 | | string | 1.0.0 | | string | 1.0.0 | | string | 1.0.0 | | 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

RecommendedProductFilter

RecommendedProductValueFilter | RecommendedProductArrayFilter

RecommendedProductFilterType

'include' | 'exclude'

RecommendedProductValueFilterComparatorType

'isValue' | 'hasValue'

RecommendedProductArrayFilterComparatorType

'inValues' | 'overlapsValues'

Changelog

The full Changelog is available here

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Capacitor Emarsys SDK

Helpful Links

SDK Versions

Install

Setup

Initialize SDK

Examples

iOS

Rich Push Notifications

Android

Flow

In-App

Predict

DeepLink

API

checkPermissions()

requestPermissions()

register()

setContact(...)

setAuthenticatedContact(...)

clearContact()

getPushToken()

clearPushToken()

pauseInApp()

isInAppPaused()

resumeInApp()

trackItem(...)

trackCategory(...)

trackSearch(...)

trackTag(...)

trackCard(...)

trackPurchase(...)

trackCustomEvent(...)

recommendProducts(...)

trackRecommendationClick(...)

fetchMessages()

addTag(...)

removeTag(...)

getApplicationCode()

setApplicationCode(...)

getMerchantId()

setMerchantId(...)

getContactFieldId()

getHardwareId()

getLanguageCode()

getSdkVersion()

addListener('pushMessageEvent', ...)

addListener('silentPushMessageInformation', ...)

removeAllListeners()

Interfaces

PermissionStatus

TokenResult

SetContactOptions

SetAuthenticatedContactOptions

CardItems

CardItem

Purchase

CustomEvent

RecommendedProductOptions

RecommendedProductSearchLogic

RecommendedProductCartLogic

RecommendedProductRelatedLogic

RecommendedProductCategoryLogic

RecommendedProductAlsoBoughtLogic

RecommendedProductPopularLogic

RecommendedProductPersonalLogic

RecommendedProductHomeLogic

RecommendedProductValueFilter

RecommendedProductArrayFilter

RecommendedProducts

Product

InboxTag

ApplicationCode

MerchantId