視頻版講解

Webhook 通道接入

簡介/原理

神策智慧運營的Webhook是一種 API，用以支援潛在的任何自研或第三方推送、站內信、發券系統、簡訊服務、... 以及任何潛在觸發行為。
經過較為輕量的 REST API 對接開發，即可快速支援非神策智慧運營內置的觸發方式。

  • SA 作為資料輸入;
    • 如上圖，首先神策智慧運營會讀取從 SA 的即時或歷史事件數據，從而進行受眾計算，或即時觸發;
  • 神策智慧運營發送 Webhook 請求;
    • 神策智慧運營會發webhook 請求到您自身的一個HTTP Endpoint;
  • HTTP Endpoint 拿到請求后的處理;
    • 可自行做格式轉化、join 自有的其他數據、排隊、buffering 等操作，並最終調用其他任何內部或外部系統（稱為 Whatever System），可能調用的系統舉例：
      • 第三方推送服務;
      • 站內信系統;
      • 寫入 Redis;
      • 優惠券發送系統。
  • 回執事件：
    • 如果Whatever System 是推送服務，那麼可以在 App 中埋點，使 SA 得到推送回執事件。

Webhook 通道及參數設定

使用者屬性 vs 樣本參數

#

參數類型

定義配置處

值配置處

值獲取方法

補充說明

1

用戶屬性

項目設定-觸達方式管理-Webhook

無需配置

自動從使用者屬性中獲取

在通道中配置一次即可

2

範本參數

項目設定-觸達方式管理-Webhook

運營計劃-計劃 X-觸達方式

從計劃配置中獲取

在通道中配置后，還需要在計劃中填寫其 「取值」 部分

項目設定-觸達方式管理 - Webhook

如下圖，通道可設定 HTTP URL、動態參數、樣本參數.

運營計劃-計劃 X-觸達方式

HTTP Endpoint Server

為與神策智慧運營的Webhook 對接，您需要開發一個HTTP Server。 其應遵循的 API 定義見下文。

Webhook Request（預設小批量合併模式）

注意，Request Body 是批量打包的：

  • Webhook 請求的 Request Body 部分是一個打包的 JSON LIST;
  • 這是為方便批量處理，神策智慧運營已經對使用者觸發做了小批量合併;
  • 神策智慧運營的 Webhook 在一個請求中包含了多個使用者的觸發;

Request 結構如下：

POST /your/path HTTP/1.1
Content-Type: application/json
Content-Length: 2737
Host: 10.42. 34.43:8999
Connection: Keep-Alive
User-Agent: Apache-HttpAsyncClient/4.1. 3 (Java/1.8.0_212)
 
 
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="02cf867a-3e71-49d5-877a-242deadbd953"><ac:plain-text-body><![CDATA[[{"project_name": "default", "sf_version": "0.3", "user_profile": { ... }, " receipt_properties": { ... }, "params": { ... }}, {"project_name": "default", "sf_version": "0.3", "user_profile": { ... }, "receipt_properties": { ... }, " params": { ... }}, {"project_name": "default", "sf_version": "0.3", "user_profile": { ... }, "receipt_properties": { ... }, "params": { ... }}]

]]></ac:plain-text-body></ac:structured-macro>


Request Body 是一個 LIST：

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="72a6a104-e676-4526-ad45-b43517cffa9e"><ac:plain-text-body><![CDATA[

[
]]></ac:plain-text-body></ac:structured-macro>
{"project_name": "default", "sf_version": "0.3", "user_profile": { ... }, " receipt_properties": { ... }, "params": { ... }},
{"project_name": "default", "sf_version": "0.3", "user_profile": { ... }, "receipt_properties": { ... }, "params": { ... }},
{"project_name": "default", "sf_version": "0.3", "user_profile": { ... }, " receipt_properties": { ... }, "params": { ... }}
]



Request Body 的 JSON LIST 解析后，每個元素是一個單使用者觸發的 JSON 結構：

