@allboatsrise/expo-marketingcloudsdk

This is an Expo module that provides a wrapper around the Salesforce Marketing Cloud SDK for iOS and Android.

It allows Expo-based apps to integrate with the Marketing Cloud SDK.

Installation

To install the package use your preferred package manager:

npm install @allboatsrise/expo-marketingcloudsdk expo-notifications zod

or

yarn add @allboatsrise/expo-marketingcloudsdk expo-notifications zod

Plugin setup

View parameters

Add package to plugins in app.js/app.config.js with minimal configuration.

"expo": {
  "plugins": [
    [
      "@allboatsrise/expo-marketingcloudsdk", {
        "appId": "<< MARKETING_CLOUD_APP_ID >>",
        "accessToken": "<< MARKETING_CLOUD_ACCESS_TOKEN >>",
        "serverUrl": "<< MARKETING_CLOUD_SERVER_URL >>",
      }
    ],
    "expo-notifications"
    ]
}

Sample initialization of notifications in the app

import * as Notifications from 'expo-notifications'
import * as MarketingCloud from '@allboatsrise/expo-marketingcloudsdk'

// ensure push notifications appear regardless whether app is active or not
Notifications.setNotificationHandler({
  handleNotification: async (_notification) => {
    return {
      shouldShowAlert: true,
      shouldPlaySound: true,
      shouldSetBadge: true,
    }
  },
})

export const App: React.FC = () => {
  useEffect(() => {
    let cleanup = () => {}

    ;(async () => {
      // request push notifications permission on load
      // ideally: show this elsewhere where it's more relevant instead of as soon as when the ap loads
      let result = await Notifications.getPermissionsAsync()
      if (!result.granted && result.canAskAgain) {
        result = await Notifications.requestPermissionsAsync({
          ios: {
            allowAlert: true,
            allowBadge: true,
            allowSound: true,
          },
        })
      }

      if (!result.granted) return

      const token = await Notifications.getDevicePushTokenAsync()

      // let Marketing Cloud SDK the value of current push token
      MarketingCloud.setSystemToken(token.data)

      // In rare situations a push token may be changed by the push notification service while the app is running.
      const subscription = Notifications.addPushTokenListener((newToken) => {
        MarketingCloud.setSystemToken(newToken.data)
      })
      cleanup = () => subscription.remove()
    })()

    return () => cleanup()
  }, [])

  // remaining app logic...
}

Plugin parameters

| Parameter | Type | Required | Description | | --------------------------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | appId | string | Yes | Marketing Cloud app id | | accessToken | string | Yes | Marketing Cloud access token | | serverUrl | string | Yes | Marketing Cloud server url | | senderId (Android only) | string | No | Marketing Cloud FCM sender id. Defaults to project_info.project_number defined in android.googleServicesFile (google-services.json) if defined. | | mid | string | No | Sets the configuration value to use for the Salesforce MarketingCloud Tenant Specific mid. | | inboxEnabled | boolean | No | Sets the configuration flag that enables or disables inbox services | | locationEnabled | boolean | No | Sets the configuration flag that enables or disables location services | | analyticsEnabled | boolean | No | Sets the configuration flag that enables or disables Salesforce MarketingCloud Analytics services | | applicationControlsBadging | boolean | No | Sets the configuration value which enables or disables application control over badging | | delayRegistrationUntilContactKeyIsSet | boolean | No | Sets the configuration value which enables or disables application control over delaying SDK registration until a contact key is set | | markNotificationReadOnInboxNotificationOpen | boolean | No | Sets the configuration value which enables or disables marking inbox notifications as read on open | | debug | boolean | No | Enable logging debug messages |

Usage

Various functions, their parameters, return values, and their specific purposes in ExpoMarketingCloudSdk

Functions

