logoドキュメント
AppPush
ドキュメントホーム
ユーザーガイド開発者ガイドデータとプライバシーベストプラクティス
検索
日本語
English
繁體中文
简体中文
日本語
ภาษาไทย
Español
ログイン
開発者ガイド / REST API / コールバック API

コールバックAPI

最新更新：2025-07-22

概要

メッセージ状態データは企業の業務システムにコールバックされ、その情報に基づいて統計分析を行うことができます。

コールバックアドレス

企業はメッセージ状態変更を受信するためのコールバックアドレスを設定する必要があります。現在、ウェブインターフェースは存在しません。Engagelabの技術担当者に連絡してコールバックアドレスを設定してください。

コールバックアドレスの有効性検証

アプリケーション設定の下のプッシュバックエンド管理でコールバックアドレスを構成すると、ランダムに生成された8文字の文字列がechostrリクエストボディパラメータとして含まれるPOSTリクエストが送信されます。以下の形式に従って、Response Bodyでechostrの値を返す必要があります：

リクエストボディ：

{ "echostr": "12345678" }
              
              {
    "echostr": "12345678"
}
このコードブロックはフローティングウィンドウ内に表示されます

レスポンスボディ：

12345678
              
              12345678
このコードブロックはフローティングウィンドウ内に表示されます

セキュリティメカニズム

クライアント認証に使用され、オプションです。

メッセージの送信元がEngagelabであることを保証するために、POSTデータの送信元を認証することを選択できます。あるいは、認証を行わずに直接POSTデータを解析することもできます。

認証方法は以下の通りです：

  • Engagelabコンソールでコールバックアドレスにコールバックユーザー名（username）とコールバックシークレット（secret）を構成します。

リクエストヘッダーからX-CALLBACK-IDを取得します。以下の例を参照してください：

X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b
              
              X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b
このコードブロックはフローティングウィンドウ内に表示されます

ここで：

  • timestampはコールバックメッセージのタイムスタンプ（標準形式）です。
  • nonceは乱数です。
  • signatureは署名情報です。

署名方法は以下の通りです：

signature=HMAC-SHA256(secret, timestamp+nonce+username)
              
              signature=HMAC-SHA256(secret, timestamp+nonce+username)
このコードブロックはフローティングウィンドウ内に表示されます

レスポンスメカニズム

開発者サービスがEngagelabからのコールバックを受信した後、以下の要件に従って3秒以内に応答する必要があります：

  • 正常に受信： HTTPレスポンスステータスコードは200または204を返す必要があり、レスポンスメッセージは不要です。
  • 受信に失敗： HTTPレスポンスステータスコードは5XXまたは4XXを返す必要があり、レスポンスメッセージは以下の形式です：
{ "code": 2002, "message": "error" }
              
              {
    "code": 2002,
    "message": "error"
}
このコードブロックはフローティングウィンドウ内に表示されます
フィールド タイプ 必須/オプション 説明
code int オプション エラーコード
message string オプション エラー詳細

コールバックフィールドの説明

メッセージボディ

フィールド名 タイプ 必須/オプション 説明
total int 必須 このコールバックに含まれるメッセージの数
rows array 必須 メッセージ状態変更の詳細情報のリストで、以下のフィールドを含みます：

rows配列フィールド

フィールド名 タイプ 必須/オプション 説明
message_id string 必須 メッセージの一意の識別子
from string オプション 送信者、デフォルトはappkey
to string オプション 受信者の識別子（例：registrationID）
server string 必須 メッセージサービス名、可能な値：AppPush、WebPush
channel string 必須 メッセージチャネル、可能な値：EngageLab、HuaWei、XiaoMi、MeiZu、OPPO、VIVO、HONOR、FCM、APNs
custom_args object オプション メッセージ作成時に送信されたカスタムパラメータ、そのまま返されます
itime int 必須 メッセージ状態が発生した実際のタイムスタンプ、message_statusと組み合わせて各メッセージ状態のタイムスタンプを取得できます
status object 必須 メッセージ状態情報、以下のフィールドを含みます：

statusオブジェクトフィールド

フィールド名 タイプ 必須/オプション 説明
message_status string 必須 メッセージ状態、可能な値：target_valid、sent、delivered、click、target_invalid、sent_failed、delivered_failed、no_click
status_data object オプション カスタム状態データ、以下のフィールドを含みます：
channel_message_id string オプション サードパーティチャネルからのメッセージID
ntf_msg int 必須 メッセージタイプ、可能な値：1: Notification、2: Custom Message、5: iOS Real-Time Activity、6: iOS VOIP Message、7: In-App Message
platform string 必須 プッシュプラットフォーム、可能な値：a: Android、i: iOS、b: Web
uid int 必須 プッシュメッセージの受信者のUID
app_version string 必須 SDK統合アプリのバージョン、SDKレポートデータを通じて取得
channel string 必須 SDK統合アプリのチャネル、SDKレポートデータを通じて取得
msg_time int 必須 メッセージ配信時間、メッセージを送信するAPIリクエストが成功した時間
time_zone string 必須 組織のタイムゾーン
loss_valid_type int オプション このフィールドには実際の意味がなく、処理する必要はありません
plan_user_total int オプション このフィールドには実際の意味がなく、処理する必要はありません
callback_type int オプション このフィールドには実際の意味がなく、処理する必要はありません
error_code int オプション エラーコード、失敗した場合にのみ提供されます
error_detail object オプション 詳細なエラー情報、失敗した場合にのみ提供され、以下のフィールドを含みます：
message string オプション 詳細なエラー理由を説明、FCMチャネルにのみ適用されます
loss object オプション ロス情報、以下のフィールドを含みます：
loss_source string オプション ロスのソース、可能な値：EngageLab、HuaWei、XiaoMi、MeiZu、OPPO、VIVO、HONOR、FCM、APNs
loss_step int オプション ロス段階、可能な値：1: Plan Target → Valid Target、2: Valid Target → Sent Quantity、3: Sent Quantity → Delivered Quantity、4: Delivered Quantity → Click Quantity

