Integration guide for partners

Overview #

AppVero attributes app installs and in-app events to the touchpoint that drove them. As a partner you do two things: send clicks (and optionally impressions) through AppVero tracking links, and receive postbacks when AppVero credits an install or event to your media source.

Advertisers configure your postbacks in their AppVero account, so one integration works for every AppVero advertiser that runs campaigns with you.

Before you start #

• Media source ID — a stable identifier for your network, agreed with AppVero, for example examplenet_int.
• App ID — each advertiser app has one, for example app_7f3k9q2m. The advertiser shares it with you.
• Link host — the advertiser’s link domain: a vendor subdomain such as northwind.appvero.link or a custom domain such as go.northwind.example.
• Your macros — the placeholders your platform fills at click time (click ID, GAID, IDFA, campaign names…).
• A postback endpoint — an HTTPS URL that accepts GET requests and answers 2xx.

Click tracking links #

Use the click link as the destination (or click URL) of your ads. Fill the values with your macros:

https://<link-host>/c/<app_id>?media_source=<partner_id>&campaign=…&click_id={your_click_id}&gaid={gaid}&idfa={idfa}

https://northwind.appvero.link/c/app_7f3k9q2m?media_source=examplenet_int
  &campaign={campaign_name}&adset={adset_name}&ad={ad_name}&site_id={publisher_id}
  &click_id={your_click_id}&gaid={gaid}&idfa={idfa}

What happens on a click:

• The click is recorded with its parameters, the user agent and IP, and a new AppVero click ID.
• Android: the user is redirected to Google Play with a referrer that carries the AppVero click ID, so the install is matched deterministically through the Play Install Referrer.
• iOS: the user is redirected to the App Store; the install can be matched by IDFA when the user has granted ATT consent.
• In-app browsers are detected and handled (for example LINE opens the external browser; Facebook, Instagram and TikTok get an interstitial).
• Desktop visitors see a page with a QR code and store links.

Server-side clicks

Add av_redirect=false to record a click without redirecting. AppVero answers 200 with {"click_id": "<AppVero click ID>"}.

Impression links #

For view-through attribution, fire the impression link when the ad is shown. It accepts the same parameters as the click link and returns a 1×1 GIF.

https://northwind.appvero.link/i/app_7f3k9q2m?media_source=examplenet_int
  &campaign={campaign_name}&click_id={your_impression_id}&gaid={gaid}&idfa={idfa}

Clicks always beat impressions. The view window is set per app and defaults to 24 hours.

Click-time parameters #

All parameters are optional. On stored short links they override the link’s values unless the advertiser has locked them. Aliases are accepted so existing link templates keep working.

Device IDs & iOS privacy #

• Pass gaid on Android and idfa on iOS only when your platform has them with the user’s permission.
• Device-ID matching on iOS uses the IDFA only with ATT consent. The SDK sends the IDFA only when ATT is authorised.
• iOS installs from paid media without ATT consent are marked restricted and measured in aggregate through SKAdNetwork and AdAttributionKit. They are not attributed to a click and do not trigger install postbacks.
• Malformed or all-zero advertising IDs are flagged (id_malformed, id_zero).

Postbacks #

Advertisers configure a partner for your media source with two URL templates. AppVero calls them server-to-server when it credits your media source:

• Install postback — for attributed installs and re-attributions.
• Event postback — for in-app events of users attributed to you that are mapped to one of your events (or every event, if the advertiser enables “send all events”).

Organic, rejected and restricted installs, sessions, reinstalls and deep-link opens do not trigger postbacks.

https://postback.network.example/install?click_id={partner_click_id}
  &gaid={gaid}&idfa={idfa}&platform={platform}&country={country}&ts={install_ts_s}

https://postback.network.example/event?click_id={partner_click_id}
  &event={partner_event}&value={revenue}&currency={currency}&value_usd={revenue_usd}

{
  "media_source": "examplenet_int",
  "name": "Example Network",
  "install_postback_url": "https://postback.network.example/install?click_id={partner_click_id}&gaid={gaid}",
  "event_postback_url": "https://postback.network.example/event?click_id={partner_click_id}&event={partner_event}&value={revenue}",
  "event_mapping": { "av_purchase": "purchase", "av_registration": "sign_up" },
  "send_all_events": false,
  "include_revenue": true,
  "enabled": true
}

Macro reference