| Function Name | Parameters | Return Type | Description | | --- | --- | --- | --- | | isPushEnabled | None | Promise<boolean> | Returns a promise that resolves to a boolean indicating whether push notifications are enabled for the user. | | enablePush | None | Promise<void> | Returns a promise that resolves when push notifications have been successfully enabled. | | disablePush | None | Promise<void> | Returns a promise that resolves when push notifications have been successfully disabled. | | getSystemToken | None | Promise<string> | Returns a promise that resolves to a string representing the device's push notification token. | | setSystemToken | token: string | Promise<void> | Returns a promise that resolves when the device's push notification token has been successfully set. | | getAttributes | None | Promise<Record<string, string>> | Returns a promise that resolves to an object representing the user's attributes. | | setAttribute | key: string, value: string | Promise<void> | Returns a promise that resolves when an attribute has been successfully set for the user. | | clearAttribute | key: string | Promise<void> | Returns a promise that resolves when an attribute has been successfully cleared for the user. | | addTag | tag: string | Promise<void> | Returns a promise that resolves when a tag has been successfully added for the user. | | removeTag | tag: string | Promise<void> | Returns a promise that resolves when a tag has been successfully removed for the user. | | getTags | None | Promise<string[]> | Returns a promise that resolves to an array of strings representing the user's tags. | | setContactKey | contactKey: string | Promise<void> | Returns a promise that resolves when the user's contact key has been successfully set. | | getContactKey | None | Promise<string> | Returns a promise that resolves to a string representing the user's contact key. | | getSdkState | None | Promise<Record<string, unknown>> | Returns a promise that resolves to an object representing the current state of the SDK. | | track | name: string, attributes: Record<string, string> | Promise<void> | Returns a promise that resolves when a custom event has been successfully tracked. | | deleteMessage | messageId: string | Promise<void> | Returns a promise that resolves when a specific inbox message has been successfully deleted. | | getDeletedMessageCount | None | Promise<number> | Returns a promise that resolves to a number representing the total number of deleted inbox messages. | | getDeletedMessages | None | Promise<InboxMessage[]> | Returns a promise that resolves to an array of InboxMessage objects representing the deleted inbox messages. | | getMessageCount | None | Promise<number> | Returns a promise that resolves to a number representing the total number of inbox messages. | | getMessages | None | Promise<InboxMessage[]> | Returns a promise that resolves to an array of InboxMessage objects representing the inbox messages. | | getReadMessageCount | None | Promise<number> | Returns a promise that resolves to a number representing the total number of read inbox messages. | | getReadMessages | None | Promise<InboxMessage[]> | Returns a promise that resolves to an array of InboxMessage objects representing the read inbox messages. | | trackMessageOpened | messageId: string | Promise | Returns a promise that resolves to true when inbox open event successfully triggered on message. | | isAnalyticsEnabled | None | Returns a promise that resolves to a boolean indicating whether analytics are enabled for the user. | | enableAnalytics | None | Promise<void> | Returns a promise that resolves when analytics have been successfully enabled. | | disableAnalytics | None | Promise<void> | Returns a promise that resolves when analytics have been successfully disabled. |

Add event listener

Available event listeners:

| Function | Parameters | Description | | --- | --- | --- | | addLogListener | listener: (event: LogEventPayload) => void | Adds a listener function to the onLog event, which is triggered when a new log event is generated. | | addInboxResponseListener | listener: (event: InboxResponsePayload) => void | Adds a listener function to the onInboxResponse event, which is triggered when a new inbox response is received. | | addRegistrationResponseSucceededListener | listener: (event: RegistrationResponseSucceededPayload) => void | Adds a listener function to the onRegistrationResponseSucceeded event, which is triggered when SDK successfully registers with backend. |

// listeners being used in a useEffect hook.

useEffect(() => {
    const logSubscription = addLogListener((logEvent: LogEventPayload) => {
        // Do something with logEvent
      })

    const inboxSubscription = addInboxResponseListener((inboxEvent: InboxResponsePayload) => {
        // Do something with inboxEvent
      })

    const registrationSubscription = MarketingCloud.addRegistrationResponseSucceededListener((registrationEvent: RegistrationResponseSucceededPayload) => {
      // Do something with registrationEvent
    })

    return () => {
      logSubscription.remove()
      inboxSubscription.remove()
      registrationSubscription.remove()
    }
}, [])