メッセージ状態値

状態値 意味 説明
target_valid 有効なターゲット 過去365日間アクティブであれば有効と見なされます
sent 送信成功 サーバーに正常に送信されました
delivered 配信成功 EngageLab、XiaoMi、OPPO、VIVOの場合 — 実際のコールバックに基づく配信；
FCMとAPNsの場合 — ベンダーのサーバーに正常に送信された場合の配信；
HuaWei、MeiZu、HONORの場合、ベンダーコールバックが構成されていない場合はベンダーのサーバーに送信された場合の配信；構成されている場合はベンダーの実際のコールバックに基づく配信
click ユーザークリック SDKによって報告されたユーザーのクリック
target_invalid 無効なターゲット ロステーブルで定義された段階1に基づいて無効と見なされます
sent_failed 送信失敗 ロステーブルで定義された段階2に基づいて無効と見なされます
delivered_failed 配信失敗 ロステーブルで定義された段階3に基づいて失敗と見なされます
no_click クリック失敗 ロステーブルで定義された段階4に基づいて失敗と見なされます、インアプリメッセージにのみ適用されます

コールバックコンテンツ

コールバック方法：POST
Content-Type：application/json

例

リクエストヘッダー
POST /developer_define_url HTTP/1.1 Content-Type: application/json
              
              POST /developer_define_url HTTP/1.1
Content-Type: application/json
このコードブロックはフローティングウィンドウ内に表示されます
リクエストボディ
{ "total": 1, "rows": [ { "message_id": "1666165485030094861", // EngageLab側のメッセージID "from": "", // 送信者 "to": "", // 受信者、registrationID "server": "AppPush", "channel": "FCM", "custom_args": {}, // このメッセージを作成するときに送信されたパラメータ "itime": 1640707579, // 例：メッセージが配信された時間 "status": { // 成功時に返されるフィールド "message_status": "delivered", // メッセージ状態 "status_data": { // カスタムデータ "channel_message_id": "wamid.123321abcdefed==", // オプション、サードパーティチャネルのメッセージID "ntf_msg": 1, // メッセージタイプ "platform": "a", // プッシュプラットフォーム "uid": 100, // プッシュ通知のユーザーID "app_version": "", // SDKと統合されたアプリのバージョン "channel": "", // SDKと統合されたアプリのチャネル "msg_time": 1640707579, // メッセージ配信時間 "time_zone": "+8", // 組織のタイムゾーン "loss_valid_type": 0, // このフィールドは重要ではありません "plan_user_total": 0, // このフィールドは重要ではありません "callback_type": 0 // このフィールドは重要ではありません }, // 失敗時に返されるフィールド "error_code": 0, // エラーコード - ライフサイクルエラーコードに対応 "error_detail": { "message": "" // エラー理由 }, "loss": { "loss_source": "vivo", "loss_step": 1 } // ロスフェーズとロスソース } } ] } 
              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861", // EngageLab側のメッセージID
            "from": "", // 送信者
            "to": "", // 受信者、registrationID
            "server": "AppPush",
            "channel": "FCM",
            "custom_args": {}, // このメッセージを作成するときに送信されたパラメータ
            "itime": 1640707579, // 例：メッセージが配信された時間
            "status": {
                // 成功時に返されるフィールド
                "message_status": "delivered", // メッセージ状態    
                "status_data": { // カスタムデータ
                    "channel_message_id": "wamid.123321abcdefed==", // オプション、サードパーティチャネルのメッセージID
                    "ntf_msg": 1, // メッセージタイプ
                    "platform": "a", // プッシュプラットフォーム
                    "uid": 100, // プッシュ通知のユーザーID    
                    "app_version": "", // SDKと統合されたアプリのバージョン 
                    "channel": "", // SDKと統合されたアプリのチャネル   
                    "msg_time": 1640707579, // メッセージ配信時間
                    "time_zone": "+8", // 組織のタイムゾーン 
                    "loss_valid_type": 0, // このフィールドは重要ではありません
                    "plan_user_total": 0, // このフィールドは重要ではありません 
                    "callback_type": 0 // このフィールドは重要ではありません
                },
                // 失敗時に返されるフィールド
                "error_code": 0, // エラーコード - ライフサイクルエラーコードに対応
                "error_detail": {
                    "message": "" // エラー理由
                },
                "loss": {
                    "loss_source": "vivo",
                    "loss_step": 1
                } // ロスフェーズとロスソース
            }
        }
    ]
}
このコードブロックはフローティングウィンドウ内に表示されます

パラメータ説明

値 意味
target_valid 有効なターゲット
sent 送信成功
delivered 配信成功
click ユーザークリック
target_invalid 無効なターゲット
sent_failed 送信失敗
delivered_failed 配信失敗

ロス段階

  1. 計画ターゲット → 有効なターゲット
  2. 有効なターゲット → 送信済み
  3. 送信済み → 配信済み
  4. 配信済み → クリック

注意：
1. 一部のチャネルでのクリックと配信は重複する可能性があり、自分で重複排除を行うことができます。
2. 配信に成功してから5日後、配信数と表示数は調整されません。

icon
お問い合わせ