概要
これは、OneSignal React NativeとExpo SDKをiOSおよびAndroidアプリに統合するためのステップバイステップガイドです。このガイドの最後には、OneSignalでプッシュ通知とアプリ内メッセージを送信できるようになります。要件
- 管理されたExpoアプリ。ベアReact Nativeアプリについては、React Native SDKセットアップを参照してください。
- Expo 開発ビルド
- Expo SDK 53+(React Native 0.79+)、新アーキテクチャを有効にする必要があります
- EAS CLI(EAS Buildドキュメント)
- 構成されたOneSignalアプリとプラットフォーム
- Xcode 14+を搭載したmacOS(セットアップ手順ではXcode 16.2を使用)
- iOS 12+、iPadOS 12+を搭載したデバイス、またはiOS 16.2+を実行しているXcodeシミュレーター
- CocoaPods 1.16.2+
- Android 7.0+デバイスまたはGoogle Play Store(Services)がインストールされたエミュレーター
配置您的 OneSignal 应用和平台
使用您支持的平台配置您的 OneSignal 应用——Apple (APNs)、Google (FCM)、华为 (HMS) 和/或 Amazon (ADM)。分步设置说明
分步设置说明
创建或选择您的应用

设置您的第一个 OneSignal 应用、组织和频道。
配置平台凭据
- Android:设置 Firebase 凭据
- iOS:p8 令牌(推荐) 或 p12 证书
- Amazon:生成 API 密钥
- 华为:授权 OneSignal
保存您的应用 ID 并安装 SDK

保存您的应用 ID 并邀请其他团队成员。
SDKセットアップ
1. SDKを追加する
Expo CLIを使用してOneSignal Expoプラグインをインストールします。react-native-onesignalパッケージを追加します。
2. プラグインを構成する
app.json(またはapp.config.js / app.config.ts)を開きます。次の設定を含める必要があります。
必須設定
"bundleIdentifier":OneSignalアプリで使用しているp8またはp12認証に一致するアプリのバンドル識別子。"infoPlist":UIBackgroundModesキーを["remote-notification"]に設定する必要があります。"entitlements"aps-environmentキーをテスト用に"development"に、TestflightおよびApp Storeビルド用に"production"に設定する必要があります。com.apple.security.application-groupsキーを["group.${ios.bundleIdentifier}.onesignal"]に設定する必要があります。
"android":packageキーをアプリのパッケージ名に設定する必要があります。"plugins":アプリのplugins配列。プラグイン配列の先頭にプラグイン[onesignal-expo-plugin]を追加する必要があります。また、テスト用にmodeキーを"development"に、TestflightおよびApp Storeビルド用に"production"に設定する必要があります。
追加のプラグインプロパティ。
追加のプラグインプロパティ。
オプション: 位置情報モジュールを無効にする
アプリがOneSignal.Location を使用しない場合は、OneSignal Expo プラグイン props で disableLocation を true に設定します。このオプションには react-native-onesignal 5.5.1 以降が必要です。プラグインはネイティブ依存関係の解決を構成し、react-native-onesignal が位置情報モジュールを除外するようにします。iOS では、プラグインが CocoaPods 解決時に使用される Podfile の環境設定を書き込みます。Android では、プラグインが生成された Gradle properties に onesignal.disableLocation=true を書き込みます。
Podfile で Notification Service Extension または Live Activity widget ターゲットに明示的に OneSignalXCFramework が宣言されている場合は、OneSignalXCFramework/OneSignal や OneSignalXCFramework/OneSignalLiveActivities などのモジュラーサブスペックを使用してください。集約 pod 'OneSignalXCFramework' は OneSignalComplete に解決され、位置情報が含まれます。クリーンな prebuild の後、ios/Podfile.lock に OneSignalComplete も OneSignalLocation も表示されないことを確認してください。
- app.config.ts
- app.json
onesignal-expo-plugin 2.6.0 以降では、プラグインの props に対する完全な TypeScript サポートと自動補完のために withOneSignal をインポートできます。3. SDKを初期化する
Expo構造(従来のアプリエントリまたはExpo Router)に応じて、これらのオプションに従ってOneSignalを初期化します。- 従来のアプリエントリ
- Expo Router
useCallback で再利用可能なリスナー
リスナーが props や state にアクセスする必要がある場合は、useEffect の外で useCallback を使って定義し、追加と削除に同じ参照を使えるようにします。addEventListener と removeEventListener に異なる関数参照を渡しても何も起こりません。リスナーは削除されず、コンポーネントがアンマウントされた後も発火する可能性があります。
Android 设置
确保您的 OneSignal 应用已使用您的 Firebase 凭据 为 Android 平台进行配置。 设置您的通知图标以匹配您的应用品牌。如果跳过此步骤,推送通知将显示默认的铃铛图标。 为 Android 构建 此时,您应该能够在物理 Android 设备或模拟器上无问题地构建和运行您的应用。- 如果适用,继续进行 iOS 设置。
- 或者跳转到测试 OneSignal SDK 集成。
iOSセットアップ
p8トークン(推奨)またはp12証明書のいずれかを使用して、OneSignalアプリがiOSプラットフォーム用に構成されていることを確認してください。iOSでビルドする
これで、実際のiOSデバイスまたはiOSシミュレーター(16.2+)でアプリをビルドして実行できるはずです。iOSビルドの一般的なエラー
Cycle Inside... building could produce unreliable results.
Cycle Inside... building could produce unreliable results.
- Xcodeで
.xcworkspaceフォルダーを開き、アプリターゲット > Build Phasesに移動します。 - **「Embed Foundation Extensions」または「Embed App Extensions」**というフェーズが必要です。
- このビルドフェーズを**「Run Script」**の_上_にドラッグして移動します。
- アプリをビルドして実行します。エラーが解決されるはずです。

