CRM Module

The CRM Module provides functionality for managing web push notifications and in-app notifications in the Gamanza Engage Web Client SDK. It allows developers to register players for web push notifications, manage notification permission requests, and handle OneSignal in-app push notifications.

Accessing the Module

The CrmModule is initialized internally by the SDK and should not be instantiated directly. It's accessible through the main SDK instance.

// Example of accessing the CrmModule through the SDK
const { Crm } = GamanzaEngageWebClientSDK.getInstance();

Methods

playerRegisterWebPushSubscription

Registers the current authenticated player for Web Push Notifications powered by Gamanza Engage CRM. This function registers the service worker, validates if the player user agent supports push, and additionally validates if the permissions for Notifications have been granted or denied.

Signature:

playerRegisterWebPushSubscription(): Promise<{
  status: WebPushSubscriptionRequestStatus;
}>

Returns:

Type	Description
Promise<{ status: WebPushSubscriptionRequestStatus }>	A promise that resolves to an object containing the status of the web push subscription request.

Example:

// Register for web push notifications
const handleRequestPermissionsClick = async (evt) => {
  evt.preventDefault();
  // This call displays the native user agent push notifications permissions request
  const result = await Crm.playerRegisterWebPushSubscription();
  if (result.status === WebPushSubscriptionRequestStatus.SUCCESS) {
    alert('Congratulations, you are subscribed to receive Push Notifications');
  } else if (result.status === WebPushSubscriptionRequestStatus.WEB_PUSH_NOT_SUPPORTED) {
    alert('Web Push Notifications are not supported in this browser');
  } else if (result.status === WebPushSubscriptionRequestStatus.WEB_PUSH_PERMISSION_DENIED) {
    alert('Permission to receive notifications was denied');
  }
};

// Attach to a button click event
document.getElementById('notification-permission-btn').addEventListener('click', handleRequestPermissionsClick);

Notes:

• For Safari, the request needs to be behind a user interaction. When the user completes the gesture, call the push subscription method immediately from the gesture's event handler code.
• For requirements, check the Web Push Configuration documentation.

shouldShowNotificationRequestPermissionsBanner

Helper function to allow you to decide when to show the permissions request banner for Web Push Notifications. This is particularly useful for Safari, where the push subscription method must be called immediately from a user gesture's event handler code.

Signature:

shouldShowNotificationRequestPermissionsBanner(days: number = 30, override: boolean = true): Promise<boolean>

Parameters:

Name	Type	Default	Description
days	number	30	Number of days to wait before showing the banner again. The system stores this value in persistent storage.
override	boolean	true	Defines if you want to write in the persistence storage the next time the function should return true for the current player.

Returns:

Type	Description
Promise<boolean>	A promise that resolves to a boolean indicating whether the notification request permissions banner should be shown.

Example:

Automatic check and override the next check:

// Check if we should show the notification permissions banner
if (await Crm.shouldShowNotificationRequestPermissionsBanner(5)) {
  // Display the banner in the UI
  showNotificationBanner();
}

Control override in persistence:

// Check if we should show the banner without updating the persistence
if (await Crm.shouldShowNotificationRequestPermissionsBanner(5, false)) {
  // Display the banner in the UI
  showNotificationBanner();
}

// Handler for player closing the banner
const onCloseBannerClick = async (evt) => {
  evt.preventDefault();
  hideNotificationBanner();
  
  // Update the next time the banner should be displayed to 5 days
  await Crm.shouldShowNotificationRequestPermissionsBanner(5, true);
};

playerOneSignalInAppPushNotificationsSubscription

Registers the current authenticated player for OneSignal In-App Push Notifications. This method allows registering a player to receive push notifications through OneSignal within the application.

Signature:

playerOneSignalInAppPushNotificationsSubscription(subs: OneSignalInAppNotificationSubscription): Promise<SimpleResponse<null>>

Parameters:

Name	Type	Description
subs	OneSignalInAppNotificationSubscription	The OneSignal subscription details.

Returns:

Type	Description
Promise<SimpleResponse<null>>	A promise that resolves to a SimpleResponse object indicating success or failure of the registration.

Example:

const subscription = {
  appId: "your-onesignal-app-id",
  subscriptionId: "subscription-id",
  playerId: "player-id",
  deviceType: "web",
  oneSignalId: "onesignal-id"
};

const result = await Crm.playerOneSignalInAppPushNotificationsSubscription(subscription);
if (result.ok) {
  console.log("Successfully registered for OneSignal notifications");
} else {
  console.error("Failed to register for OneSignal notifications:", result.error);
}

Related Interfaces

OneSignalInAppNotificationSubscription

Interface representing the subscription details for OneSignal In-App Push Notifications.

type OneSignalInAppNotificationSubscription = {
  appId: string;
  subscriptionId: string;
  playerId: string;
  deviceType: string;
  oneSignalId: string;
};

Property	Type	Description
appId	string	The OneSignal application ID
subscriptionId	string	The OneSignal subscription identifier
playerId	string	The player's unique identifier
deviceType	string	The type of device being registered
oneSignalId	string	The OneSignal unique identifier

SimpleResponse

Generic interface representing a simple response from the API.

interface SimpleResponse<T> {
  ok: boolean;
  error?: ErrorResponse;
  data: T | null;
}

Property	Type	Description
ok	boolean	Indicates if the operation was successful
error	ErrorResponse (optional)	Error details if the operation failed
data	T | null	The response data (null in this case of OneSignal registration)

ErrorResponse

