Expo SDK 设置

概述

要求

一个托管的 Expo 应用。对于原生 React Native 应用，请参阅 React Native SDK setup。
Expo SDK 48+（说明使用版本 52.0.43）
EAS CLI（EAS Build 文档）
React Native 0.71+（说明使用版本 0.78.2）
已配置的 OneSignal 应用和平台

iOS 要求

带有 Xcode 14+ 的 macOS（设置说明使用 Xcode 16.2）
iOS 12+、iPadOS 12+ 设备或运行 iOS 16.2+ 的 Xcode 模拟器
CocoaPods 1.16.2+

Android 要求

安装了 Google Play 商店（服务）的 Android 7.0+ 设备或模拟器

配置您的 OneSignal 应用和平台

推送通知所需设置 要开始使用 OneSignal 发送推送通知，您必须首先为您支持的所有平台配置 OneSignal 应用——Apple (APNs)、Google (FCM)、华为 (HMS) 和/或 Amazon (ADM)。

如果您的组织已有 OneSignal 账户，请要求邀请您为管理员角色以配置应用。否则，请注册免费账户以开始使用。

配置 OneSignal 应用的分步说明。

您可以在单个 OneSignal 应用下管理多个平台（iOS、Android、华为、Amazon、Web）。

创建或选择您的应用

要向现有应用添加平台，请在 OneSignal 控制台中转到 设置 > 推送和应用内。
要重新开始，请点击 新应用/网站 并按照提示操作。

示例显示创建新应用。

设置并激活平台

为您的应用和组织选择一个清晰且易识别的名称。
选择您要配置的平台（iOS、Android 等）。
点击 下一步：配置您的平台。

设置首个 OneSignal 应用、组织和频道的示例。

配置平台凭据

根据您的平台按照提示操作：

输入您的凭据后点击 保存并继续。

选择目标 SDK

选择与您的开发平台匹配的 SDK（例如，iOS、Android、React Native、Unity），然后点击 保存并继续。

选择您正在使用的 SDK 以导航到文档。

安装 SDK 并保存您的应用 ID

配置好您的平台后，将显示您的 OneSignal 应用 ID。复制并保存此 ID——在安装和初始化 SDK 时您将需要它。如果与他人协作，请使用邀请按钮添加开发人员或团队成员，然后点击完成以完成设置。

保存您的应用 ID 并邀请其他团队成员。

完成后，请遵循您所选平台的 SDK 安装指南以完成 OneSignal 集成。

SDK 设置

1. 添加 SDK

使用 Expo CLI 安装 OneSignal Expo 插件。

npm

npx expo install onesignal-expo-plugin

将 react-native-onesignal 包添加到您的项目中。

  npm install --save react-native-onesignal

2. 配置插件

打开您的 app.json（或 app.config.js）。在 plugins 数组中，您应该看到 "onesignal-expo-plugin"。配置所需的插件属性：

json

  {
    "expo": {
      "ios": {
        "bundleIdentifier": "com.yourcompany.yourapp", // ✅ Required for iOS builds
        "infoPlist": {
          "UIBackgroundModes": ["remote-notification"] // ✅ 推送通知所需
        },
        "entitlements": {
          "aps-environment": "development", // ✅ 推送通知所需，对于 Testflight 和 App Store 构建改为 "production"
          "com.apple.security.application-groups": [
            "group.${ios.bundleIdentifier}.onesignal" // // ✅ 确认交付所需
          ]
        }
      },
      "android": {
        "package": "com.yourcompany.yourapp" // ✅ Required for Android builds
      },
      "plugins": [
        [
          "onesignal-expo-plugin",
          {
            "mode": "development"
          }
        ]
      ]
    }
  }

确保将插件 [onesignal-expo-plugin] 添加到插件数组的前面。它应该是数组中的第一个插件。这将防止 OneSignal/OneSignal.h file not found 错误。

额外的插件属性。

