> ## 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.
# イベントストリーム
> OneSignalからメッセージデータをリアルタイムで選択した宛先に送信します。
イベントストリームを使用すると、OneSignalからメッセージデータをリアルタイムで選択した宛先に送信できます。イベントストリームは、OneSignalをマーケティングエコシステム内の他の製品に接続する優れた方法です。チームが対応するメッセージングをトリガーし、記録を維持するなど、さまざまなことを可能にします。
利用可能なイベントタイプには以下が含まれます：
* プッシュメッセージイベント（送信済み、受信済み、クリック済み、失敗、配信停止済み）
* メールイベント（送信済み、開封済み、クリック済み、バウンス済み、配信停止済みなど）
* SMSイベント（送信済み、失敗、配信停止済みなど）
* アプリ内メッセージイベント（インプレッション、クリック済みなど）
* ライブアクティビティイベント（送信済み、配信済み、確認済み配信、失敗、配信停止済み、クリック済み）
## 一般的なユースケース
* **エンゲージメントデータを一元化** — CRM、CDP、またはデータウェアハウスにイベントをストリーミングして、クロスチャネルのアクティビティ（開封、クリック、バウンス）を個別のツールに分散させず、一か所に集約します。
* **分析、レポーティング、コンプライアンス** — すべてのメッセージイベントをウェアハウスに蓄積して、トレンド分析、監査、または規制上の記録保存に活用します。
* **エンゲージメント離脱の監視** — 配信停止、バウンス、却下を自社システムで追跡して、リテンションリスクを早期に発見します。
* **外部ワークフローのトリガー** — ユーザーがメッセージを開封またはクリックしたときに他のツールで自動化を実行します（例：リードスコアを更新する、フォローアップシーケンスを開始する）。
* **バッチ同期と余分なインテグレーションを置き換える** — イベントにリアルタイムで対応し、OneSignalを直接宛先に接続することで、中間ツールとメンテナンスコストを削減します。
### 技術チームを始めるために
イベントストリームの設定は、マーケティング/プロダクトオーナー（*どの*イベントが重要で*どこに*送るかを決定する）とエンジニアリングチーム（受信エンドポイントを構築してストリームを設定する）の共同作業です。エンジニアリング側で必要な作業は次のとおりです：
1. **宛先とスコープを決定** — イベントをどこに送るか（自社 API、データウェアハウス、CDP など）、どのイベントタイプをストリーミングするか（プッシュ、メール、SMS、IAM、ライブアクティビティ）、エンドポイントを適切にサイジングするためのメッセージ量の見積もりを合意します。
2. **HTTPエンドポイントを設定** — POSTリクエストを受け入れる公開アクセス可能なエンドポイントを構築または設定します。応答時間を低く保つために、重い処理なしにイベントを迅速に記録する必要があります。パフォーマンスの期待値とエンドポイントが遅れた場合の動作については[再試行 / 無効化](#retries--disabling)をご覧ください。
3. **OneSignalでイベントストリームを設定** — **データ > イベントストリーム**で、イベントを選択し、URLと認証ヘッダーを設定し、[イベントストリームデータ](./event-streams-data)フィールドと[Liquid構文](./using-liquid-syntax)を使用してJSONボディを定義します。
4. **エンドツーエンドでテスト** — 本番エンドポイントに切り替える前に[webhook.site](https://webhook.site)を使用してペイロードの形式とヘッダーを確認します（[テスト](#testing)を参照）。
***
## セットアップ
OneSignalアプリケーションの**データ > イベントストリーム > 新規イベントストリーム**で新しいイベントストリームを構成できます。
**要件**
次の要件が満たされない限り、イベントを送信できません：
* 公開アクセス可能な **HTTP(S) エンドポイント**を指す有効なURLまたはIPアドレス
* URLとIPアドレスは公的にルーティング可能である必要があります
* ドメインには、認識されたトップレベルドメイン（例：「.com」、「.net」）が含まれている必要があります
### イベントの選択
イベントストリームに名前を付けて、**イベントを選択**をクリックします。
これによりイベント選択ページが開き、イベントストリームをトリガーするイベントを選択できます。
各イベントはプランのメッセージイベントボリュームにカウントされます。大規模なオーディエンスに**すべての**イベントタイプ（特に `sent`）をストリーミングすると、割り当てをすぐに消費する可能性があります——例えば、100,000人のユーザーへの1回の送信だけで100,000件の `sent` イベントが発生します。
ボリュームを管理するには：
* **必要なイベントタイプのみ選択** — 例えば、送信レベルのトラッキングが不要な場合は `received` と `clicked` で十分かもしれません。
* **[イベントストリームフィルター](#event-stream-filters)を使用**して、すべてのトラフィックをストリーミングするのではなく、特定のメッセージやテンプレートにイベントを限定します。
#### イベントストリームフィルター
1つ以上のメッセージまたはテンプレートの識別子を指定することで、オプションでイベントをさらに絞り込むことができます。これにより、特定のメッセージに関連するイベントのみを受信できます。
テンプレート識別子は、**メッセージ > テンプレート**に移動してコピーできます。追跡したいテンプレートの横で、**オプション > テンプレートIDをコピー**を選択し、イベントストリームフィルターに貼り付けます。
### イベントストリームの構成
HTTPメソッド、URL を選択し、イベントストリームのヘッダーを追加します。ここで、OneSignalとシステム間の安全な通信を確保するために認証を構成する必要があります。
URIとヘッダーには、ユーザープロパティとイベントストリームのプロパティの両方から取得されるLiquid構文を含めることができます。
#### 認証ヘッダー
エンドポイントへのリクエストが本当にOneSignalからのものであることを検証するために、認証ヘッダーを追加できます。一般的な認証方法には次のものがあります：
* **Authorizationヘッダー**：`Authorization`ヘッダーを追加します。`YOUR_TOKEN`はシステムまたはサードパーティによって提供されます：
* `Basic {{YOUR_TOKEN}}`
* `Bearer {{YOUR_TOKEN}}`
* `ApiKey {{YOUR_API_KEY}}`
* **カスタムヘッダー**：次のようなカスタムヘッダーを追加することもできます：
* `X-API-Key: {{YOUR_API_KEY}}`
*注：OneSignalは暗号化サービスを提供していません*
#### 構成のテスト
テストする簡単な方法をお探しの場合は、[webhook.site](https://webhook.site)を使用してください。ページの中央にある「Your unique URL」を見つけます。そのURLをコピーして、イベントストリーム構成のURLフィールドで使用します。
#### 許可されないヘッダー
次のヘッダーは制限されており、設定できません。
* `content-length`
* `referer`
* `metadata-flavor`
* `x-google-metadata-request`
* `host`
* `x-onesignal*`
### ボディ
イベントストリームのボディはJSONになります。ボディJSONは、個別のキー/値ペアとして、または編集可能なコードブロックとして定義できます。入力方法を変更するには、ボディ見出しの下の最初のドロップダウンを使用して、カスタムボディを選択します。
右側には、イベントストリームセットアップ中に入力されたものから構築された例示的なcURLリクエストが表示されます
### パーソナライゼーション
事前定義された[イベントストリームデータ](./event-streams-data)を使用して、イベントストリームのすべてのフィールドをパーソナライズできます。このデータは、[Liquid構文](./using-liquid-syntax)を使用して追加できます。これにより、ほぼすべてのユースケースでイベントストリームを使用する柔軟性が得られます。
パーソナライゼーションに利用可能なすべてのイベント、メッセージ、およびユーザーイベントデータのリストについては、[イベントストリームデータ](./event-streams-data)を参照してください。
#### ボディの例
ドロップダウンで「カスタムボディ」を選択します：
```json JSON theme={null}
{
"Event Data": {
"event.kind": "{{ event.kind }}",
"event.id": "{{ event.id }}",
"event.timestamp": "{{ event.timestamp }}",
"event.datetime": "{{ event.datetime }}",
"event.app_id": "{{ event.app_id }}",
"event.subscription_device_type": "{{ event.subscription_device_type }}",
"event.subscription_id": "{{ event.subscription_id }}",
"event.onesignal_id": "{{ event.onesignal_id }}",
"event.external_id": "{{ event.external_id }}",
"event.data.page_name": "{{ event.data.page_name}}",
"event.data.page_id": "{{ event.data.page_id}}",
"event.data.target_name": "{{ event.data.target_name}}",
"event.data.target_id": "{{ event.data.target_id}}",
"event.data.failure_reason": "{{ event.data.failure_reason}}"
},
"Message Data": {
"message.id": "{{ message.id }}",
"message.name": "{{ message.name }}",
"message.title": "{{ message.title.en }}",
"message.contents": "{{ message.contents.en }}",
"message.template_id": "{{ message.template_id }}",
"message.url": "{{ message.url }}",
"message.app_url": "{{ message.app_url }}",
"message.web_url": "{{ message.web_url }}"
}
}
```
#### JSONでのLiquid構文の使用
JSON内でLiquid構文を使用する場合、適切な引用符の使用はデータ型によって異なります：
**JSONフォーマットのガイドライン**
* **文字列** → 引用符で囲む**必要があります**。
* **数値** → 引用符で囲ま**ない**でください。
* **オブジェクト** → 引用符で囲んでは**いけません**。
以下の**正しい**例にある `//` コメント行は読みやすさのためだけのものです。実際のイベントストリームボディでは削除してください——厳密なJSONは `//` コメントを許可していません。
**例**
**✅ 正しい** — 引用符で囲む：
```liquid JSON theme={null}
{
"user_id": "{{ user.onesignal_id }}"
}
```
**❌ 誤り** — 引用符がないと無効なJSONになります：
```liquid JSON theme={null}
{
"user_id": {{ user.onesignal_id }}
}
```
**✅ 正しい** — 引用符なし：
```liquid JSON theme={null}
{
"user_score": {{ user.tags.score }}
}
```
**❌ 誤り** — 引用符で数値が文字列になります：
```liquid JSON theme={null}
{
"user_score": "{{ user.tags.score }}"
}
```
**✅ 正しい** — 引用符なし：
```liquid JSON theme={null}
{
"user_data": {{ user.tags }}
}
```
**❌ 誤り** — 引用符でオブジェクトが文字列になります：
```liquid JSON theme={null}
{
"user_data": "{{ user.tags }}"
}
```
**Liquid構文で多言語条件を処理するためのベストプラクティス**
言語ベースの条件での問題を回避するには
1. **直接言語チェックを使用する**：より良い互換性のために、`userLang`のような変数ではなく、条件内で常に`user.language`を直接チェックします。
2. **シンプルから始める**：基本的なフレーズから始めて、徐々に複雑さを追加します。
3. **過度のネストを避ける**：解析の問題を防ぐために、条件をフラットに保ちます。
4. **最初に基本的な句読点をテストする**：特殊文字を使用する前に、シンプルな文と句読点から始めます。
5. **フォールバックを使用する**：翻訳が欠落している場合に備えて、デフォルト言語（例：英語）を確保します。
6. **標準キーに固執する**：信頼性のために、`content/title/en`のような標準OneSignalキーを使用します。
このアプローチにより、解析エラーが最小限に抑えられ、システムとの互換性が確保されます。
Liquid構文を使用してメッセージをパーソナライズする方法の詳細とオプションについては、[Liquid構文の使用ガイド](./using-liquid-syntax)をご覧ください。
***
## 結果とデバッグ
イベントストリームのパフォーマンスを監視してトラブルシューティングします：
**レポートタブ** — 全期間の合計、イベントストリームの現在のステータス、および時間の経過に伴うHTTPレスポンスコードの時系列グラフを表示します。
| レスポンス | 意味 |
| ------------- | ---------------------------------------------------------- |
| **2xx** | イベントがエンドポイントで正常に受信されました。 |
| **4xx / 5xx** | エンドポイントがエラーを返しました。特定のステータスコードとレスポンスボディについては、ログタブを確認してください。 |
| **タイムアウト** | エンドポイントが許可された時間内に応答しませんでした。OneSignalは接続を閉じ、配信を失敗として扱いました。 |
**ログタブ** — 完全なリクエストボディ、ヘッダー、エンドポイントからのレスポンスを含む最近のリクエストのサンプルを表示します。デバッグを開始するのに最適な場所です——OneSignalが何を送信し、サーバーが何を返したかを正確に確認できます。
ペイロードや設定の調整が必要な場合は、イベントストリームを編集し、**テスト送信**ボタンを使用してサンプルリクエストを送信します。ペイロードがエンドポイントの期待に合うまで繰り返し、その後本番に移行します。
### 再試行 / 無効化
**再試行動作** — リクエストが回復可能なステータス（例：`429`）で失敗した場合、OneSignalは遅延を増やしながら再試行します。1つのイベントの再試行が失敗し続けると、そのイベントは永久に失敗としてマークされ、再試行されなくなります。
**自動無効化** — エンドポイントが多くのイベントにわたって継続的な失敗を返すと、OneSignalはイベントストリーム全体を無効にする可能性があります。これが発生した場合：
1. アプリと組織の管理者は、失敗量が顕著になったとき（無効化前）と、ストリームが無効化されたときに再度メールを受け取ります。
2. ダッシュボードの**イベントストリーム**インデックスページにもバナーが表示されます。
3. 根本的な問題を修正し、**ログ**タブまたは[webhook.site](https://webhook.site)でテストして、ストリームを再有効化します。
**パフォーマンスガイダンス** — エンドポイントは、メッセージ送信が生成するイベント量を処理できる必要があります。バックログと無効化を避けるには：
* **イベントを素早く記録** — 重い処理なしに、受信イベントをキューまたはデータストアに書き込みます。
* **遅い応答と429を避ける** — 一貫して遅い応答時間またはレート制限の応答は、イベントのバックアップを引き起こし、OneSignalがストリームを無効にする原因になります。
* **送信量に合わせてサイジング** — 100kのメッセージを送信すると、選択したイベントタイプごとに最大100kのイベントが発生します。プランのメッセージボリュームを確認し、適切にプロビジョニングしてください。
**重複排除** — 配信された各イベントには一意の`event.id`が含まれます。同じイベントが再試行または再生される場合にシステムが重複排除できるよう、ヘッダーまたはJSONボディに含めてください。
### 成功のためのヒント
* **まず自社サーバーにストリームをポイントします。** サードパーティAPIに直接接続することは*可能*ですが、受信側をコントロールできない場合、デバッグ、レート制限の処理、ボリュームの管理がより困難になります。
* **サードパーティに転送する前にバッファリングします。** OneSignalはユーザーがイベントをトリガーする速さでイベントを送信します——大規模な送信により、外部のレート制限を圧倒したり、コストを増加させたりするバーストが発生する可能性があります（特にSMSプロバイダー）。イベントを受け入れ、キューに入れ、コントロールできるペースで外部APIに転送する軽量サービスを構築してください。
* **サードパーティのAPIドキュメントを確認します。** 多くのサービスは、イベントストリームでターゲットできる公開HTTP APIを提供しています。ストリームを設定する前に、認証、受け入れ可能なペイロード形式、レート制限に関するドキュメントを探してください。
### メッセージイベントデータの制限
ジャーニーやAPIを介して送信されたメッセージのデータはOneSignalで30日間のみ利用可能です。これは、ジャーニーまたはAPIメッセージが送信されてから30日以上後に発生するメッセージイベント（クリック、開封、配信停止など）がイベントストリームで利用できなくなることを意味します。これはアナリティクスで空白または欠落したデータとして表示される場合があります。
この制限を回避するには、これらのクリック/開封/配信停止イベントの `message.id` を、同じ `message.id` を持つ元の `sent` イベントと相関させてください。元の `sent` イベントには関連するメッセージデータ（タイトル、テンプレートなど）が含まれているはずです。
***
## テスト
[webhook.site](https://webhook.site)を使用したエンドツーエンドのテストウォークスルー。**Your unique URL** をイベントストリームの **URL** フィールドに **POST** メソッドで貼り付けます。
追跡するイベントを設定します。この例では、プッシュイベントを使用しますが、どれでも動作します。
この例では、上記の[ボディの例](#body)を使用します。
イベントを保存してライブに設定します。
イベントをトリガーするためにメッセージを送信します。webhook.siteでは、次のデータを含むイベントが表示されます：
これは以下を示しています：
* **Host**：リクエストの送信元のIPアドレス。可能なIPのリストについては、[REST API概要](/reference/rest-api-overview)を参照してください。
* **Request Content**：イベントストリームのボディ内で送信されたデータ。
***