合作夥伴 Postback 整合驗證
對象： 在聯盟後台設定 postback 的人，以及確認設定已就緒的 AM 或 BD。請在第一個廣告系列上線之前跑一遍本頁。
Postback 是發往 https://mmp.revosurge.com 的普通 HTTP GET 呼叫，所有內容都放在查詢字串裏。
規則分兩級
必要規則會阻止上線。建議規則不會，但每一條都有具體的代價 — 通常是歸因質素，或對帳能力。
規則 ID（PB-R-01、PB-O-01…）是穩定的。請在工單和發給合作夥伴的電郵中引用它們。
Postback 的失敗是刻意靜默的
RevoSurge 絕不會因為負載問題而回 4xx。一條沒有可用身分識別的 postback 會回 200 {"status":"ignored"} — 你的後台會把它記為成功，而這筆轉換就此消失。本頁大部分內容都是因為這一個行為而存在的。
必要規則
| ID | 規則 | 失敗會導致甚麼 |
|---|---|---|
PB-R-01 | 每次呼叫都帶上正確的 k | 403。甚麼都不會被記錄。 |
PB-R-02 | 端點路徑與事件相符 — 事件類型由路徑決定 | event 宏只作交叉核對記錄，絕不用於判定類型。把充值發到註冊路徑，它就永遠是一次註冊。 |
PB-R-03 | click_id 與 user_id 至少有一個 | 200 {"status":"ignored"}。在你的日誌裏看來是成功，但這筆轉換並不存在。 |
PB-R-04 | click_id 或 user_id 中沒有未替換的宏 | 字面值 {sub1} 會令整條 postback 被丟棄。在其他欄位中則只損失該欄位。 |
PB-R-05 | 首次充值發到 /first-deposit，之後的充值發到 /repeat-deposit | 首存（FTD）數會雙向出錯，而 FTD 通常正是廣告系列的出價目標。 |
PB-R-06 | ts 是 unix 毫秒，不是秒 | 秒級值會被自動修正，並當作契約偏離上報。不會有任何失敗，但你依賴的是我們的修正，而不是傳送你真正想表達的值 — 而且告警會落到你的客戶經理那邊，而不是你。 |
PB-R-07 | /first-deposit、/repeat-deposit 和 /revenue 都傳送 amount，且正負號正確（/registration 與 /app-launch 不帶金額） | 沒有可報告的收入，也無從計算 ROAS。 |
PB-R-08 | event_id 全域唯一、穩定，並在重試時原樣重複 | 沒有它，去重會退回到 txid，再退回到查詢字串雜湊。任何欄位次序有變的重試都會變成第二筆轉換。 |
PB-R-09 | 503 要重試；200 和 403 不重試 | 503 代表寫入未被確認 — 除非你重發，否則這筆轉換就會遺失。缺少 event_id 時重試 200 有重複計數的風險。 |
PB-R-10 | 註冊的生產 URL 中不含 dryrun | 每條 postback 都只回傳判定結果，甚麼都不記錄。 |
PB-R-11 | user_id 與你在 Web 追蹤器和 S2S 中使用的識別碼相同 | 同一玩家變成兩份檔案。充值無法關聯到帶來它的那次點擊。 |
PB-R-12 | Postback 從你的後台伺服器端觸發，而不是從瀏覽器 | k 金鑰以明文出現在 URL 中 — 瀏覽器觸發的 postback 會把它暴露在網頁原始碼裏。用戶端呼叫亦會被廣告攔截器攔掉，並在重新整理時重複觸發。 |
建議規則
| ID | 規則 | 代價是甚麼 |
|---|---|---|
PB-O-01 | 傳送 ctx | click_id 缺失或過期時沒有後備歸因。 |
PB-O-02 | 傳送 txid 作為第二去重鍵 | 一旦 event_id 缺失，去重就會降級為查詢字串雜湊，這很脆弱。 |
PB-O-03 | 以真實值填寫 hash_id / hash_name 和 source_id / source_name | 沒有按連結或流量來源的細分。廣告系列表現欠佳時，你無法分辨是哪個投放位帶來了這些充值。 |
PB-O-04 | 傳送 country | 地區報表較弱；我們只能退回到推斷。 |
PB-O-05 | 把你自己的事件類型宏作為 event 傳送 | 失去能發現端點用錯（PB-R-02）的交叉核對。 |
PB-O-06 | 在你知道時聲明 is_new_customer 和 first_deposit_ts | 我們無法用自己的首存判定來印證你的首存分類。 |
PB-O-07 | 若你採用分攤歸因模型，聲明 attribution_share | 歸因會被當作全額歸因處理，同時高估 RevoSurge 和你自己的貢獻。 |
必要項修復方式
PB-R-01 — 金鑰錯誤或缺失
修復： 在 URL 中加上 k=<your postback key>。金鑰在對接時發放 — 如果你沒有，請向你的客戶經理索取。
請當作共用密鑰處理：它只放在你後台保存的伺服器端 postback URL 中，絕不能出現在玩家瀏覽器看得到的任何地方。
PB-R-02 — 事件用錯了端點
修復： 使用與事件相符的路徑：
| 事件 | 路徑 |
|---|---|
| 玩家帳號建立 | /v1/pb/{partner}/registration |
| 首次充值 | /v1/pb/{partner}/first-deposit |
| 之後的充值 | /v1/pb/{partner}/repeat-deposit |
| 收入分成結算 | /v1/pb/{partner}/revenue |
| App 啟動（每一次啟動） | /v1/pb/{partner}/app-launch |
沒有其他路徑。App 安裝不是啟動，也沒有對應的 postback 路徑 — 安裝經由你的 MMP 回傳。從啟動路徑發出的註冊，或從註冊路徑發出的啟動，都會被永久錯誤歸類，與存款走錯路徑一樣。
/revenue 上的負 amount 是合法的 — 在收入分成之下，虧損的期間就是一次負的收入事件。如果你需要專門上報退款或追回（chargeback / clawback），請與你的客戶經理議定表示方式，而不要想當然地以為一條負收入會被這樣解讀。
把 event 宏設對並沒有幫助 — 它只作交叉核對記錄，絕不用於判定類型。只有路徑才算數。
PB-R-03 — 沒有可用的身分識別
修復： 傳送 click_id（首選）或 user_id。至少有一個必須解析為真實值。
請對照你的日誌檢查，而不是憑假設：回應是 200，所以你的後台幾乎肯定會把這些報告為已送達。
PB-R-04 — 未替換的宏
修復： 觸發一條測試 postback，然後讀回儲存下來的值。如果 click_id 以字面值 {click_id} 或 {sub1} 到達，代表你後台裏的宏名與該平台實際替換的宏名不一致。
在 click_id 和 user_id 以外的欄位中，未替換的宏不會導致 postback 被丟棄：該欄位會被略去，但字面值會保留下來供診斷 — 而這正是排查哪個宏名寫錯時要看的東西。
這是上線時最常見的失敗，因為一個在設定畫面裏看來沒問題的模板，只有在真實轉換經過它時才會暴露出來。
PB-R-05 — 首次與後續充值走同一路徑
修復： 你的後台必須知道一筆充值是否是該玩家的首存，並路由到對應的路徑。如果做不到，就把所有充值都發到 /repeat-deposit 並告知你的客戶經理 — 少算的首存可以補救；發到註冊路徑的充值則無法補救。
PB-R-06 — 時間戳用了秒
修復： ts 和 first_deposit_ts 都是 unix 毫秒。把 10 位數的值乘以 1000。
秒級值會被偵測、修正，並視為契約偏離 — 事件以修正後的時間儲存，同時觸發告警。所以它不會在你的日誌裏顯示為失敗，但也不是悄無聲息地出錯：你的客戶經理會收到通知。
另外，超過 30 天的舊事件或超過未來 60 分鐘的事件會被記錄並標記，絕不會被拒絕。
PB-R-07 — 金額缺失或正負號錯誤
修復： 在每一條充值和收入 postback 上，把 amount 作為帶正負號的十進位數傳送。結算幣別為 USD，且不作任何換算，所以請傳送 USD。
在收入分成之下，負值是合法且預期之內的：營運方虧損的期間就是一次負的收入事件。
PB-R-08 — 沒有穩定的 event_id
修復： 在你自己的系統中為每筆轉換產生一個全域唯一的 ID，並作為 event_id 傳送。任何重試都傳送完全相同的值。
去重優先次序依次為 event_id、txid，最後是查詢字串的逐位元組雜湊。雜湊後備並不是安全網：改變參數次序、新增一個欄位，或對某個值重新編碼，同一筆轉換就會被計為兩次。 這一點在 /app-launch 上最要緊：同一玩家會多次啟動 App，若沒有 event_id 和 ts，兩次啟動可能產生相同的 URL，被合併成一條。
PB-R-09 — 重試行為錯誤
修復：
| 回應 | 意思 | 是否重試 |
|---|---|---|
200 {"status":"ok"} | 已寫入持久化儲存 | 否 |
200 {"status":"ignored"} | 沒有可用的身分識別 — 請修正負載 | 否，結果會完全一樣 |
503 {"status":"unavailable"} | 寫入未被確認 | 是 |
403 | 金鑰錯誤或 IP 不獲允許 | 否 |
200 確認的是寫入已完成，而不只是我們收到了請求。
PB-R-10 — dry run 沒有關掉
修復： 從後台註冊的 URL 中移除 dry run 參數。dryrun、dryrun=1 和 dryrun=true 都會被接受，所以請搜尋 dryrun，而不是某個確切的字串。dry run 回應帶有回應標頭 X-Ingest-Mode: dryrun，且不記錄任何內容。
PB-R-11 — 識別碼與你的其他追蹤不一致
修復： 在 Web 追蹤器（user_id）、S2S（identity.client_user_id）和 postback（user_id）中，每個玩家使用同一個識別碼。同樣的字串、同樣的大小寫，不要一處帶前綴而其他地方不帶。
這一項出錯時每條 postback 都會成功，只是數字是錯的。事後修正亦不會合併已經拆分開的檔案。
PB-R-12 — 從瀏覽器觸發 postback
修復： 使用你聯盟平台的伺服器端 postback 功能來觸發。像素或用戶端呼叫會把 k 金鑰放進網頁原始碼，會被廣告攔截器攔掉，而且玩家每次重新整理都會重複觸發。
RevoSurge 亦可能把 postback 限制在你的出口 IP 白名單內 — 請向你的客戶經理確認是否已為你啟用，因為啟用後來自瀏覽器的呼叫會以 403 失敗。
建議項修復方式
PB-O-01 — 沒有 ctx
修復： 傳入你的平台提供的投放情境宏。click_id 缺失或過期時，歸因正是靠它還原的。
PB-O-02 — 沒有 txid
修復： 把你的交易 ID 作為 txid 傳送。它是第二去重鍵，也是你們財務團隊對帳時依據的欄位。
PB-O-03 — 分類欄位為空
修復： 把 hash_id / hash_name 對應到你的連結或帳號識別碼，把 source_id / source_name 對應到你的流量來源。
請傳送真實值，而不是佔位符。在這裏填一個常數比留空更糟，因為它看來已經填好，卻會悄悄破壞所有以它為基礎的細分報表。
PB-O-04 — 沒有 country
修復： 如果你的平台提供玩家國家，請傳送它。
PB-O-05 — 沒有 event 宏
修復： 把你自己的事件類型宏作為 event 傳送。它絕不會改變轉換的分類方式 — 那是端點路徑的職責 — 但端點用錯這類問題，正是靠它在扭曲一整個月的報表之前被發現。
PB-O-06 — 沒有首存聲明
修復： 當你的系統知道 is_new_customer 和 first_deposit_ts 時，請傳送它們。我們讀不懂的值會記為空值，而不是 0。
PB-O-07 — 沒有歸因份額
修復： 如果你在多個來源之間分攤歸因，請在 attribution_share 中聲明你的份額。它會作為你方的聲明被記錄 — 絕不會被換算標度，也不會被乘進 amount。
本頁無法檢查的兩件事
- 你的後台在真實轉換發生時確實會觸發。 即使平台的 postback 規則已被停用、套用到錯誤的廣告系列，或被一個永遠不會符合的條件過濾掉，你貼進瀏覽器的 URL 依然能通過本頁的每一條規則。只有上線測試才能證明它確實會觸發。
- 你的總數與我們的一致。 歸因窗口、分攤歸因模型和結算時點都會合理地改變數字。請按
event_id和txid對帳，而不是比較總數。
下一步
所有必要規則都通過後，前往交付與上線。