API

After the SDK is initialized you can invoke one of the public SDK functions which are described in this section. If a public SDK functions which can be called is dependent on the activated feature set (see following sub chapter).

The SDK is available via the global variable WebEmarsysSdk, which you have created in the initialization step.

Please note that all functions except push return Promise objects.

Feature Sets

Actually the SDK supports 2 feature sets which are mutal exclusive

Web Push
Mobile Inbox (pulling of inbox messages in the web browser)

The Mobile Inbox feature set is NOT officially supported for all customers and - as mentioned - cannot be used together with Web Push.

Initialization of the Mobile Inbox

As already mentioned several times above, the Mobile Inbox feature cannot be used together with the Web Push feature and it needs also to be initialized in a different way. In order to enable this feature 2 things need to be done:

Assign to the applicationCode in your init code section an APP code of a mobile APP which is used for inbox campaigns. A web push related domain code will NOT work!
Add additional the initialization variable called useInbox to your initialization parameters and set it to true

When the SDK is initialized for Mobile Inbox Pull, all Web Push related parameters from the initialization section will be ignored. If one of the following Web Push related functions of the SDK will be called, an exception will be thrown:

subscribe
unsubscribe
isSubscribed
customEvent

Methods

`subscribe`

This method is used to request a user’s permission for push notifications. If a user is already subscribed, the method will just return.

If a user did not yet grant the allowance for push notifications:

The browsers permission dialog will be triggered to ask the user
If the user grants the permission for getting push notifications the callback onSubscribe will be invoked.

function subscribe (): Promise<void>;

Returns

void

Throws

The function throws an error if it is called when the SDK feature "Mobile Inbox" is active.

`unsubscribe`

This method will remove a user from receiving push notifications. For this purpose the stored push token of the user will be removed from the local storage as well as from the backend and the related subscription will be invalidated.

Invokes the onUnsubscribe callback when the execution was successful.

function unsubscribe (): Promise<void>;

Returns

void

Throws

The function throws an error if it is called when the SDK feature "Mobile Inbox" is active.

`isSubscribed`

Returns a boolean indication if the web browser and user is fully registered. This is the case if

The user granted the allowance for receiving push notifications (has a push token),
the browser is registered in our backend

function isSubscribed (): Promise<boolean>;

Returns

A boolean indication for the subscription status

Throws

The function throws an error if it is called when the SDK feature "Mobile Inbox" is active.

`login`

Binds a specific contact using a given contact field ID and contact field value to the browser.

Parameters

contactInfo: The optional contact information. If omitted, the browser will be linked to the so called anonymous contact.

function login (contactInfo?: Omit<ContactInfo, 'encrypted'>): Promise<boolean>;

type ContactInfo = {
  fieldId: number,
  fieldValue: string,
  encrypted: boolean
}

Returns

true if the login was successful, false otherwise.

`setOpenIdAuthenticatedContact`

Binds a specific contact using a given contact field ID and id-token to the browser. The id-token will be validated on the server-side.

Parameters

contactInfo: object containing the fieldId as well as the id-token from the open-id authentication.

function login (contactInfo?: OpenIdContactInfo): Promise<boolean>;

type OpenIdContactInfo = {
  fieldId: number,
  openIdToken: string
}

Returns

true if successful, false otherwise.

`logout`

Binds the anonymous contact to the browser.

function logout (): Promise<boolean>;

Returns

true if the login was successful, false otherwise.

`getClientId`

Returns the unique ID assigned to the client.

This method may only be used after the SDK has been fully initialized.

Only use the client ID from the point of view of a unique ID. Never rely on the IDs structure itself as it is subject to change.

function getClientId (): Promise<string | undefined>;

Returns

The client ID as a string or undefined in case of improper use.

`getLoggedInContact`

Returns the information about the contact which is currently linked to the browser. The data itself is encrypted, so the presence of the contact info just indicates that "someone" is logged in.

function getLoggedInContact (): Promise<ContactInfo | {} | undefined>;

type ContactInfo = {
  fieldId: number | string,
  fieldValue: string,
  encrypted: boolean
}

Returns

The ContactInfo consisting of the fieldId, fieldValue and the encrypted flag, which indicates if the fieldId and fieldValue are encrypted.
an empty object {} if the anonymous contact is linked or
undefined if there is neither a user nor the anonymous contact linked to the browser.

`isLoggedIn`

Returns a boolean indication if the user is logged-in.

function isLoggedIn(): Promise<boolean>;

Returns

True if the user is logged in, false otherwise

`registerClient`

