# @allboatsrise/expo-marketingcloudsdk 中文文档

规范地址：https://npmcn.com/package/%40allboatsrise/expo-marketingcloudsdk/

版本：55\.0\.2
npm 元数据更新时间：2026-11-07T00:48:47.313Z
中文译文更新时间：2026-11-05T21:34:59.330Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40allboatsrise/expo-marketingcloudsdk
原文对照：https://npmcn.com/package/%40allboatsrise/expo-marketingcloudsdk/?lang=original
项目主页：https://github.com/allboatsrise/expo-marketingcloudsdk
源码仓库：https://github.com/allboatsrise/expo-marketingcloudsdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：145 kB，82 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：zod ^4\.0\.0，expo \>=55\.0\.16，expo-notifications \>=55\.0\.20
- 首次发布：2021-12-08T17:45:14.364Z
- 最新版本发布：2026-11-07T00:48:47.125Z
- 近 30 天下载量：17210（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：103（近 12 个月 4 个）

## 中文简介

销售力量营销云SDK的展览模块

## 安装

```sh
npm install @allboatsrise/expo-marketingcloudsdk
```

也可以使用：`pnpm add @allboatsrise/expo-marketingcloudsdk`、`yarn add @allboatsrise/expo-marketingcloudsdk`、`bun add @allboatsrise/expo-marketingcloudsdk`

## README

# @ 所有船只起落/远销云雾克

这是一个世博会模块,它为iOS和Android提供一款环绕销售力量营销云(SFMC)SDK的包装.

它允许基于Expo的应用程序与营销云SDK集成.

## 安装

要安装软件包,请使用您的首选软件包管理器 :

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

或者说

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

## 插件设置

#### [查看参数](https://npmcn.com/package/%40allboatsrise/expo-marketingcloudsdk/#readme-plugin-parameters)

添加软件包到 `plugins` 内 `app.js`编号 :`app.config.js` 最小的配置.

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

应用程序中通知的初始化样本

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

## 插件参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `appId` | 字符串 | 对 | 营销云应用代号 |
| `accessToken` | 字符串 | 对 | 营销云访问符 |
| `serverUrl` | 字符串 | 对 | 营销云服务器 URL |
| `senderId` (仅限机器人) | 字符串 | 没有 | 营销云FCM发件人ID. 默认为 `project_info.project_number` 定义 `android.googleServicesFile` (google-services.json)如果定义的话. |
| `mid` | 字符串 | 没有 | 设置用于销售力营销Cloud租户特定中间的配置值. |
| `inboxEnabled` | 布尔 | 没有 | 设置允许或禁用收件箱服务的配置旗 |
| `locationEnabled` | 布尔 | 没有 | 设置允许或禁用位置服务的配置旗 |
| `analyticsEnabled` | 布尔 | 没有 | 设置允许或禁用销售力量营销的配置旗 |
| `applicationControlsBadging` | 布尔 | 没有 | 设定允许或禁用应用程序控件的配置值 |
| `delayRegistrationUntilContactKeyIsSet` | 布尔 | 没有 | 设置允许或禁用应用程序控制的配置值, 将 SDK 注册延迟到联系人密钥设定 |
| `markNotificationReadOnInboxNotificationOpen` | 布尔 | 没有 | 设置允许或禁用打开时标记收件箱通知的配置值 |
| `debug` | 布尔 | 没有 | 启用日志调试消息 |

# 使用量

各种函数、参数、返回值及其特定目的 `ExpoMarketingCloudSdk`

## 职能