Prop	Required	Description
`mode`	✅	Configures the APNs environment entitlement. Use `"development"` for testing and switch to `"production"` for TestFlight and App Store builds.
`devTeam`	❌	Your Apple Team ID, found by running `expo credentials:manager` (e.g., `"91SW8A37CR"`).
`iPhoneDeploymentTarget`	❌	设置应用支持的最低 iOS 版本。应与 Podfile 中的值匹配（例如，`"15.0"`）。
`smallIcons`	❌	Android 小通知图标路径数组（白色、透明、96x96px）。这些图像将自动缩放。示例：`["./assets/ic_stat_onesignal_default.png"]`
`largeIcons`	❌	Android 大通知图标路径数组（白色、透明、256x256px）。示例：`["./assets/ic_onesignal_large_icon_default.png"]`
`smallIconAccentColor`	❌	用作 Android 通知图标强调色的十六进制颜色值。示例：`"#FF0000"`
`iosNSEFilePath`	❌	您的自定义 iOS 通知服务扩展 Objective-C 文件的路径。示例：`"./assets/NotificationService.m"`

3. Initialize SDK

根据您的 Expo 结构（传统应用入口或 Expo Router），按照这些选项初始化 OneSignal。

传统应用入口
Expo 路由器

在您的 App.tsx 或 App.js 文件中使用提供的方法初始化 OneSignal。Replace YOUR_APP_ID with your OneSignal App ID found in your OneSignal dashboard Settings > Keys & IDs.

If you don’t have access to the OneSignal app, ask your Team Members to invite you.

App.tsx

import React, { useEffect } from 'react';
// Include the OneSignal package
import { OneSignal, LogLevel } from 'react-native-onesignal';

export default function App(): React.JSX.Element {
  // 在 useEffect 中初始化 OneSignal 以确保它只运行一次
  useEffect(() => {
    // 启用详细日志记录用于调试（在生产环境中移除）
    OneSignal.Debug.setLogLevel(LogLevel.Verbose);
    // Initialize with your OneSignal App ID
    OneSignal.initialize('YOUR_APP_ID');
    // 使用此方法提示推送通知。
    // 我们建议在测试后移除此方法，而是使用应用内消息提示通知权限。
    OneSignal.Notifications.requestPermission(false);
  }, []); // 确保这只在应用安装时运行一次
}

查看我们的 OneSignal Expo Plugin GitHub 仓库以获取更多配置选项、更复杂的设置说明或提出问题。我们的 SDK 是开源的，欢迎提交 PR！

Android 设置

确保您的 OneSignal 应用已使用您的 Firebase 凭据为 Android 平台进行配置。设置您的通知图标以匹配您的应用品牌。如果跳过此步骤，推送通知将显示默认的铃铛图标。 为 Android 构建 此时，您应该能够在物理 Android 设备或模拟器上无问题地构建和运行您的应用。

确认您的 Android 构建正常工作后：

如果适用，继续进行 iOS 设置。
或者跳转到测试 OneSignal SDK 集成。

iOS setup

确保您的 OneSignal 应用已配置为使用 p8 令牌（推荐）或 p12 证书的 iOS 平台。

这应该使用您的 EAS 配置中相同的凭据设置。

iOS 构建

您现在应该能够在真实的 iOS 设备或 iOS 模拟器（16.2+）上构建并运行您的应用。

Common iOS build errors

循环内部...构建可能产生不可靠结果。

在使用 Xcode 15+ 构建时您可能会看到此错误，这是由于影响跨平台系统的默认配置更改。

在 Xcode 中打开您的 .xcworkspace 文件夹，并导航到 您的应用目标 > Build Phases。
您应该有一个名为 “Embed Foundation Extensions” 或 “Embed App Extensions” 的阶段。
拖动并移动此构建阶段到 “Run Script” 之_上_。
构建并运行您的应用。错误应该得到解决。

Xcode 中 Build Phases 的正确顺序。

取消勾选仅在安装时复制。

PBXGroup 错误

RuntimeError - PBXGroup attempted to initialize an object with unknown ISA PBXFileSystemSynchronizedRootGroup from attributes:

