@allboatsrise/expo-marketingcloudsdk

This is an Expo module that provides a wrapper around the Salesforce Marketing Cloud (SFMC) 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 | Description | | --- | --- | | isPushEnabled | Returns a promise that resolves to a boolean indicating whether push notifications are enabled for the user. | | enablePush | Returns a promise that resolves when push notifications have been successfully enabled. | | disablePush | Returns a promise that resolves when push notifications have been successfully disabled. | | getSystemToken | Returns a promise that resolves to a string representing the device's push notification token. | | setSystemToken | Returns a promise that resolves when the device's push notification token has been successfully set. | | getAttributes | Returns a promise that resolves to an object representing the user's attributes. | | setAttribute | Returns a promise that resolves when an attribute has been successfully set for the user. | | clearAttribute | Returns a promise that resolves when an attribute has been successfully cleared for the user. | | addTag | Returns a promise that resolves when a tag has been successfully added for the user. | | removeTag | Returns a promise that resolves when a tag has been successfully removed for the user. | | getTags | Returns a promise that resolves to an array of strings representing the user's tags. | | setContactKey | Returns a promise that resolves when the user's contact key has been successfully set. | | getContactKey | Returns a promise that resolves to a string representing the user's contact key. | | getSdkState | Returns a promise that resolves to an object representing the current state of the SDK. | | track | Returns a promise that resolves when a custom event has been successfully tracked. | | deleteMessage | Returns a promise that resolves when a specific inbox message has been successfully deleted. | | getDeletedMessageCount | Returns a promise that resolves to a number representing the total number of deleted inbox messages. | | getDeletedMessages | Returns a promise that resolves to an array of InboxMessage objects representing the deleted inbox messages. | | getMessageCount | Returns a promise that resolves to a number representing the total number of inbox messages. | | getMessages | Returns a promise that resolves to an array of InboxMessage objects representing the inbox messages. | | getReadMessageCount | Returns a promise that resolves to a number representing the total number of read inbox messages. | | getReadMessages | Returns a promise that resolves to an array of InboxMessage objects representing the read inbox messages. | | trackMessageOpened | Returns a promise that resolves to true when inbox open event successfully triggered on message. | | isAnalyticsEnabled | Returns a promise that resolves to a boolean indicating whether analytics are enabled for the user. | | enableAnalytics | Returns a promise that resolves when analytics have been successfully enabled. | | disableAnalytics | Returns a promise that resolves when analytics have been successfully disabled. | | isSfmcNotificationResponse | Check if a notification response NotificationResponse originated from SFMC. | | extractPayloadFromSfmcNotificationResponse | Extract payload info from SFMC notification reponse. | | useLastSfmcNotificationResponse | A React hook that always returns the SFMC notification response that was received most recently. |

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()
    }
}, [])

Notification Response Handling

Use useLastSfmcNotificationResponse hook to listen for last notification that the user interacted with that originated from SFMC.

import { useLastSfmcNotificationResponse } from '@allboatsrise/expo-marketingcloudsdk'

const { response, payload } = useLastSfmcNotificationResponse()

useEffect(() => {
  if (!payload) return

  if (responsePayload.openDirectUrl) {
    // e.g. open url in the browser
  }
}, [payload])

Alternatively use isSfmcNotificationResponse to check if the response from useLastNotificationResponse originated from SFMC and then extract the payload using extractPayloadFromSfmcNotificationResponse

import { useLastNotificationResponse } from 'expo-notifications'
import { isSfmcNotificationResponse, extractPayloadFromSfmcNotificationResponse } from '@allboatsrise/expo-marketingcloudsdk'

const response = useLastNotificationResponse()

useEffect(() => {
  if (!response) return
  if (!isSfmcNotificationResponse(response)) return
  const payload = extractPayloadFromSfmcNotificationResponse(response)
  
  if (responsePayload.openDirectUrl) {
    // e.g. open url in the browser
  }
}, [payload])