{
"project_name"： "default"， # 神策的專案名（非顯示名，而是作為標識符的英文名）
"sf_version"： "1.2"， # 神策智能運營版本資訊
"user_profile" ：{ # 神策 user profile 資訊的僅 ID 部分，沒有帶上屬性資訊.
"user_id"： -5159414601538973264， # 長整數，在神策分析中使用者的唯一標識
"first_id"： "EA7583CDA6678BC"， # 通常是使用者的設備 ID
"second_id" ： "12345678901" # 通常是使用者的登錄 ID
},
"receipt_properties"： { # 回執屬性打包，您通常不需要關心此結構的內部細節，在發送回執消息時，直接當做屬性 map 使用即可.
"sf_msg_id": "ffa71d08-f352-43eb-a1f5-5197299d2075",
"sf_plan_id": 10,
"sf_plan_audience_id": 20,
"sf_plan_strategy_id": 0,
"sf_strategy_unit_id": null,
"sf_plan_type" ： "運營計劃"
},
"params"： { # 您在 webhook 中配置的
"viplevel"： "1"， #"動態參數" 舉例，對應到下圖中的，動態參數 viplevel". 需要注意的是，params 欄位無論原始類型是什麼，均會被神策智慧運營轉換為 STRING 類型
"action"： "sample_action" # "靜態參數" 舉例，對應到下圖中的，靜態參數 action".
},
"send_id"： "1618307389657000" # 發送 ID 為觸達使用者方式的發送標識，比如手機號、推送 ID
}


Webhook Response

HTTP 200 無 Body，神策智慧運營認為全部發送成功。
HTTP 200 有 Body，並返回詳細的報錯資訊，您需要產生一個 Response Body 如下：

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="f4f59a37-e509-473f-9129-56f7b5f75786"><ac:plain-text-body><![CDATA[

[
]]></ac:plain-text-body></ac:structured-macro>
{
"succeed": true
},
{
"succeed": false
"fail_reason": "....."
},
...
]


非 HTTP 200 狀態，認為全部失敗。

範本參數類型舉例


注：對於任何類型的數據（如上圖整數，小數，日期等類型），在發送請求時，所有字段全部轉為字串進行處理。

如上圖：最終的 request 為

{
"project_name"： "default"， # 神策的專案名（非顯示名，而是作為標識符的英文名）
"sf_version" ： "1.2"， # 神策智慧運營版本資訊
"user_profile" ：{ # 神策 user profile 資訊的僅 ID 部分，沒有帶上屬性資訊.
"user_id"： -5159414601538973264， #長整數，在神策分析中使用者的唯一標識
"first_id"： "EA7583CDA6678BC"， # 通常是使用者的設備 ID
"second_id"： "12345678901" # 通常是使用者的登錄 ID
},
"receipt_properties"： { # 回執屬性打包，您通常不需要關心此結構的內部細節，在發送回執消息時，直接當做屬性 map 使用即可.
"sf_msg_id": "ffa71d08-f352-43eb-a1f5-5197299d2075",
"sf_plan_id": 10,
"sf_plan_audience_id": 20,
"sf_plan_strategy_id": 0,
"sf_strategy_unit_id": null,
"sf_plan_type" ： "運營計劃"
},
"params"： { # 您在 webhook 中配置的
"string": "string",
"text"： "使用者城市是北京"，
"datetime": "2019-08-08",
"integer": "123",
"decimal": "158.123",
"percentage"： "18.5" # 注意：百分數只傳對應數值，沒有 %
},
"send_id"： "1618307389657000" # 發送 ID 為觸達使用者方式的發送標識，比如手機號、推送 ID
}


請求性能與延遲

高吞吐場景

如果您常見的使用模式為 「定時」、「多次例行」 的批量計劃，且每次的觸發使用者量很大，請聯繫我們提供方案。

高實時場景

為提高輸送，對使用者觸發做了小批量的合併，這會導致數秒延遲。
Webhook 本身對時效性不做保證，若需要秒級或毫秒級時效性，請考慮使用智慧運營 1.6 版本的彈窗，或聯繫神策獲得技術方案。

回執事件

您可以發送一個回執的事件給 SA，並帶上回執屬性。
回執事件的目的是為了支援對神策智慧運營更靈活的數據分析，但並非神策智慧運營必備事件。
事件/屬性定義如下：

name

cname

附帶屬性

解釋

$AppPushClick

