@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:

``bash
npm install @allboatsrise/expo-marketingcloudsdk expo-notifications zod
`
or
`bash
yarn add @allboatsrise/expo-marketingcloudsdk expo-notifications zod
`

Plugin setup

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

`json
"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

`typescript
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

| 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. |

`typescript
// 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.

`typescript
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

``typescript
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])