Interface representing an error response from the API.

interface ErrorResponse {
  message: string;
  details: {
    faultCode: number;
    fields: {
      field: string;
      error: string;
    }[];
  };
  request: {
    xRequestId: string;
    method: string;
    headers: Record<string, string>[];
  };
  timestamp: string;
}

Property	Type	Description
message	string	Error message
details.faultCode	number	Numeric code identifying the error
details.fields	Array	List of field-specific errors
details.fields[].field	string	Name of the field with an error
details.fields[].error	string	Error message for the field
request.xRequestId	string	Request identifier
request.method	string	HTTP method used for the request
request.headers	Array	Request headers
timestamp	string	Timestamp when the error occurred

WebPushSubscriptionRequestStatus

Enum representing the possible status values returned by the playerRegisterWebPushSubscription method.

enum WebPushSubscriptionRequestStatus {
  SUCCESS = 'SUCCESS',
  ALREADY_GRANTED = 'ALREADY_GRANTED',
  MISSING_SERVICE_WORKER = 'MISSING_SERVICE_WORKER',
  WEB_PUSH_NOT_SUPPORTED = 'WEB_PUSH_NOT_SUPPORTED',
  WEB_PUSH_PERMISSION_DENIED = 'WEB_PUSH_PERMISSION_DENIED',
  WEB_PUSH_PERMISSION_CANCELLED = 'WEB_PUSH_PERMISSION_CANCELLED',
  ERROR = 'ERROR',
}

Value	Description
SUCCESS	The player has successfully registered for web push notifications.
ALREADY_GRANTED	The player has already granted permission for web push notifications.
MISSING_SERVICE_WORKER	The service worker required for web push notifications is missing.
WEB_PUSH_NOT_SUPPORTED	Web push notifications are not supported in the current browser.
WEB_PUSH_PERMISSION_DENIED	The player has denied permission for web push notifications.
WEB_PUSH_PERMISSION_CANCELLED	The player cancelled the permission request for web push notifications.
ERROR	An error occurred during the web push subscription process.

OnsiteVariantEnum

Enum representing the different display variants for onsite notifications.

enum OnsiteVariantEnum {
  DEFAULT = 'DEFAULT',
  TITLE = 'TITLE',
  IMAGE_TOP = 'IMAGE_TOP',
  IMAGE_RIGHT = 'IMAGE_RIGHT',
  IMAGE_LEFT = 'IMAGE_LEFT',
}

Value	Description
DEFAULT	Default display variant for onsite notifications.
TITLE	Title-only display variant for onsite notifications.
IMAGE_TOP	Display variant with image at the top for onsite notifications.
IMAGE_RIGHT	Display variant with image on the right for onsite notifications.
IMAGE_LEFT	Display variant with image on the left for onsite notifications.

AnalyticsTrackingType

Enum representing the different types of analytics tracking.

enum AnalyticsTrackingType {
  DELIVERED = 'DELIVERED',
  OPENED = 'OPENED',
  CLICKED = 'CLICKED',
  ERROR = 'ERROR',
}

Value	Description
DELIVERED	Tracking for when a notification is delivered.
OPENED	Tracking for when a notification is opened.
CLICKED	Tracking for when a notification is clicked.
ERROR	Tracking for when an error occurs with a notification.

AnalyticsTrackingChannel

Enum representing the different channels for analytics tracking.

enum AnalyticsTrackingChannel {
  ON_SITE = 'ON_SITE',
  WEB_PUSH = 'WEB_PUSH',
}

Value	Description
ON_SITE	Analytics tracking for onsite notifications.
WEB_PUSH	Analytics tracking for web push notifications.

OnSiteNotificationEventData

Interface for onsite notification event data.

interface OnSiteNotificationEventData extends BaseEventData {
  msg: {
    type: OnsiteVariantEnum;
    contentHtml: string;
    language: string;
  };
  playerId: string;
}

Property	Type	Required	Description
msg	{ type: OnsiteVariantEnum; contentHtml: string; language: string; }	Yes	Message content for the onsite notification.
msg.type	OnsiteVariantEnum	Yes	Display variant for the onsite notification.
msg.contentHtml	string	Yes	HTML content for the onsite notification.
msg.language	string	Yes	Language of the onsite notification content.
playerId	string	Yes	ID of the player receiving the notification.

AnalyticsTrackingEventEmitter

Interface for analytics tracking event emitters.

interface AnalyticsTrackingEventEmitter {
  message: InternalRawEvent<'messageGateway:on:sendOnSiteNotification'>;
  trackingType: AnalyticsTrackingType;
  channel: AnalyticsTrackingChannel;
  errorDetail?: {
    code: string;
    description?: string;
    metadata: Record<string, unknown>;
  };
}

Property	Type	Required	Description
message	InternalRawEvent<'messageGateway:on:sendOnSiteNotification'>	Yes	The message event being tracked.
trackingType	AnalyticsTrackingType	Yes	The type of tracking (DELIVERED, OPENED, CLICKED, ERROR).
channel	AnalyticsTrackingChannel	Yes	The channel being tracked (ON_SITE, WEB_PUSH).
errorDetail	{ code: string; description?: string; metadata: Record<string, unknown>; }	No	Details about any error that occurred.
errorDetail.code	string	Yes	A unique error code to identify the problem (e.g., PUSH_001).
errorDetail.description	string	No	A human-readable description of the error to be displayed in the Analytics UI.
errorDetail.metadata	Record<string, unknown>	Yes	General error information in a more technical way for internal audit.