{"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}

Fix:

找到错误中 “path” 下列出的文件夹
In Xcode project sidebar, right-click the folder
Select Convert to Group

PBXGroup 的路径错误。

将文件夹转换为组。

确认您的 iOS 构建工作正常后，继续进行测试 OneSignal SDK 集成。

测试 OneSignal SDK 集成

本指南帮助您通过测试推送通知、订阅注册和应用内消息来验证 OneSignal SDK 集成是否正常工作。

检查移动端订阅

在测试设备上启动您的应用。

如果您在初始化时添加了 requestPermission 方法，原生推送权限提示应该会自动出现。

iOS 和 Android 推送权限提示

检查您的 OneSignal 控制台

在接受提示之前，请检查 OneSignal 控制台：

转到 受众 > 订阅。
您应该看到一个状态为”从未订阅”的新条目。

控制台显示 '从未订阅' 状态的订阅

返回应用并在提示中点击允许。

刷新 OneSignal 控制台的订阅页面。

订阅状态现在应该显示为已订阅。

控制台显示 '已订阅' 状态的订阅

您已成功创建了移动端订阅。移动端订阅是在用户首次在设备上打开您的应用时创建的，或者在同一设备上卸载并重新安装您的应用时创建的。

设置测试订阅

测试订阅有助于在发送消息之前测试推送通知。

添加到测试订阅。

在控制台中，在订阅旁边，点击选项（三个点）按钮并选择添加到测试订阅。

将设备添加到测试订阅

为您的订阅命名。

为订阅命名，以便您稍后能够在测试订阅标签中轻松识别您的设备。

控制台显示 '为您的订阅命名' 字段

创建测试用户分组。

转到 受众 > 分组 > 新建分组。

为分组命名。

将分组命名为 Test Users（名称很重要，因为稍后会使用到）。

添加测试用户过滤器并点击创建分组。

使用测试用户过滤器创建 'Test Users' 分组

您已成功创建了测试用户分组。现在我们可以测试向这个单独的设备和测试用户组发送消息。

通过 API 发送测试推送

获取您的应用 API 密钥和应用 ID。

在您的 OneSignal 控制台中，转到 设置 > 密钥和 ID。

更新提供的代码。

将下面代码中的 YOUR_APP_API_KEY 和 YOUR_APP_ID 替换为您的实际密钥。此代码使用我们之前创建的 Test Users 分组。

curl -X \
POST --url 'https://api.onesignal.com/notifications' \
 --header 'content-type: application/json; charset=utf-8' \
 --header 'authorization: Key YOUR_APP_API_KEY' \
 --data \
 '{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "name": "Testing basic setup",
  "headings": {
  	"en": "👋"
  },
  "contents": {
    "en": "Hello world!"
  },
  "included_segments": [
    "Test Users"
  ],
  "ios_attachments": {
    "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  },
  "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'

运行代码。

在您的终端中运行代码。

检查图片和确认送达。

如果所有设置步骤都成功完成，测试订阅应该会收到包含图片的通知：

iOS 和 Android 上包含图片的推送通知

图片在折叠的通知视图中会显得很小。展开通知以查看完整图片。

检查确认送达。

在您的控制台中，转到 送达 > 已发送消息，然后点击消息查看统计数据。您应该会看到已确认统计，表示设备收到了推送。

显示确认送达的送达统计

如果您使用的是专业版或更高版本，请滚动到受众活动以查看订阅级别的确认：

受众活动中设备级别的确认送达

您已成功通过我们的 API 向分组发送了通知。

没有收到图片？您的通知服务扩展可能缺失。
没有确认送达？请检查您的应用组设置。
遇到问题？将 API 请求和应用启动从开始到结束的日志复制粘贴到 .txt 文件中。然后将两者都发送给 support@onesignal.com。

发送应用内消息

应用内消息让您可以在用户使用您的应用时与他们进行沟通。

在设备上关闭或将您的应用切换到后台。

这是因为用户必须在新会话开始_之前_满足应用内受众条件。在 OneSignal 中，当用户在应用处于后台或关闭至少 30 秒后重新打开应用时，会开始一个新会话。更多详情，请参阅我们的应用内消息如何显示指南。

创建应用内消息。

在您的 OneSignal 控制台中，导航到 消息 > 应用内 > 新建应用内消息。
找到并选择欢迎消息。
将您的受众设置为我们之前使用的 Test Users 分组。

使用应用内消息定位 'Test Users' 分组

如需要，请自定义消息内容。

应用内欢迎消息的自定义示例

将触发器设置为 '应用打开时'。

安排频率。

在 安排 > 您希望多久显示一次此消息？ 下选择 每次触发条件满足时。

应用内消息安排选项

使消息生效。

点击 使消息生效，这样每次测试用户打开应用时都可以使用该消息。

打开应用并查看消息。

应用内消息生效后，打开您的应用。您应该会看到它显示：

在设备上显示的欢迎应用内消息

没有看到消息？

开始新会话
- 您必须关闭或将应用切换到后台至少 30 秒后再重新打开。这可以确保开始新会话。
- 更多信息，请参阅应用内消息如何显示。
仍在 Test Users 分组中？
- 如果您重新安装或更换了设备，请重新将设备添加到测试订阅并确认它是 Test Users 分组的一部分。
遇到问题？
- 在重现上述步骤时，请遵循获取调试日志。这将生成额外的日志，您可以与 support@onesignal.com 分享，我们将帮助调查正在发生的情况。

您已成功设置 OneSignal SDK 并学习了重要概念，如：

收集订阅，设置测试订阅，以及创建分组。
使用分组和我们的创建消息 API 发送带图片的推送和确认送达。
发送应用内消息。

继续阅读本指南以在您的应用中识别用户并设置其他功能。

用户识别

之前，我们演示了如何创建移动端订阅。现在我们将扩展到使用 OneSignal SDK 在所有订阅（包括推送、电子邮件和短信）中识别用户。我们将涵盖外部 ID、标签、多渠道订阅、隐私和事件跟踪，以帮助您统一用户并跨平台与他们互动。

分配外部 ID

使用外部 ID 通过您后端的用户标识符在设备、电子邮件地址和电话号码之间一致地识别用户。这确保您的消息传递在各个渠道和第三方系统中保持统一（对集成特别重要）。每次您的应用识别用户时，使用我们 SDK 的login 方法设置外部 ID。

OneSignal 为订阅（订阅 ID）和用户（OneSignal ID）生成唯一的只读 ID。当用户在不同设备上下载您的应用、订阅您的网站，和/或在您的应用之外提供电子邮件地址和电话号码时，将创建新的订阅。强烈建议通过我们的 SDK 设置外部 ID，以在用户的所有订阅中识别用户，无论订阅是如何创建的。

添加数据标签

标签是字符串数据的键值对，您可以使用它们来存储用户属性（如 username、role 或偏好）和事件（如 purchase_date、game_level 或用户交互）。标签支持高级消息个性化和分组，允许更高级的用例。在您的应用中发生事件时，使用我们 SDK 的addTag 和 addTags 方法设置标签。在这个示例中，用户达到了第 6 级，可以通过名为 current_level 的标签识别，其值设置为 6。

OneSignal 中带有名为'current_level'标签设置为'6'的用户档案

我们可以创建一个等级在 5 到 10 之间的用户分组，并使用它来发送有针对性的个性化消息：

分组编辑器显示针对 current_level 值大于 4 且小于 10 的用户的分组

屏幕截图显示针对 5-10 级分组发送的个性化推送通知

iOS 和 Android 设备上收到的包含个性化内容的推送通知

添加电子邮件和/或短信订阅

之前我们了解了我们的 SDK 如何创建移动端订阅来发送推送和应用内消息。您还可以通过创建相应的订阅，通过电子邮件和短信渠道联系用户。

使用addEmail 方法创建电子邮件订阅。
使用addSms 方法创建短信订阅。

如果电子邮件地址和/或电话号码在 OneSignal 应用中已存在，SDK 会将其添加到现有用户，不会创建重复项。您可以通过控制台中的 受众 > 用户 或使用查看用户 API查看统一的用户。

通过外部 ID 统一的包含推送、电子邮件和短信订阅的用户档案

多渠道沟通的最佳实践

在添加电子邮件或短信订阅之前获得明确同意。
向用户解释每个沟通渠道的好处。
提供渠道偏好，让用户可以选择他们偏好的渠道。

隐私和用户同意

要控制 OneSignal 何时收集用户数据，请使用 SDK 的同意管控方法：

setConsentRequired(true)：阻止数据收集直到获得同意。
setConsentGiven(true)：一旦获得同意即启用数据收集。

有关更多信息，请参阅我们的隐私和安全文档：

提示推送权限

不要在应用打开时立即调用 requestPermission()，而是采取更策略性的方法。在请求权限之前，使用应用内消息解释推送通知的价值。有关最佳实践和实现细节，请参阅我们的提示推送权限指南。

监听推送、用户和应用内事件

使用 SDK 监听器来响应用户操作和状态变化。 SDK 提供了几个事件监听器供您使用。更多详情请参阅我们的SDK 参考指南。

推送通知事件

addClickListener()：检测通知被点击时。对深度链接有帮助。
addForegroundLifecycleListener()：控制通知在前台的行为方式。

要进行完全自定义，请参阅移动端服务扩展。

用户状态变化

addObserver() 用于用户状态：检测外部 ID 设置时。
addPermissionObserver()：跟踪用户与原生推送权限提示的特定交互。
addObserver() 用于推送订阅：跟踪推送订阅状态变化时。

应用内消息事件

addClickListener()：处理应用内点击操作。适用于深度链接或跟踪事件。
addLifecycleListener()：跟踪应用内消息的完整生命周期（显示、点击、关闭等）。

高级设置和功能

探索更多功能以增强您的集成：

移动端 SDK 设置和参考

通过查看移动端推送设置指南，确保您已启用所有关键功能。有关可用方法和配置选项的完整详细信息，请访问移动端 SDK 参考。

恭喜！您已成功完成移动端 SDK 设置指南。

需要帮助？与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息：

您遇到的问题详情以及复现步骤（如有）
您的 OneSignal 应用 ID
外部 ID 或订阅 ID（如适用）
您在 OneSignal 控制台中测试的消息 URL（如适用）
任何相关的日志或错误信息

我们很乐意为您提供帮助！

开发者文档

移动SDK

网络 SDK

实时活动

桌面和手表设置

旧版 SDK 参考

概述

要求

配置您的 OneSignal 应用和平台

SDK 设置

1. 添加 SDK

2. 配置插件

3. Initialize SDK

Android 设置

iOS setup

iOS 构建

Common iOS build errors

测试 OneSignal SDK 集成

检查移动端订阅

设置测试订阅

通过 API 发送测试推送

发送应用内消息

用户识别

分配外部 ID

添加数据标签

添加电子邮件和/或短信订阅

隐私和用户同意

提示推送权限

监听推送、用户和应用内事件

推送通知事件

用户状态变化

应用内消息事件

高级设置和功能

移动端 SDK 设置和参考

开发者文档

移动SDK

网络 SDK

实时活动

桌面和手表设置

旧版 SDK 参考

​概述

​要求

​配置您的 OneSignal 应用和平台

​SDK 设置

​1. 添加 SDK

​2. 配置插件

​3. Initialize SDK

​Android 设置

​iOS setup

​iOS 构建

​Common iOS build errors

​测试 OneSignal SDK 集成

​检查移动端订阅

​设置测试订阅

​通过 API 发送测试推送

​发送应用内消息

​用户识别

​分配外部 ID

​添加数据标签

​添加电子邮件和/或短信订阅

​隐私和用户同意

​提示推送权限

​监听推送、用户和应用内事件

​推送通知事件

​用户状态变化

​应用内消息事件

​高级设置和功能

​移动端 SDK 设置和参考

概述

要求

配置您的 OneSignal 应用和平台

SDK 设置

1. 添加 SDK

2. 配置插件

3. Initialize SDK

Android 设置

iOS setup

iOS 构建

Common iOS build errors

测试 OneSignal SDK 集成

检查移动端订阅

设置测试订阅

通过 API 发送测试推送

发送应用内消息

用户识别

分配外部 ID

添加数据标签

添加电子邮件和/或短信订阅

隐私和用户同意

提示推送权限

监听推送、用户和应用内事件

推送通知事件

用户状态变化

应用内消息事件

高级设置和功能

移动端 SDK 设置和参考