Network Postback
Reward apps, boosting networks, and other media partners that run their own tracking systems typically ask you to "notify our endpoint when a conversion happens." adstage handles this as a per-link setting. Enter the callback URL the network gave you, and adstage calls it when a user who came through that link installs, purchases, or triggers another configured event.
No development work is required per network. Take their spec, enter it in the dashboard, and the integration is live.
1. Where to Configure
Open the Network Postback section in Deep Links > Create, or on the detail view of an existing link. The setting is stored per link, so create a separate link for each media partner and enter that partner's endpoint on it.
2. Settings
| Item | Description |
|---|---|
Install Postback URL | Required. The endpoint called when an install conversion occurs |
Event Postback URL | Optional. Endpoint for non-install events such as purchases. If empty, the install URL is used for all events |
Click ID Parameter | The name of the click identifier the network appends to the click URL. Defaults to click_id |
Postback Events | Which events trigger a postback. Defaults to install |
If the network says "we pass our click ID as a parameter named cb," enter cb as the Click ID Parameter.
3. URL Templates and Macros
Paste the URL the network gave you and use macros where values must be substituted.
The following macros are available.
| Macro | Value |
|---|---|
{click_id} | The click identifier the network passed at click time |
{adid} | Advertising identifier (IDFA on iOS, GAID on Android) |
{ifa} {idfa} {gaid} | Same value as {adid}. You can use whichever name appears in the network's spec |
{device_id} | The device identifier assigned by adstage |
{platform} | ios or android |
{event} | Event name (for example install, purchase) |
{timestamp} | When the event occurred |
{ip} | User IP address |
{campaign} | Campaign name |
Macros not on the list
If the network requires values of its own such as {sub_id} or {pub_id}, use them as-is. Any macro not on the list echoes back the click URL parameter with the same name.
In other words, if the network appended ?sub_id=abc123 to the click URL, {sub_id} in the postback is filled with abc123.
Please note
If the parameter is not present at click time, an empty value is sent. Confirm that the parameters in the network's spec are actually included in the click URL.
4. How It Works
-
A user clicks the network's ad and lands on the adstage tracking link. The click ID and the network's parameters are recorded at this point.
-
When that user installs or triggers a configured event, adstage attributes the event back to the network's click.
-
The macros in the URL template are replaced with real values and the network's endpoint is called.
Deduplication
The same event for the same click fires only once. Even if the user reopens the app or the event is collected more than once, the network is not notified twice.
Event names that mean the same thing, such as install and first_open, are treated as one, so only a single postback fires even if both arrive.
Retries on Failure
If the network's server is temporarily unavailable, adstage retries automatically so conversions are not silently lost.
| Item | Value |
|---|---|
| Retry attempts | Up to 8 (1 initial send + 8 retries) |
| Minimum retry interval | 3 minutes |
| Sweep interval | Failed records are checked every 5 minutes |
| Give-up threshold | Failures older than 24 hours |
5. What to Ask the Network Before Integrating
You only need four things from a new media partner.
- Postback URL — for installs, and a separate one for events if they have it
- Click ID parameter name — what they call the identifier on the click URL
- Required macros — which values they expect to receive
- Target events — installs only, or other events such as purchases
6. Cautions
- Postback settings are per link. If a network uses multiple links, configure each one.
- A postback fires only when attribution succeeds. Traffic that did not pass through the network's link is not eligible.
- Values are URL-encoded automatically. Do not pre-encode values in macro positions.
- Some networks signal success or failure in the response body. adstage judges by HTTP status code only, treating 2xx and 3xx as success. If a network returns 200 with an error in the body, adstage cannot detect the failure — ask them to return 4xx or 5xx on errors.