> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ReactJSとNextJSのセットアップ
> ReactJSまたはNextJS Webアプリケーションにプッシュ通知を統合する方法を学びます。初期化、サービスワーカーのセットアップ、TypeScriptサポートを含みます。
export const SdkReleasesIframe = ({sdkFilter = undefined, viewMode = undefined, height, ...frameProps}) => {
const baseUrl = 'https://onesignal.github.io/sdk-releases';
const buildUrl = (theme, sdkFilter, viewMode) => {
const url = new URL(baseUrl);
const params = new URLSearchParams();
if (theme) {
params.set('theme', theme);
}
if (sdkFilter) {
params.set('sdk', sdkFilter);
}
if (viewMode) {
params.set('viewMode', viewMode);
}
if (params.toString()) {
url.search = params.toString();
}
return url.toString();
};
const detectTheme = () => {
if (document.documentElement.classList.contains('dark')) {
return 'dark';
}
return 'light';
};
const [theme, setTheme] = useState('light');
const [iframeSrc, setIframeSrc] = useState(() => {
const initialTheme = detectTheme();
return buildUrl(initialTheme, sdkFilter, viewMode);
});
useEffect(() => {
const currentTheme = detectTheme();
setTheme(currentTheme);
setIframeSrc(buildUrl(currentTheme, sdkFilter, viewMode));
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
const handleThemeChange = () => {
const newTheme = detectTheme();
setTheme(newTheme);
setIframeSrc(buildUrl(newTheme, sdkFilter, viewMode));
};
if (mediaQuery.addEventListener) {
mediaQuery.addEventListener('change', handleThemeChange);
} else {
mediaQuery.addListener(handleThemeChange);
}
window.addEventListener('storage', handleThemeChange);
const observer = new MutationObserver(handleThemeChange);
observer.observe(document.documentElement, {
attributes: true,
attributeFilter: ['class', 'data-theme']
});
return () => {
if (mediaQuery.removeEventListener) {
mediaQuery.removeEventListener('change', handleThemeChange);
} else {
mediaQuery.removeListener(handleThemeChange);
}
window.removeEventListener('storage', handleThemeChange);
observer.disconnect();
};
}, [sdkFilter, viewMode]);
const getIframeHeight = () => {
if (viewMode === 'table') {
return '450';
}
if (viewMode === 'mini') {
return '170';
}
return '800';
};
const iframeHeight = height || getIframeHeight();
return
;
};
## 概要
このガイドでは、ReactJSまたはNextJSアプリケーションにOneSignalプッシュ通知を統合する方法を説明します。インストールから構成、サービスワーカー管理までのすべてをカバーしています。
***
## 要件
* 構成されたOneSignalアプリとプラットフォーム。開始するには、[Webプッシュセットアップ](./web-push-setup)を参照してください。
***
## インストール
お好みのパッケージマネージャーを選択してください：
```bash Yarn theme={null}
yarn add react-onesignal
```
```bash npm theme={null}
npm install --save react-onesignal
```
***
## 初期化
OneSignalサービスをインポートし、ルートコンポーネントで初期化します。
`YOUR_APP_ID`を[キーとID](./keys-and-ids)にあるOneSignalアプリIDに置き換えてください。
```javascript theme={null}
"use client";
import { useEffect } from 'react';
import OneSignal from 'react-onesignal';
export default function Page() {
useEffect(() => {
// Ensure this code runs only on the client side
if (typeof window !== 'undefined') {
OneSignal.init({
appId: 'YOUR_APP_ID',
// You can add other initialization options here
notifyButton: {
enable: true,
}
});
}
}, []);
return (
Hello, world!
{/* Rest of your page content */}
);
}
```
### initオプションのカスタマイズ
追加の[`init`パラメータ](./web-sdk-reference#init)を使用して初期化をカスタマイズできます。
### サービスワーカーの設定
まだ行っていない場合は、[OneSignalサービスワーカーファイルをダウンロード](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip)して、サイトに追加する必要があります。
`OneSignalSDKWorker.js`ファイルは公開アクセス可能である必要があります。`public`ディレクトリ、トップレベルルート、またはサブディレクトリに配置できます。ただし、ファイルをサブディレクトリに配置する場合、またはサイトに別のサービスワーカーがある場合は、パスを指定してください。詳細については、[OneSignalサービスワーカー](./onesignal-service-worker)を参照してください。
| オプション | 説明 |
| -------------------- | -------------------------------------------------------------------------------------------- |
| `serviceWorkerParam` | OneSignalワーカーによって制御されるスコープ。**推奨：** カスタムサブパスを使用します（例：`"/onesignal/"`）。 |
| `serviceWorkerPath` | ホストされているOneSignalサービスワーカーファイルへのパス（例：`"onesignal/OneSignalSDKWorker.js"`）。公開アクセス可能である必要があります。 |
完全な動作例については、こちらを参照してください：[React + OneSignalの例](https://github.com/OneSignal/react-onesignal/tree/main/example)
#### ワーカーのホスティング
* パブリックルート（デフォルト）：`/OneSignalSDKWorker.js`
* カスタムフォルダー（推奨）：例：前のステップで設定した`/onesignal/OneSignalSDKWorker.js`。
#### サービスワーカーのホスティングを確認する
ブラウザでパスにアクセスして、アクセス可能であることを確認します。
ルートを使用した場合：
```
https://your-site.com/OneSignalSDKWorker.js
```
例のパスを使用した場合：
```
https://your-site.com/onesignal/OneSignalSDKWorker.js
```
有効なJavaScriptが返されるはずです。
### 重要な注意事項
* 開発環境での重複初期化を避ける
* 開発環境でテストする場合、OneSignal SDKが2回初期化され、コンソールエラーが発生する場合があります。
* これは、``が開発中にエフェクトを2回実行するために発生します。これを解決するには、開発中にルートコンポーネントから``を削除してください。
Strictモードは開発にのみ影響します。本番ビルドには影響しません。
***
## 测试 OneSignal SDK 集成
本指南帮助您验证 OneSignal SDK 集成是否正常工作，通过测试推送通知和订阅注册。
### 检查网页推送订阅
* 测试时使用 Chrome、Firefox、Edge 或 Safari。
* **请勿使用无痕或隐私浏览模式。** 用户无法在这些模式下订阅推送通知。
* 提示应根据您的[权限提示](/docs/cn/permission-requests)配置出现。
* 在原生提示上点击**允许**以订阅推送通知。
* 前往**受众 > 订阅**。
* 您应该看到状态为**已订阅**的新条目。
您已成功创建了[网页推送订阅](/docs/cn/subscriptions)。
当用户首次订阅您网站的推送通知时，将创建网页推送订阅。
### 设置测试订阅
测试订阅有助于在发送消息前测试推送通知。
在控制台中，在订阅旁边，点击**选项（三个点）**按钮并选择**添加到测试订阅**。
命名订阅，以便您后续在**测试订阅选项卡**中轻松识别您的设备。
前往**受众 > 细分 > 新建细分**。
将细分命名为 `Test Users`（名称很重要，因为后续会用到）。
您已成功创建了测试用户细分。
现在我们可以测试向这个单独设备和测试用户组发送消息。
### 通过 API 发送测试推送
在您的 OneSignal 控制台中，前往**设置 > [密钥和 ID](/docs/cn/keys-and-ids)**。
在下面的代码中将 `YOUR_APP_API_KEY` 和 `YOUR_APP_ID` 替换为您的实际密钥。这段代码使用了我们之前创建的 `Test Users` 细分。
```curl theme={null}
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"
],
"chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'
```
在您的终端中运行代码。
如果所有设置步骤都成功完成，测试订阅应该会收到通知。
仅 Chrome 支持图片。图片在收缩的通知视图中显示很小。展开通知以查看完整图片。
在您的控制台中，前往**投递 > 已发送消息**，然后点击消息查看统计数据。您应该看到**已确认**统计数据，表示设备收到了推送。
Safari 不支持确认投递。
查看推送通知的投递、点击和转化统计数据。
您已成功通过 API 向细分发送了通知。
如果通知未到达，请联系 `support@onesignal.com` 并提供以下信息：
* API 请求和响应（复制粘贴到 `.txt` 文件中）
* 您的订阅 ID
* 包含 OneSignal 代码的网站 URL
***
## 用户识别
上一节介绍了如何创建网页推送[订阅](/docs/cn/subscriptions)。本节将扩展到使用 OneSignal SDK 识别跨所有订阅（包括推送、电子邮件和短信）的[用户](/docs/cn/users)。涵盖外部 ID、标签、多渠道订阅、隐私和事件追踪，帮助您统一并跨平台互动用户。
### 分配外部 ID
使用外部 ID 通过您后端的用户标识符在设备、电子邮件地址和电话号码中一致地识别用户。这确保您的消息在渠道和第三方系统中保持统一（对[集成](/docs/cn/integrations)尤其重要）。
使用 SDK 的[`login` 方法](/docs/cn/web-sdk-reference#login-external-id)在您的应用每次识别用户时设置外部 ID。
OneSignal 为订阅（订阅 ID）和用户（OneSignal ID）生成唯一的只读 ID。
当用户在不同设备上下载您的应用、订阅您的网站和/或在应用外提供电子邮件地址和电话号码时，将创建新的订阅。
强烈建议通过 SDK 设置外部 ID，以在用户的所有订阅中识别用户，无论订阅是如何创建的。
### 添加数据标签
[标签](/docs/cn/add-user-data-tags)是字符串数据的键值对，您可以使用它们存储用户属性（如 `username`、`role` 或偏好设置）和事件（如 `purchase_date`、`game_level` 或用户交互）。标签为高级[消息个性化](/docs/cn/message-personalization)和[细分](/docs/cn/segmentation)提供支持，允许更高级的使用场景。
当应用中发生事件时，使用 SDK 的[`addTag` 和 `addTags` 方法](/docs/cn/web-sdk-reference#addtag-%2C-addtags)设置标签。
在这个例子中，用户达到了 6 级，可通过名为 `current_level` 的标签识别，值设置为 `6`。
我们可以创建一个等级在 5 到 10 之间的用户细分，然后使用它来发送针对性和个性化的消息：
### 添加电子邮件和/或短信订阅
OneSignal SDK 在用户选择加入时自动创建网页推送订阅。您也可以通过创建相应的订阅，通过电子邮件和短信渠道联系用户。
* 使用[`addEmail` 方法](/docs/cn/web-sdk-reference#addemail-%2C-removeemail)创建电子邮件订阅。
* 使用[`addSms` 方法](/docs/cn/web-sdk-reference#addsms-%2C-removesms)创建短信订阅。
如果电子邮件地址和/或电话号码在 OneSignal 应用中已存在，SDK 将将其添加到现有用户，不会创建重复。
您可以通过控制台中的**受众 > 用户**或[View user API](/reference/view-user)查看统一用户。
多渠道沟通的最佳实践
* 在添加电子邮件或短信订阅之前获得明确同意。
* 向用户解释每个沟通渠道的好处。
* 提供渠道偏好设置，以便用户可以选择他们喜欢的渠道。
***
### 隐私和用户同意
要控制 OneSignal 何时收集用户数据，请使用 SDK 的同意门控方法：
* [`setConsentRequired(true)`](/docs/cn/web-sdk-reference#setconsentrequired)：在给予同意之前阻止数据收集。
* [`setConsentGiven(true)`](/docs/cn/web-sdk-reference#setconsentgiven)：一旦获得同意就允许数据收集。
有关隐私和安全的更多信息：
了解 OneSignal SDK 从用户收集的数据。
依据隐私法规管理和保护用户数据。
***
## 监听推送、用户和应用内事件
使用 SDK 监听器对用户操作和状态变化做出反应。
SDK 为您提供了多个事件监听器可以钩入。查看我们的[SDK 参考指南](/docs/cn/web-sdk-reference)了解更多详情。
### 推送通知事件
* [点击事件监听器](/docs/cn/web-sdk-reference#click)：检测通知何时被点击。
* [前台生命周期监听器](/docs/cn/web-sdk-reference#foregroundwilldisplay)：控制通知在前台的行为。
### 用户状态变化
* [用户状态变化事件监听器](/docs/cn/web-sdk-reference#addeventlistener-user-state)：检测外部 ID 何时被设置。
* [权限观察器](/docs/cn/web-sdk-reference#permissionchange)：追踪用户与原生推送权限提示的特定交互。
* [推送订阅变化观察器](/docs/cn/web-sdk-reference#addeventlistener-push-subscription-changes)：追踪推送订阅状态何时变化。
***
## 高级设置和功能
探索更多功能以增强您的集成：
从其他推送服务迁移到 OneSignal。
将 OneSignal 与第三方工具和平台连接。
为推送通知添加互动按钮。
以用户首选语言发送本地化消息。
使用服务器端身份验证保护您的 SDK 集成。
追踪与消息关联的自定义转化事件。
### Web SDK 设置和参考
为您的集成启用所有关键网页推送功能。
可用方法和配置选项的完整详情。
恭喜！您已成功完成 Web SDK 设置指南。
***
需要帮助？
与我们的支持团队聊天或发送邮件至 `support@onesignal.com`
请包含以下信息：
* 您遇到的问题详情以及复现步骤（如有）
* 您的 OneSignal 应用 ID
* 外部 ID 或订阅 ID（如适用）
* 您在 OneSignal 控制台中测试的消息 URL（如适用）
* 任何相关的[日志或错误信息](/docs/cn/capturing-a-debug-log)
我们很乐意为您提供帮助！