| 函数名称 | 说明 |
| --- | --- |
| `isPushEnabled` | 返回一个解析为布尔的保证, 显示是否为用户启用了按下通知 . |
| `enablePush` | 返回一个在成功启用了按下通知后解答的承诺 . |
| `disablePush` | 返回一个在按下通知成功禁用时解答的诺言 . |
| `getSystemToken` | 返回一个承诺, 以解析一个代表设备的驱动通知符的字符串 . |
| `setSystemToken` | 返回一个在设备的驱动通知符成功设置时解答的保证 . |
| `getAttributes` | 返回一个解析到代表用户属性的对象的许诺. |
| `setAttribute` | 返回一个在为用户成功设定属性时解析的许诺. |
| `clearAttribute` | 返回在成功为用户清除属性时解析的许诺 . |
| `addTag` | 返回一个在成功为用户添加标签时解析的许诺 . |
| `removeTag` | 返回在成功删除用户标签时解析的诺言 . |
| `getTags` | 返回一个解析为代表用户标签的字符串的保证 . |
| `setContactKey` | 返回一个在用户的接触密钥成功设定后解答的承诺 . |
| `getContactKey` | 返回一个表示用户联系密钥的字符串解析的诺言 . |
| `getSdkState` | 返回一个能够解析代表 SDK 当前状态的对象的保证 . |
| `track` | 返回一个自定义事件成功跟踪后解答的诺言 . |
| `deleteMessage` | 返回当特定收件箱消息被成功删除时解答的诺言 . |
| `getDeletedMessageCount` | 返回一个承诺,该承诺将解析给一个代表被删除收件箱总数的数字. |
| `getDeletedMessages` | 返回解析到一系列 `InboxMessage` 代表已删除的收件箱消息的对象. |
| `getMessageCount` | 返回一个承诺,以解析一个代表收件箱消息总数的数字. |
| `getMessages` | 返回解析到一系列 `InboxMessage` 代表收件箱信息的对象. |
| `getReadMessageCount` | 返回一个承诺,以解析一个代表已读收件箱总数的数字. |
| `getReadMessages` | 返回解析到一系列 `InboxMessage` 代表已读收件箱信息的对象. |
| `trackMessageOpened` | 当信箱打开事件成功触发时, 返回解析为真实的诺言 . |
| `isAnalyticsEnabled` | 返回一个解析布尔表示是否为用户启用分析的许诺 . |
| `enableAnalytics` | 返回在成功启用分析后解析的许诺 . |
| `disableAnalytics` | 返回在解析成功禁用时解答的诺言 . |
| `isSfmcNotificationResponse` | 检查通知答复 `NotificationResponse` 原产自SFMC. |
| `extractPayloadFromSfmcNotificationResponse` | 从SFMC通知中提取有效载荷信息. |
| `useLastSfmcNotificationResponse` | 反应钩总是返回最近收到的SFMC通知回复. |

## 添加事件倾听器

可用事件听众 :

| 函数 | 参数 | 说明 |
| --- | --- | --- |
| `addLogListener` | `listener: (event: LogEventPayload) => void` | 将一个收听器函数添加到 `onLog` 事件,在生成新日志事件时触发. |
| `addInboxResponseListener` | `listener: (event: InboxResponsePayload) => void` | 将一个收听器函数添加到 `onInboxResponse` 事件,当收到新的收件箱响应时触发. |
| `addRegistrationResponseSucceededListener` | `listener: (event: RegistrationResponseSucceededPayload) => void` | 将一个收听器函数添加到 `onRegistrationResponseSucceeded` 事件,在 SDK 用后端成功注册时触发. |

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

## 通知回复处理

使用 `useLastSfmcNotificationResponse` 钩键以监听用户与源自 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])
```

替代使用 `isSfmcNotificationResponse` 以检查是否来自 `useLastNotificationResponse` 源自SFMC,然后使用 `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])
```

## 常见问题

### @allboatsrise/expo-marketingcloudsdk 是什么？

销售力量营销云SDK的展览模块

### 如何安装 @allboatsrise/expo-marketingcloudsdk？

在项目目录运行 npm install @allboatsrise/expo-marketingcloudsdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.0\.0）、expo-notifications（\>=55\.0\.20）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @allboatsrise/expo-marketingcloudsdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @allboatsrise/expo-marketingcloudsdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @allboatsrise/expo-marketingcloudsdk 可以商用吗？

@allboatsrise/expo-marketingcloudsdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @allboatsrise/expo-marketingcloudsdk 的下载量有多少？

根据 npm 官方下载统计，@allboatsrise/expo-marketingcloudsdk 在 2026/10/06 – 2026/11/04 这 30 天内被下载 17,210 次，日均约 574 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @allboatsrise/expo-marketingcloudsdk 还在维护吗？

最新版本 55\.0\.2 发布于 2026/11/07（今天）；至今共发布 103 个版本，其中过去 12 个月发布了 4 个；首次发布于 2021/12/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。