Xcodeのビルドフェーズの正しい順序。

「Copy only when installing」のチェックを外します。
PBXGroupエラー
PBXGroupエラー
PBXGroupが不明なISA PBXFileSystemSynchronizedRootGroupの属性からオブジェクトを初期化しようとしました:{"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}- エラーの「path」の下にリストされているフォルダーを見つけます
- Xcodeプロジェクトサイドバーで、フォルダーを右クリックします
- **「Convert to Group」**を選択します

PBXGroupのパスエラー。

フォルダーをグループに変換します。
测试 OneSignal SDK 集成
本指南帮助您通过测试推送通知、订阅注册和应用内消息来验证 OneSignal SDK 集成是否正常工作。检查移动端订阅
在测试设备上启动您的应用。
requestPermission 方法,原生推送权限提示应该会自动出现。
iOS 和 Android 推送权限提示
检查您的 OneSignal 控制台
- 转到 受众 > 订阅。
- 您应该看到一个状态为”从未订阅”的新条目。

控制台显示 '从未订阅' 状态的订阅
返回应用并在提示中点击允许。
刷新 OneSignal 控制台的订阅页面。
设置测试订阅
测试订阅有助于在发送消息之前测试推送通知。添加到测试订阅。

将设备添加到测试订阅
为您的订阅命名。
创建测试用户分组。
为分组命名。
Test Users(名称很重要,因为稍后会使用到)。添加测试用户过滤器并点击创建分组。

使用测试用户过滤器创建 'Test Users' 分组
通过 API 发送测试推送
获取您的应用 API 密钥和应用 ID。
更新提供的代码。
YOUR_APP_API_KEY 和 YOUR_APP_ID 替换为您的实际密钥。此代码使用我们之前创建的 Test Users 分组。运行代码。
检查图片和确认送达。

iOS 和 Android 上包含图片的推送通知
检查确认送达。
发送应用内消息
应用内消息让您可以在用户使用您的应用时与他们进行沟通。在设备上关闭或将您的应用切换到后台。
创建应用内消息。
- 在您的 OneSignal 控制台中,导航到 消息 > 应用内 > 新建应用内消息。
- 找到并选择欢迎消息。
- 将您的受众设置为我们之前使用的 Test Users 分组。

使用应用内消息定位 'Test Users' 分组
如需要,请自定义消息内容。

应用内欢迎消息的自定义示例
将触发器设置为 '应用打开时'。
安排频率。

应用内消息安排选项
使消息生效。
打开应用并查看消息。

在设备上显示的欢迎应用内消息
用户识别
之前,我们演示了如何创建移动端订阅。现在我们将扩展到使用 OneSignal SDK 在所有订阅(包括推送、电子邮件和短信)中识别用户。我们将涵盖外部 ID、标签、多渠道订阅、隐私和事件跟踪,以帮助您统一用户并跨平台与他们互动。分配外部 ID
使用外部 ID 通过您后端的用户标识符在设备、电子邮件地址和电话号码之间一致地识别用户。这确保您的消息传递在各个渠道和第三方系统中保持统一(对集成特别重要)。 每次您的应用识别用户时,使用我们 SDK 的login 方法设置外部 ID。
添加数据标签
标签是字符串数据的键值对,您可以使用它们来存储用户属性(如username、role 或偏好)和事件(如 purchase_date、game_level 或用户交互)。标签支持高级消息个性化和分组,允许更高级的用例。
在您的应用中发生事件时,使用我们 SDK 的addTag 和 addTags 方法设置标签。
在这个示例中,用户达到了第 6 级,可以通过名为 current_level 的标签识别,其值设置为 6。

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

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

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

iOS 和 Android 设备上收到的包含个性化内容的推送通知
添加电子邮件和/或短信订阅
之前我们了解了我们的 SDK 如何创建移动端订阅来发送推送和应用内消息。您还可以通过创建相应的订阅,通过电子邮件和短信渠道联系用户。- 使用
addEmail方法创建电子邮件订阅。 - 使用
addSms方法创建短信订阅。

通过外部 ID 统一的包含推送、电子邮件和短信订阅的用户档案
- 在添加电子邮件或短信订阅之前获得明确同意。
- 向用户解释每个沟通渠道的好处。
- 提供渠道偏好,让用户可以选择他们偏好的渠道。
隐私和用户同意
要控制 OneSignal 何时收集用户数据,请使用 SDK 的同意管控方法:setConsentRequired(true):阻止数据收集直到获得同意。setConsentGiven(true):一旦获得同意即启用数据收集。
提示推送权限
不要在应用打开时立即调用requestPermission(),而是采取更策略性的方法。在请求权限之前,使用应用内消息解释推送通知的价值。
有关最佳实践和实现细节,请参阅我们的提示推送权限指南。
监听推送、用户和应用内事件
使用 SDK 监听器来响应用户操作和状态变化。 SDK 提供了几个事件监听器供您使用。更多详情请参阅我们的SDK 参考指南。推送通知事件
addClickListener():检测通知被点击时。对深度链接有帮助。addForegroundLifecycleListener():控制通知在前台的行为方式。
用户状态变化
addObserver()用于用户状态:检测外部 ID 设置时。addPermissionObserver():跟踪用户与原生推送权限提示的特定交互。addObserver()用于推送订阅:跟踪推送订阅状态变化时。
应用内消息事件
addClickListener():处理应用内点击操作。适用于深度链接或跟踪事件。addLifecycleListener():跟踪应用内消息的完整生命周期(显示、点击、关闭等)。
高级设置和功能
探索更多功能以增强您的集成:移动端 SDK 设置和参考
通过查看移动端推送设置指南,确保您已启用所有关键功能。 有关可用方法和配置选项的完整详细信息,请访问移动端 SDK 参考。support@onesignal.com请包含以下信息:- 您遇到的问题详情以及复现步骤(如有)
- 您的 OneSignal 应用 ID
- 外部 ID 或订阅 ID(如适用)
- 您在 OneSignal 控制台中测试的消息 URL(如适用)
- 任何相关的日志或错误信息
