Server to Server (S2S) 整合指南 (Chinese)

1. 簡介

本文件旨在指導合作夥伴如何設定 Appier 的伺服器對伺服器 (Server-to-Server, S2S) 整合。透過此對接，您可以將用戶在您 App 內的關鍵行為 (例如：安裝、開啟、購買等) 即時地回傳給 Appier，並讓我們根據這些行為，將轉換成效歸因到對應的廣告點擊或曝光

2. 設置追蹤連結 (Tracking URL)

請提供您的點擊與曝光追蹤連結，並在連結中置入下述的 click_id 參數，以便 Appier 帶入點擊資訊。

• 點擊連結範例 (Click URL)：

http://clk.yourtrackerdomain.com/?click_id=${short_id}

• 曝光連結範例 (Impression URL)：

http://imp.yourtrackerdomain.com/?click_id=${short_id}

追蹤連結參數說明

名稱 (* 代表必傳數值)	敘述	參數數值 (Click tracker)
Click ID *	Appier click ID 備註: 這個參數最多可容納 400 bytes。請確認您的系統也支援至這個限制。	${short_id}
廣告識別碼 (IDFA / AAID)	用戶的裝置廣告識別碼。 - iOS: IDFA (Apple iOS IDFA) - Android: AAID (Google Advertising ID)	${idfa}
Publisher ID	加密處理後的 Publisher ID	${partner_id}
Channel ID	加密過後的渠道/APP/網站名稱 備註: 此為選填參數。若您的 Publisher 需要區分不同渠道的成效，請帶入此數值	${channel_id}
Creative ID	Appier Creative ID	${crpid}
Creative Label	Appier Creative Label	${cr_label}

備註: 如果您有其他參數希望我們帶入追蹤連結中，請與您的 Appier 窗口聯繫

3. S2S Postback API 規範

當用戶在您的 App 中完成特定行為事件 (例如購買)，您的伺服器需要發送一個 GET 請求到 Appier 的 Postback Endpoint，以通知我們此轉換事件的發生

API 基礎資訊

• Endpoint: https://your_postback_endpoint.appier.net/limit (注意：您的正式 Endpoint 將由 Appier 窗口提供，此處僅為範例)

• Method: GET

API 參數說明

在發送請求時，請將以下資訊作為 URL 的查詢參數 (Query Parameters) 帶入。

• ★ 表示必要參數。

