Skip to content

Expo module for Salesforce Marketing Cloud SDK

License

Notifications You must be signed in to change notification settings

allboatsrise/expo-marketingcloudsdk

Repository files navigation

@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

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