● Set up · Affiliate
Partner offers
signed postbacks credit points.
List offers from affiliate partners. When a user completes one, the partner's server calls your offerPostback function with an HMAC signature, and the user receives points. Your own payment from the partner is under your agreement with them.
01How it works
- You create the offerConsole → Offers: title, description, URL (the partner's tracking link), points, partner name, order, optional image URL, active.
- The app opens the linkWhen the user taps the offer, the app opens your URL in the browser and adds
sub_id=<uid>andoffer_id=<offerId>to it (app/lib/ui/screens/offers_screen.dart). Ask your partner to passsub_idback to you asuid. - The partner calls your postbackAfter the user completes the offer, the partner's server calls the URL below with a signature.
- The function credits once
offerPostback(firebase/functions/src/offers.ts) checks the signature, ignores duplicates of the sametx, refuses inactive offers, banned users and switched-off offers, applies the daily cap (economy.offerDailyCap, default 10) and credits the offer's points.
02The postback URL and its signature
https://REGION-PROJECT.cloudfunctions.net/offerPostback?offer={offerId}&uid={uid}&tx={tx}&sig={sig}| Parameter | Value |
|---|---|
offer | The offer id from the console. |
uid | The user id (the sub_id the app added to the link). |
tx | A unique transaction id from the partner. A repeated tx is ignored. |
sig | hex(HMAC-SHA256(secret, offer:uid:tx)) |
The secret. Each offer gets its own 32-byte secret when you create it. The console shows it once; only an owner can create or rotate it. Give it to the partner over a private channel. Once you set Backend → Cloud Functions base URL, the console shows the postback URL with your values filled in.
Responses
| Status | Body | Meaning |
|---|---|---|
| 400 | bad request | A parameter is missing or malformed (sig must be 64 hex characters). |
| 403 | bad signature | The signature does not match the offer's secret. |
| 200 | credited | Points added. |
| 200 | duplicate, unknown_user, inactive_offer, banned, offers_disabled, daily_cap | Accepted but not credited, so the partner stops retrying. |
Test a signature on your computer (replace the values):
printf '%s' "OFFER_ID:USER_UID:TX123" | openssl dgst -sha256 -hmac "OFFER_SECRET" | awk '{print $2}'03Before you list an offer
- Offers credit points, never money. Do not promise users cash for completing offers.
- Do not list offers that require a purchase or a deposit to be credited, or that drive app installs in ways your ad network or store forbids (incentivised installs). Read your partner's and Google Play's rules.
- The commercial agreement with the partner, and any tracking it requires, are yours.