コールバックAPI
概要
メッセージ状態データは企業の業務システムにコールバックされ、その情報に基づいて統計分析を行うことができます。
コールバックアドレス
企業はメッセージ状態変更を受信するためのコールバックアドレスを設定する必要があります。現在、ウェブインターフェースは存在しません。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 | 必須 | メッセージ作成時に送信されたカスタムパラメータ、そのまま返されます。属性は常に存在します。業務値がない場合は null です。 |
itime |
int | 必須 | メッセージ状態が発生した実際のタイムスタンプ、message_statusと組み合わせて各メッセージ状態のタイムスタンプを取得できます |
status |
object | 必須 | メッセージ状態情報、以下のフィールドを含みます： |
statusオブジェクトフィールド
| フィールド名 | タイプ | 必須/オプション | 説明 |
|---|---|---|---|
message_status |
string | 必須 | メッセージ状態、可能な値：target_valid、sent、delivered、Impression、click、target_invalid、sent_failed、delivered_failed、impression_failed、no_click |
status_data |
object | 必須 | カスタム状態データ。属性は常に存在します。業務値がない場合はゼロ値または null です。以下のフィールドを含みます： |
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 | 必須 | このフィールドには実際の意味がなく、処理する必要はありません。属性は常に存在します。業務値がない場合は 0 です。 |
plan_user_total |
int | 必須 | このフィールドには実際の意味がなく、処理する必要はありません。属性は常に存在します。業務値がない場合は 0 です。 |
callback_type |
int | オプション | このフィールドには実際の意味がなく、処理する必要はありません |
error_code |
int | 必須 | エラーコード。属性は常に存在します。成功時も整数のゼロ値 0 を出力し、失敗時は対応するエラーコードです。 |
error_detail |
object | 必須 | 詳細なエラー情報。属性は常に存在します。成功時または業務値がない場合はゼロ値または null です。以下のフィールドを含みます： |
message |
string | オプション | 詳細なエラー理由を説明、FCMチャネルにのみ適用されます |
loss |
object | 必須 | ロス情報。属性は常に存在します。業務値がない場合はゼロ値または null です。以下のフィールドを含みます： |
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。属性は常に存在します。業務値がない場合は 0 です。 |
メッセージ状態値
| 状態値 | 意味 | 説明 |
|---|---|---|
target_valid |
有効なターゲット | 過去365日間アクティブであれば有効と見なされます |
sent |
送信成功 | サーバーに正常に送信されました |
delivered |
配信成功 | EngageLab、XiaoMi、OPPO、VIVOの場合 — 実際のコールバックに基づく配信；FCMとAPNsの場合 — ベンダーのサーバーに正常に送信された場合の配信；HuaWei、MeiZu、HONORの場合、ベンダーコールバックが構成されていない場合はベンダーのサーバーに送信された場合の配信；構成されている場合はベンダーの実際のコールバックに基づく配信 |
Impression |
表示成功 | EngageLab Android通知とアプリ内メッセージは表示成功をコールバックします。 |
click |
ユーザークリック | SDKによって報告されたユーザーのクリック |
target_invalid |
無効なターゲット | ロステーブルで定義された段階1に基づいて無効と見なされます |
sent_failed |
送信失敗 | ロステーブルで定義された段階2に基づき送信失敗と見なされます |
delivered_failed |
配信失敗 | ロステーブルで定義された段階3に基づいて失敗と見なされます |
impression_failed |
表示失敗 | EngageLab Android通知とアプリ内メッセージは解析または表示失敗をコールバックします。 |
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 |
配信成功 |
Impression |
表示成功 |
click |
ユーザークリック |
target_invalid |
無効なターゲット |
sent_failed |
送信失敗 |
delivered_failed |
配信失敗 |
impression_failed |
表示失敗 |
ロス段階
- 計画ターゲット → 有効なターゲット
- 有効なターゲット → 送信済み
- 送信済み → 配信済み
- 配信済み → クリック
注意：
1. 一部のチャネルでのクリックと配信は重複する可能性があり、自分で重複排除を行うことができます。
2. 配信に成功してから5日後、配信数と表示数は調整されません。
