キャンペーンWebhook

SORIを通じた音声認識が成功したときに、これがユーザーに表示されます。SORI consoleで登録できます。

概要

SORI APIは、キャンペーン関連のイベントをほぼリアルタイムでサーバーに通知するWebhook機能を提供します。キャンペーンの詳細設定でWebhookエンドポイントを設定することで、以下のイベントの通知を受信できます：

キャンペーンインプレッションキャンペーンが認識され、ユーザーのデバイスに表示されたときにトリガー
キャンペーンクリックユーザーが発見されたキャンペーンをクリックし、キャンペーンアクションURLにアクセスしたときにトリガー

ほぼリアルタイムのイベント通知により、以下が可能になります：

インスタント分析キャンペーンパフォーマンスをリアルタイムで追跡・分析
音声認識ベースの報酬ユーザーの音声認識ステータスに基づいてサーバーサイドで報酬を発行
不正検出異常なパターンを即座に監視・検出
ライブダッシュボードキャンペーン指標のリアルタイム可視化を作成

Webhookの設定

SORIは、Webhookエンドポイントを設定する2つの方法を提供します：

グローバルWebhook URL

設定セクションで設定
デフォルトですべてのキャンペーンに適用
すべてのキャンペーンイベントの中央エンドポイントとして機能

キャンペーン固有のWebhook URL

各キャンペーンの詳細設定で設定可能
その特定のキャンペーンのグローバルWebhook URLをオーバーライド
異なるキャンペーンに異なる処理が必要な場合に有用

Webhookの設定方法

Webhookイベントを受信するためのHTTPエンドポイントをサーバーに準備
以下のいずれかを設定：

設定でグローバルWebhook URL、または
個別のキャンペーン設定でキャンペーン固有のWebhook URL

エンドポイントがJSONペイロードでPOSTリクエストを処理できることを確認

イベントタイプ

インプレッションとクリックイベントは両方とも同じWebhookエンドポイントを共有します。ペイロードのevent_typeフィールドを使用してイベントタイプを区別できます。

キャンペーンインプレッションイベント

キャンペーンがユーザーに正常に表示されたときに送信されます。インプレッションイベントの場合、event_typeはimpressionになります。

キャンペーンクリックイベント

ユーザーがキャンペーンをクリックし、キャンペーンアクションURLにリダイレクトされたときに送信されます。クリックイベントの場合、event_typeはclickになります。

Webhookイベントの処理

エンドポイントがWebhookイベントを受信すると、イベントの詳細を含むJSONペイロードが含まれます。以下は両方のイベントタイプの例です：

インプレッションイベントの場合：

json

{
  "event_type": "impression",
  "material_id": "string",
  "material_name": "string",
  "campaign_id": "string",
  "campaign_name": "string",
  "device_id": "string",
  "platform": "string",
  "metadata": {
    "key": "value"
  },
  "timestamp": "2024-01-01T12:00:00Z",
  "viewer_country": "string",
  "viewer_region": "string",
  "viewer_city": "string"
}

クリックイベントの場合：

json

{
  "event_type": "click",
  "campaign_id": "string",
  "campaign_name": "string",
  "device_id": "string",
  "platform": "string",
  "metadata": {
    "key": "value"
  },
  "timestamp": "2024-01-01T12:00:00Z",
  "viewer_country": "string",
  "viewer_region": "string",
  "viewer_city": "string"
}

カスタムメタデータ

metadataフィールドは、SDKから来るキーと値のペアで、ユーザーやデバイスを識別するために使用できます。このフィールドはオプションです。詳細については、メタデータプロバイダーセクションを参照してください。

ロケーション情報に関する注意

これはGeoIPエスティメーションに基づいており、必ずしも正確ではない場合があります。正確な情報が利用できない場合は、値Unknownが提供されます。

レスポンス要件

Webhookエンドポイントは以下を行う必要があります：

受信を確認するために2xxステータスコードでレスポンス
ブロッキングを避けるために可能であれば非同期でイベントを処理
イベントを冪等的に処理（タイムスタンプを使用）
タイムアウトを避けるために5秒以内にレスポンス

セキュリティ考慮事項

データプライバシーを確保するために、可能な限りWebhookエンドポイントにHTTPSを使用
受信ペイロード構造を検証
Webhook URLを機密に保つ

エラーハンドリング

エンドポイントがイベントの受信に失敗した場合、SORI APIサーバーは：

失敗した配信を最大3回再試行
再試行間に指数バックオフを実装
すべての再試行が尽きた後、イベントを破棄

実装例

Python (FastAPI)

python

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook")
async def webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("event_type")

    if (event_type == "impression"):
        # インプレッションイベントを処理
        # イベントを処理するコードを追加（例：データベースへのログ）
        pass
    elif (event_type == "click"):
        # クリックイベントを処理
        # イベントを処理するコードを追加（例：データベースへのログ）
        pass

    # 200ステータスコードでレスポンス
    return {"status": "success"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=3000)

NodeJS

typescript

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhook", (req, res) => {
  const payload = req.body;
  const eventType = payload.event_type;

  if (eventType === "impression") {
    // インプレッションイベントを処理
    // イベントを処理するコードを追加（例：データベースへのログ）
  } else if (eventType === "click") {
    // クリックイベントを処理
    // イベントを処理するコードを追加（例：データベースへのログ）
  }

  // 200ステータスコードでレスポンス
  res.status(200).send({ status: "success" });
});

app.listen(3000, () => {
  console.log("Server is running on port 3000");
});

キャンペーンWebhook ​

概要 ​

Webhookの設定 ​

グローバルWebhook URL ​

キャンペーン固有のWebhook URL ​

Webhookの設定方法 ​

イベントタイプ ​

キャンペーンインプレッションイベント ​

キャンペーンクリックイベント ​

Webhookイベントの処理 ​

カスタムメタデータ ​

レスポンス要件 ​

セキュリティ考慮事項 ​

エラーハンドリング ​

実装例 ​

Python (FastAPI) ​

NodeJS ​