This function can be used to manually register the client with the backend and linking it either to the anonymous contact (no contactInfo is passed) or an identified contact if a proper contactInfo is passed (the field ID and field value of this contact).

The function is helpful if you just want to register the browser/client in order to be able to send events to the backend without having the permission for sending web push notifications.

Ensure that you got the consent of the user before you use this function and send events to the backend.

function registerClient (contactInfo?: Omit<ContactInfo, 'encrypted'>): Promise<boolean>;

type ContactInfo = {
  fieldId: number,
  fieldValue: string,
  encrypted: boolean
}

Returns

true if the registration was successful, false otherwise.

`customEvent`

This function can be used to report a custom event to the backend. Every custom event consists of a name and optional event attributes. The attributes have to be given as an object in JSON format (key/value).

type MEEventAttributes = { [key: string]: string }

public async customEvent (name: string, attributes?: MEEventAttributes): Promise<boolean>;

Returns

The method returns a promise which resolves to a boolean which indicates the success of the sending of the custom event to the backend.

Throws

The function throws an error if it is called when the SDK feature "Mobile Inbox" is active.

Example

const result = await customEvent('addedSomething', { what: 'vanilla', where: 'soup', id: '73627263' });
// or without attributes:
const result = await customEvent('leftPage');

`getInboxItems`

This function can be used (if the Mobile Inbox feature is enabled) for fetching all inbox items for the currently logged in user.

type InboxItemProperties = { [key: string]: string }
type InboxItem = {
  id: string
  title: string
  body: string
  imageUrl?: string
  imageAltText?: string
  receivedAt: number
  updatedAt: number
  expiresAt?: number
  collapseId?: string
  tags?: string[]
  properties?: InboxItemProperties
}
type InboxItems = InboxItem[]

public async getInboxItems (): Promise<InboxItems | undefined>;

Returns

The method returns a promise which resolves either to an array of InboxItem or undefined in case any kind of error.

Throws

The function throws an error if it is called when the SDK feature "Web Push" is active.

Example

const result = await getInboxItems();

`push`

This function can be used to register a callback function for specific events which are triggered by the SDK. For the description of the SdkCommand please refer to the Event Listeners section.

function push (sdkCommand: SdkCommand): void;

Event Listeners

As already mentioned in the [API] section there are several events which are triggered by the SDK. For those events it is possible to register a callback function.

To register a callback function you have to use the public push method of the SDK and you should register all of your callbacks in a <script> part which is placed at the end of your HTML.

type HandlerFn = (params?: any) => any
type SdkOnReadyCallback = HandlerFn
type SdkInitCallback = ['init', IInitParams]
type MeWebSdkEvent = 'onReady' | 'onSubscribe' | 'onUnsubscribe' | 'onSWInitError'
  | 'onPermissionPrompt' | 'onPermissionDenied' | 'onPermissionGranted'
type MeWebSdkEventCallback = [MeWebSdkEvent, HandlerFn]
type SdkCommand = SdkInitCallback | SdkOnReadyCallback | MeWebSdkEventCallback

function push (sdkCommand: SdkCommand): void;

`init`

Is invoked once after the web page itself and the SDK code is fully loaded. The init callback itself is part of the SDK. What needs to be passed to the push method are the initialization parameters. See [Integration] for usage.

type SdkInitCallback = ['init', IInitParams]
type SdkCommand = SdkInitCallback | ...

function push (sdkCommand: SdkCommand): void;

`onReady`

This callback is invoked after the SDK has been fully initialized. You can register the desired callback by passing a function to the push method or use the same approach which has to be used for all other supported events. E.g. place at the end of your HTML file something like this to register the callback which shall be invoked once the SDK is fully initialized:

<script>
  WebEmarsysSdk.push(function() {
    console.log('EVENT: onReady');
    // do whatever you need to do after the SDK is ready
  });
  // further event handler registrations...
</script>

Further Events

All callbacks for events listed in this section have to be registered by passing an array object to the push method, which consists of the event name and the callback function. E.g.:

<script>
  // ...
  WebEmarsysSdk.push(['onPermissionPrompt', function() {
    console.log('EVENT: onPermissionPrompt');
  }]);
</script>

onSubscribe: Invoked when the browser is registered with our backend and we have a push token and a user is linked to the browser.
onUnsubscribe: Invoked after the successful execution of unsubscribe.
onSWInitError: Invoked in case there was an error detected during the registration of the service worker (SW).
onPermissionPrompt: Invoked when it is necessary to prompt the user for allowance of push notifications.
onPermissionDenied: Invoked when the user generally denied reception of push notifications.
onPermissionGranted: Invoked when the user granted the reception of push notifications.