推送打開

receipt_properties 中的屬性原樣使用即可

如果Webhook對接的系統是第三方/自研推送系統，那麼請在 App 端做此事件的埋點，請具體代碼示例請參考[ Android

https://manual.sensorsdata.cn/pages/viewpage.action?pageId=7546443]推送集成和[ iOS

https://manual.sensorsdata.cn/pages/viewpage.action?pageId=17567473]推送集成 。

WebhookReceipt

通用 Webhook 回執

receipt_properties 中的屬性原樣使用即可

例如站內消息發送成功、優惠券發送成功。

$PlanMsgArrived

Webhook 傳送成功或失敗回執

receipt_properties 中的屬性與新增加的屬性

可以通過上報此事件給 SA，判斷 Webhook 發送是否成功。

Webhook 傳送成功或失敗回執詳細描述

事件預置屬性

屬性名稱

屬性含義

屬性值

$sf_msg_status

是否發送成功指標

RECEIPT_SEND_FAILED 「發送失敗，RECEIPT_SEND_SUCCESS 「發送成功」

$sf_enter_plan_time

計劃進入時間

長整型

$sf_channel_category

通道類型

Webhook

$sf_plan_type

計劃類型

運營計劃，流程畫布

$sf_strategy_unit_id

原則器ID

整型

$sf_plan_strategy_id

實驗群 組代碼

整型

$sf_plan_id

排程ID

整型

備註：是否發送成功指標是指客戶發送資訊給具體使用者，使用者接收資訊是否成功。

事件上報demo

SensorsAnalytics sa = new SensorsAnalytics(new SensorsAnalytics.ConcurrentLoggingConsumer("./access.log1"));
Map<String, Object> properties = new HashMap<>();
計劃ID
properties.put("$sf_plan_id", 10);
實驗組ID
properties.put("$sf_plan_strategy_id", 0);
策略器名稱
properties.put("$sf_strategy_unit_id", 10);
計劃類型
properties.put（"$sf_plan_type"， "運營計劃"）;
通道ID
properties.put("$sf_channel_id", 10);
通道類型
properties.put("$sf_channel_category", null);
計劃進入時間
properties.put("$sf_enter_plan_time", null);

發送成功指標
properties.put("$sf_msg_status", "RECEIPT_SEND_SUCCESS");
發送失敗指標
properties.put("$sf_msg_status", "RECEIPT_SEND_FAILED");

sa.track("userId", false, "$PlanMsgArrived", properties);

Code Block 1 webhook回執事件上報javademo

驗證數據來自神策智能運營

一些場景下，您需要驗證Webhook 請求是來自神策智慧運營而不是第三方偽造的，這時您可為 Webhook 配置一個 Secret Token（目前可以提供給我們配置），該 Secret Token 在神策智慧運營服務端和您的伺服器上共用。
1.神策智慧運營發送請求前，對於請求的內容 REQUEST_BODY，計算 HmacSHA1（SECRET_TOKEN， REQUEST_BODY） 作為 Signature，如 cc711d5c504b757117f8823527522d512f79ffe4。 2. 發送Webhook 請求時將添加HTTP header X-Sf-Signature，如 X-Sf-Signature： cc711d5c504b757117f8823527522d512f79ffe4 。 3. 您的伺服器接到請求后，同樣計算 HmacSHA1（SECRET_TOKEN， REQUEST_BODY），如果值與 header X-Sf-Signature 相同，那麼可以確定是由神策智慧運營伺服器發送的。
其中簽名函數 HmacSHA1（SECRET_TOKEN = "abc"， REQUEST_BODY = "123"） = be9106a650ede01f4a31fde2381d06f5fb73e612shell 命令：echo -n '123' | openssl dgst - sha1 -hmac 'abc' 輸出 be9106a650ede01f4a31fde2381d06f5fb73e612
HmacSHA1 計算代碼範例：
maven 依賴：

<dependency>
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
<version>1.10</version>
</dependency>


HmacSHA1 計算代碼：

import org.apache.commons.codec.digest.HmacUtils;
...
String signature = HmacUtils.hmacSha1Hex(secretToken, requestBody)


Webhook 通道接入講解視頻