Server to Server (S2S) Postback Integration (English)

1. Introduction

This document is intended to guide partners on how to set up Appier's Server-to-Server (S2S) integration. Through this integration, you can send key user actions within your app (e.g., install, open, purchase, etc.) to Appier in real-time. This allows us to attribute conversions to the corresponding ad clicks or impressions.

2. Tracking URL Setup

Please provide your click and impression tracking URLs, and include the click_id parameter as described below, so that Appier can pass click information.

• Click URL Example: http://clk.yourtrackerdomain.com/?click_id=${short_id}

• Impression URL Example: http://imp.yourtrackerdomain.com/?click_id=${short_id}

Tracking Link Parameter Description

Name (* denotes required value)	Description	Macro Value (for your Click Tracker)
Click ID *	Appier click ID. Note: This parameter can hold a maximum of 400 bytes. Please ensure your system also supports this limit.	${short_id}
Advertising ID (IDFA / AAID)	The user's device advertising identifier. - iOS: IDFA (Apple iOS IDFA) - Android: AAID (Google Advertising ID)	${idfa}
Publisher ID	The encrypted Publisher ID.	${partner_id}
Channel ID	The encrypted channel/app/website name. Note: This is an optional parameter. If your Publisher needs to differentiate performance across different channels, please include this value.	${channel_id}
Creative ID	Appier Creative ID.	${crpid}
Creative Label	Appier Creative Label.	${cr_label}

If you have other parameters you would like us to include in the tracking link, please contact your Appier representative.

3. S2S Postback API Specification

When a user completes a specific event in your app (e.g., a purchase), your server needs to send a GET request to Appier's Postback Endpoint to notify us of this conversion event.

API Basic Information

• Endpoint: https://your_postback_endpoint.appier.net/limit (Note: Your official Endpoint will be provided by your Appier representative, this is just an example)

• Method: GET

API Parameter Description

When sending the request, please include the following information as URL query parameters.

• ★ Indicates a required parameter.

• ☆ Indicates a conditionally required parameter (e.g., required for iOS devices, or required for Android devices).

Name (* denotes required value)	Required	Description	Postback Parameter
asi	★	Appier Click ID (this is the value generated by Appier and passed to you through the tracking link when a user clicks an ad). Note: If the user is not from Appier's ad traffic, please pass an empty value for this field.	1234567890_abcdefghijklmnop
idfa	★	Advertising Identifier (iOS IDFA / Android AAID). Note: iOS IDFA should be uppercase; Android AAID should be lowercase.	8CE56A2A-A2FD-4E16-8430-6DB542A4BD4D
action_id	★	The name of the event you define to distinguish different user actions. (Please refer to Section 4 below: Supported Event List)	type_purchase
os	★	Operating system (please use lowercase ios or android).	ios
ip	★	The user's device IP address. Note: Please do not send your server's IP.	1.2.3.4
ios_app_id	☆	For iOS. Your iOS App's Bundle ID on the App Store.	id861796017
android_package_name	☆	For Android. Your Android App's Package Name.	com.xxx.mobile.shopping
idfv	☆	For iOS. iOS IDFV (Identifier for Vendors). Note: This ID is specific to the iOS system and should be uppercase.	F1C0D8C2-0F82-43A2-A5C5-12CA555D07B8
attributed	★	Used to indicate whether the user is attributed to Appier. Send 1 to represent attribution to Appier; 0 for non-attribution.	1
x_rv	★	Total order amount (Revenue). Applicable for events: type_purchase, type_cart.	998
appier_cu	★	Order currency (Currency). Applicable for events: type_purchase, type_cart.	TWD
json	★	Product details, as a URL-encoded JSON Array string. Applicable for events: type_purchase, type_cart, type_product.	(See description below)
partner_id		Appier Publisher ID
chid		Appier Sub-publisher ID (Channel ID)
crpid		Appier Creative ID	abcde135
att_status		ATT (App Tracking Transparency) status (for iOS only). Value is 1 or 0.	1
language		The device's configured language.	zh
osv		The device's operating system version.	13.4.1
device_model		Device model. Note: If it contains special characters, please URL Encode it.	iPhone12,5
carrier		Telecom carrier. Note: If it contains spaces or Chinese characters, please URL Encode it.	TStar
app_version		The app's version number.	9.0.8
country		The country where the user is located. Format is ISO 3166-1 alpha-2 two-letter lowercase code.	tw
city		The city where the user is located.	Taipei
ua		The user device's User Agent string.	Mozilla/5.0...
timestamp		The time the event occurred (Unix Timestamp), in seconds. Note: When postbacks are delayed, this parameter helps to accurately align reports.	1678886400
x_uid		Your system's internal unique user identifier (User ID).	user-1234
postback_id		A unique identifier for the postback. Note: Used to deduplicate postback requests. It is recommended to generate a new ID for each request.	abc-def-123-456

4. Supported Event List

Please provide a mapping between your system's event names and Appier's action_id.

Below are Appier's recommended standard event names. If your system's existing event names differ, please inform your Appier representative, and we will complete the mapping for you.

Recommended action_id	Corresponding User Action
type_install	App Download / First Install
type_open	Open App
type_home	View Home Page
type_login	Complete Login
type_listpage	View Category Page / Search Results Page
type_product	View Product Detail Page
type_addcart	Add to Cart
type_cart	View Cart
type_purchase	Complete Purchase

Recommended Parameters for Each Event

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

5. Product Information JSON Format (Important)

If the event involves product information (e.g., type_product, type_purchase), you must prepare the product details in JSON Array format and URL Encode it before placing it in the URL.

JSON Structure:

[
  {
    "productID": "Product ID",
    "unit": "Quantity (number)",
    "price": "Unit Price (number)",
    "currency": "Currency"
  }
]

Example:

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

Note: If you cannot provide the quantity (unit) or unit price (price), please pass an empty string "".

6. Full Postback URL Examples

• "Open App" Event Example Request:

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}

• "Complete Purchase" Event Example Request:

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}

Appendix: HTTP Status Codes

After receiving your Postback request, the Appier server will return a standard HTTP status code.

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