Skip to content

Commit

Permalink
feat: update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@jennieandersson
jennieandersson committed Oct 25, 2024
1 parent 8e0f2bd commit 172f573
Showing 1 changed file with 58 additions and 52 deletions.
110 changes: 58 additions & 52 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# @allboatsrise/expo-marketingcloudsdk
# @hi3g-access/expo-marketingcloudsdk

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

Expand All @@ -9,14 +9,17 @@ It allows Expo-based apps to integrate with the Marketing Cloud SDK.
To install the package use your preferred package manager:

```bash
npm install @allboatsrise/expo-marketingcloudsdk expo-notifications zod
npm install @hi3g-access/expo-marketingcloudsdk expo-notifications zod
```

or

```bash
yarn add @allboatsrise/expo-marketingcloudsdk expo-notifications zod
yarn add @hi3g-access/expo-marketingcloudsdk expo-notifications zod
```

## Plugin setup

#### [View parameters](#plugin-parameters)

Add package to `plugins` in `app.js`/`app.config.js` with minimal configuration.
Expand All @@ -25,7 +28,7 @@ Add package to `plugins` in `app.js`/`app.config.js` with minimal configuration.
"expo": {
"plugins": [
[
"@allboatsrise/expo-marketingcloudsdk", {
"@hi3g-access/expo-marketingcloudsdk", {
"appId": "<< MARKETING_CLOUD_APP_ID >>",
"accessToken": "<< MARKETING_CLOUD_ACCESS_TOKEN >>",
"serverUrl": "<< MARKETING_CLOUD_SERVER_URL >>",
Expand All @@ -40,7 +43,7 @@ Sample initialization of notifications in the app

```typescript
import * as Notifications from 'expo-notifications'
import * as MarketingCloud from '@allboatsrise/expo-marketingcloudsdk'
import * as MarketingCloud from '@hi3g-access/expo-marketingcloudsdk'

// ensure push notifications appear regardless whether app is active or not
Notifications.setNotificationHandler({
Expand Down Expand Up @@ -106,7 +109,7 @@ export const App: React.FC = () => {
| `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 |
| `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
Expand All @@ -115,64 +118,67 @@ Various functions, their parameters, return values, and their specific purposes

## 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<boolean> | Returns a promise that resolves to true when inbox open event successfully triggered on message. |

| 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<boolean> | Returns a promise that resolves to true when inbox open event successfully triggered on message. |

## 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. |
| 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 logSubscription = addLogListener((logEvent: LogEventPayload) => {
// Do something with logEvent
})

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

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

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


0 comments on commit 172f573

Please sign in to comment.