Setup Checklist

Get the CPX App ID and optional secure hash from publisher.cpx-research.com → your app
Create the realtime integration under Integrations → Realtime Integrations → Create
Click Test on the integration page header
Approve publishers on the container offer and set margins, on the Offer and Publisher pages as usual
Set the CPX postback URL at publisher.cpx-research.com → Postback settings

ℹ️ Container Offer

Saving an integration provisions one real offer under the chosen advertiser. It anchors tracking links, publisher access, rules, budgets, margins, and conversions. It's created Private, Active, CPA, revenue-share, WEB, and all countries, because the network does its own targeting. Don't add targeting to it.

Step 1 - Create the Integration

Go to Integrations → Realtime Integrations → Create.

Field	Value
Name	Any label, e.g. `CPX Research`
Advertiser	The advertiser the container offer is provisioned under. Cannot be changed later.
Adapter	CPX Research. MAPPABLE means one tile per survey. Cannot be changed later.
Enabled	On. Off stops listing and sends clicks to the fallback URL.
App id	CPX App ID from `publisher.cpx-research.com`

Advanced Settings (collapsed, all optional)

Field	Default	Meaning
App secure hash	–	CPX secure hash. When set, every request is signed with `md5(user_id-hash)`. Must match the app's setting in CPX.
Surveys per listing	12	Surveys returned per user list.
Display title / description / image	–	Only used by IFRAME and ECOMMERCE adapters (one tile for the whole wall). Ignored for CPX.
Fallback URL	none	Where a click lands when CPX cannot resolve it (timeout, survey gone). Becomes the container offer's landing page.
Click timeout (ms)	1500	How long a click waits for CPX before falling back.
List cache TTL (s)	300	How long a user's list is cached. CPX asks for 120s or less.

Click Save. The page header now shows the container offer id.

Step 2 - Test

Test on the integration page calls CPX with your own IP and browser as test user swaarm-test, lists surveys, then resolves a click on the first one. Expect listItems: ok, N items and a resolved CPX URL.

ℹ️ 0 items usually means CPX has no surveys for your IP or country right now, or the App ID or secure hash is wrong. Retry from a different network or check the credentials.

Step 3 - Publishers and Margins

The container offer is Private. A publisher, including the rewarded app's own publisher, needs Approved offer access before it sees any surveys.

Payout per survey comes from CPX (payout_publisher_usd) and is your revenue. Publishers see it net of margin, resolved in this order: publisher + container offer, then publisher, then container offer, then advertiser. No margin means the full payout is shown.

ℹ️ The usual margin priority rules apply here just like on any other offer. For example, if CPX pays $10 for a survey and a 50% margin is set (at the offer-publisher, offer, or advertiser level), the publisher or user sees a $5 payout.

Step 4 - CPX Postback

In CPX → Postback settings, point CPX at the container offer's postback URL on your tracking domain:

https://track.{yournetwork}.swaarm-clients.com/postback?click_id={subid_1}&sale_amount={amount_usd}

⚠️ Replace {yournetwork} with your own Swaarm postback domain.

Swaarm plants its click id in CPX subid_1 on every click, so {subid_1} is what links the completion back. subid_2 carries <publisherId>_<subId> for your own reference. Exact placeholder names are shown in the CPX postback settings screen.

How It Works at Runtime

List - ask CPX per user

The rewarded app (realtimeOffers) or publisher API calls Swaarm. Swaarm asks CPX for that user (id, IP, user agent, country) and returns one item per survey: survey (N min), completion rate, payout, event Survey completed. Cached per user for the list TTL.

Click - resolve live, then 302

The link is the container offer link plus user_id and unique1=<survey id>. Swaarm records the click, re-fetches the user's surveys with the click id as subid_1, and redirects to that survey's CPX link. Timeout or survey gone means the fallback URL.

Conversion - normal postback

CPX posts back with subid_1 = click id. A normal conversion lands on the container offer, event Survey completed, revenue from sale_amount. Rules, budgets, publisher postbacks, and rewarded crediting apply as for any offer.

In reports, the container offer is the offer. The survey id is in unique1.

Publisher API

⚠️ Replace {yournetwork} with your own Swaarm tracking domain.

GET https://feed.{yournetwork}.swaarm-clients.com/realtime/v1/offers?api_key=<publisher key>&user_id=<end user id>

Param	Notes
api_key or token	Publisher API key
user_id	Required. The publisher's end-user id (becomes CPX `ext_user_id`).
user_ip, user_ua	Override the caller's IP and user agent. Send the end user's, not the server's, or CPX returns nothing.
country, os	Override device detection.
pub_sub_id	Publisher sub id, appended to click links.
integration_id	Limit to one integration.
limit, offset	Paging, max 500.
format=html	Quick visual offerwall for debugging.

Response: offers[] with item_id, name, description, click_url, payout (USD, net of margin), points, events[].

Troubleshooting

Symptom	Check
Test says 0 items	App ID and secure hash. CPX may have no surveys for your IP. Retry from another network.
No surveys for a user or publisher	Integration Enabled; container offer Active; publisher has Approved access; API call includes a real `user_ip` and `user_ua`.
Clicks land on the fallback URL	CPX slower than the click timeout, or the survey expired since listing. Lower the list TTL, or raise the timeout modestly.
User A's survey opens for user B	Each CPX link is bound to the user it was listed for. Never share links between users.
Conversions missing	CPX postback URL uses `click_id={subid_1}` and your tracking domain. Check Postback logs on the container offer.
Payout looks too high or low	Margin hierarchy above. CPX `payout_publisher_usd` is gross revenue.
Adapter or Advertiser greyed out	By design after creation. Create a new integration to change them.

CPX Research Surveys Integration (Realtime Integrations)