Macros are replaced with URL-encoded values. Empty values are sent as empty strings.

{revenue}, {currency} and {revenue_usd} are filled for events with revenue when the advertiser includes revenue in your postbacks.

Delivery & retries

• Postbacks are GET requests with the user agent AppVero-Postback/1.0. Redirects are not followed.
• Any 2xx response is a success. Respond quickly — requests time out after 10 seconds.
• Network errors, timeouts, 408, 429 and 5xx are retried with exponential backoff (starting at 5 seconds, up to 15 minutes apart) for up to 24 hours. Other 4xx responses are not retried.
• Requests to one endpoint are rate-limited per partner, so bursts are smoothed rather than dropped.
• Every attempt is logged for the advertiser with its status code and latency; query values are redacted in the log.
• Delivery is at-least-once: de-duplicate on {click_id} + {event_name} + {event_ts_s} or your own key.

Event mapping #

The advertiser maps AppVero event names to yours, for example av_purchase → purchase. The mapped name is available as {partner_event}; the original as {event_name}. Unmapped events are not sent unless “send all events” is on, in which case {partner_event} carries the AppVero name.

Recommended standard events (the av_ prefix is reserved):

• av_registration
• av_login
• av_tutorial_complete
• av_add_to_cart
• av_checkout
• av_purchase
• av_subscribe
• av_trial_start
• av_level_up
• av_share
• av_invite

S2S events #

Technology partners and advertiser backends can send events server-to-server with an API key that has the s2s scope. Each batch identifies the user by one of install_id, customer_user_id, gaid or idfv, and the events inherit the install’s attribution — including postbacks to the credited partner.

curl -X POST https://api.appvero.ai/v1/s2s/events \
  -H "Authorization: Bearer avk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_user_id": "u_123",
    "events": [{
      "event_id": "5b6c1d2e-8f90-4a1b-9c3d-2e4f6a8b0c1d",
      "name": "av_purchase",
      "ts": 1760003700000,
      "revenue": 49.90,
      "currency": "USD",
      "params": { "order_id": "NW-10293" }
    }]
  }'

• event_id is the idempotency key — resending the same event is safe.
• Event names match [A-Za-z0-9_.-]{1,64}; up to 50 params with string, number or boolean values.
• revenue needs an ISO 4217 currency.

Attribution rules #

• Last touch wins; clicks beat impressions.
• Android order: Play Install Referrer → Meta Install Referrer → device-ID click → device-ID impression → probabilistic (advertiser’s own media only) → organic.
• iOS order: Apple Ads (AdServices) → IDFA click (ATT authorised) → probabilistic (advertiser’s own media only) → organic. Paid installs without consent are restricted.
• Windows are set per app. Defaults: 7-day click window, 24-hour view window.
• Reinstalls of a known device keep their original attribution and don’t trigger install postbacks; re-engaged users can be re-attributed after a period of inactivity (defaults: 7 days inactive, 30-day window), which sends an install postback to the new source.
• Fraud checks run on the winning touchpoint. Rejected installs get no partner credit.

Fraud reason codes #

AppVero publishes every reason it uses to reject or flag traffic, so customers and networks can audit decisions. Codes are stable; new codes are only added, never renamed. They appear in the install response, in raw data (fraud_reason, fraud_flags), in the fraud report and in webhook payloads.

Testing checklist #

1. 1Your media source ID is agreed and used in every link (media_source=…).
2. 2Click links pass your click ID in click_id, and GAID / IDFA macros only where your platform has them with consent.
3. 3A test click from a real device redirects to the store (or the app, if installed) and appears in the advertiser’s click log.
4. 4A fresh install on an Android test device after the click is attributed to your media source with match_type=referrer or device_id.
5. 5Your endpoint receives the install postback with {partner_click_id} filled in, and answers with a 2xx status.
6. 6A mapped in-app event (for example av_purchase) triggers the event postback with the mapped {partner_event} and, if enabled, {revenue} and {currency}.
7. 7Impression links (if you use view-through) return a 1×1 GIF and are fired once per impression.
8. 8Rejected and flagged test traffic shows the expected reason code — for example installs from a datacenter VPN show ip_anonymous.
9. 9You can reconcile one install end to end using {click_id} or {partner_click_id} with the advertiser’s raw data.

Support #

Questions about an integration: [email protected]. Security issues: [email protected]. Not a partner yet?Apply here.