• ☆ 表示條件式必要參數 (例如：iOS 裝置必要，或 Android 裝置必要）

參數名稱	必要	描述	範例
asi	★	Appier Click ID (此為用戶點擊廣告時，由 Appier 產生並透過追蹤連結傳遞給您的值)。 備註: 若該用戶非來自 Appier 的廣告流量，此欄位請傳遞空值。	1234567890_abcdefghijklmnop
idfa	★	廣告識別碼 (iOS IDFA / Android AAID)。 備註: iOS IDFA 為大寫；Android AAID 則為小寫。	8CE56A2A-A2FD-4E16-8430-6DB542A4BD4D
action_id	★	您所定義的事件名稱，用於區分不同的用戶行為。 (請參考下方第 4 節：支援事件清單)	type_purchase
os	★	作業系統 (請使用小寫 ios 或 android)。	ios
ip	★	用戶裝置的 IP 位址。 注意： 請勿傳送您伺服器的 IP。	1.2.3.4
ios_app_id	☆	iOS 適用。 您的 iOS App 在 App Store 上的應用程式編號 (Bundle ID)。	id861796017
android_package_name	☆	Android 適用。 您的 Android App 的應用程式編號 (Package Name)。	com.xxx.mobile.shopping
idfv	☆	iOS 適用。 iOS IDFV (Apple 供應商識別碼; Identifier for Vendors)。 備註: 此 ID 為 iOS 系統特有，且應為大寫。	F1C0D8C2-0F82-43A2-A5C5-12CA555D07B8
attributed	★	用於標示該用戶是否歸因於 Appier。 傳送 1 代表歸因於 Appier；0 代表非歸因。	1
x_rv	★	訂單總金額 (Revenue)。 適用事件: type_purchase, type_cart	998
appier_cu	★	訂單幣別 (Currency)。 適用事件: type_purchase, type_cart	TWD
json	★	產品明細，為一個 JSON Array 格式的字串，需進行 URL Encode。 適用事件: type_purchase, type_cart, type_product	(見下方說明)
partner_id		Appier Publisher ID
chid		Appier Sub-publisher ID (Channel ID)
crpid		Appier Creative ID	abcde135
att_status		ATT (App Tracking Transparency) 狀態 (僅適用於 iOS)。 值為 1 或 0。	1
language		裝置設定的語言。	zh
osv		裝置的作業系統版本。	13.4.1
device_model		裝置型號。 備註: 若包含特殊字元，請進行 URL Encode。	iPhone12,5
carrier		電信商。 備註: 若包含空白或中文字，請進行 URL Encode。	TStar
app_version		App 的版本號。	9.0.8
country		用戶所在國家。格式為 ISO 3166-1 alpha-2 的兩位小寫字母。	tw
city		用戶所在城市。	Taipei
ua		用戶裝置的 User Agent 字串。	Mozilla/5.0 (iPhone; CPU iPhone OS 18_7_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Mobile/15E148 Safari/604.1
timestamp		事件發生的時間戳 (Unix Timestamp)，單位為秒。 備註: 當回傳延遲時，此參數有助於精準對齊報表。	1678886400
x_uid		您系統內部的用戶唯一識別碼 (User ID)。	user-1234
postback_id		Postback 的唯一識別碼。 備註: 用於排除重複的 Postback 請求，建議每次請求都產生一組新的 ID。	abc-def-123-456

4. 支援事件清單 (Event List)

請提供您系統中的事件名稱 (Event Name) 與 Appier action_id 的對應清單

以下為 Appier 建議的標準事件名稱，若您系統中既有的事件名稱與此不同，請告知您的 Appier 窗口，我們將為您完成對應設定。

建議的 action_id	對應的用戶行為
type_install	App 下載/首次安裝
type_open	開啟 App
type_home	瀏覽首頁
type_login	完成登入
type_listpage	瀏覽分類頁/搜尋結果頁
type_product	瀏覽商品詳情頁
type_addcart	加入購物車
type_cart	瀏覽購物車
type_purchase	完成購買

各事件建議帶入的參數

Events	x_rv & appier_cu	JSON
Install
Open
ViewListPage		V
Product View		V
Add to Cart		V
View Cart	v	V
Purchase	V	V

5. 產品資訊 JSON 格式 (重要)

若事件涉及產品資訊（如 type_product, type_purchase），請務必以JSON Array格式準備產品明細，並在放入 URL 前進行 URL Encode。

JSON 結構:

[
  {
    "productID": "商品編號",
    "unit": 數量(數字),
    "price": 單價(數字),
    "currency": "幣別"
  }
]

範例:

[
  {
    "productID": "12345678",
    "unit": 1,
    "price": 800,
    "currency": "TWD"
  },
  {
    "productID": "4365445",
    "unit": 2,
    "price": 350,
    "currency": "TWD"
  }
]

備註： 若您無法提供數量 (unit) 或單價 (price)，請傳入空字串 ""

6. Postback URL 完整範例

• 「開啟 App」事件的範例請求:

http://your_postback_endpoint.appier.net/limit?asi={click_id}&partner_id={partner_id}&chid={channel_id}&crpid={crpid}&att_status=1&idfa={ios_idfa}&idfv={idfv}&appier_cu={currency}&language={language}&country={country}&city={city}&ip={ip}&os=ios&osv={os_version}&carrier={operator}&ua={user_agent}&app_version={app_version}&ios_app_id={app_id}&attributed={attributed}&action_id=open&postback_id={postbackid}

• 「完成購買」事件的範例請求:

http://your_postback_endpoint.appier.net/limit?asi={click_id}&partner_id={partner_id}&chid={channel_id}&crpid={af_c_id}&att_status=0&idfa={aos_idfa}&idfv=&x_rv={revenue}&appier_cu={currency}&json={event-value}&language={language}&country={country}&city={city}&ip={ip}&os=android&osv={os_version}&carrier={operator}&ua={user_agent}&app_version={app_version}&android_package_name={android_package_name}&attributed=0&action_id=purchase&postback_id={postbackid}

附錄: HTTP Status Code

HTTP Status Code:

Appier 伺服器在收到您的 Postback 請求後，會回傳標準的 HTTP 狀態碼

Status Code	Description
200	OK
400	Bad Request
404	Not Found
413	Request Entity Too Large
414	Request URI Too Long
500	Internal Server Error
502	Bad Gateway
503	Service Unavailable
504	Gateway Timeout