Offerwall Iframe Integration

Embed the Preads offerwall in your site with a single iframe. This is the recommended integration method and needs no server-side code.

You must pass userId. Without it the wall renders and looks completely normal, but every offer click fails silently and nothing is tracked. This is the single most common integration failure — see Why userId matters.

Requirements

  • An approved app in your publisher account. New apps are created pending and do not work until an administrator approves them.
  • That app's API Key.
  • A stable, unique userId for each of your end users.

A valid but unapproved app returns 403 App not found or inactive. A missing or unknown API key is rejected at validation and the browser is redirected to the home page instead — so a typo in the key shows up as your visitor landing on the homepage rather than an error. If the wall link sends users to your homepage, check the key character by character.

Basic implementation

Replace YOUR_API_KEY and YOUR_USER_ID. URL-encode the user ID when you build the URL. 

<iframe
  src="https://preads.hansaldev.com/wall?apiKey=YOUR_API_KEY&userId=YOUR_USER_ID"
  style="width:100%; height:800px; border:0; padding:0; margin:0;"
  scrolling="yes"
  frameborder="0">
</iframe>

The wall is responsive. It also works when opened directly in a browser tab, which is useful for testing.

Parameters

Parameter Required Description
apiKey Yes Your app's API key, from the app's detail page.
userId Yes Your unique identifier for this end user. Required for the wall to render, and required for click tracking and postback attribution.
Validation note. userId is accepted as an empty value at the wall endpoint itself, which is why an incomplete integration renders normally. It is not optional at the tracking endpoint the wall calls when a user clicks an offer — see below.

Why userId matters

Every request the wall makes on the user's behalf forwards your userId:

  • offer filtering and tab switching
  • the live-conversion ticker
  • the click that registers the offer

The first two tolerate an empty value. The click does not: the tracking endpoint requires it, so an empty userId makes the offer click fail validation. Because that click opens in a new browser tab, the failure is invisible on your page.

The consequences of an empty userId are:

  1. No click is recorded.
  2. Therefore no conversion, so no payout and no postback.
  3. Your reports stay empty and your balance never moves.
Always give each end user a distinct, stable ID. If the same ID is shared by several users their conversions are merged, and the platform's fraud checks treat them as one person. A common working pattern is your own numeric user ID, or an opaque random value you store against the account.

Keep the user ID URL-safe

The wall substitutes your userId into its own URLs without escaping it. If your ID can contain &, #, +, ? or a space, it will be corrupted and tracking will fail intermittently. Use an ID made of letters, digits, - and _, or percent-encode it yourself when you build the iframe URL.

Sub-parameters and attribution

Four optional sub-parameters, aff_sub through aff_sub4, let you carry campaign or placement data through the click and back out to your postback.

They belong on the tracking request, not on the wall URL, and you have to add them yourself — the wall does not accept them: 

GET https://preads.hansaldev.com/api/track?apiKey=YOUR_API_KEY&userId=YOUR_USER_ID&offerId=123&aff_sub=summer_sale&aff_sub2=placement_a

Values are stored on the click and echoed back to your postback as {aff_sub} – {aff_sub4}. Maximum length is 255 characters each.

All offerwall endpoints

The wall is one of several related endpoints. All of them take apiKey, and userId where noted.

Endpoint Purpose userId
GET /wall The main offerwall. This is the one to embed. Required
GET /surveywall Survey offers only. Use when you want a narrower wall. Required
GET /history The end user's own offer history — completed and pending, most recent 100. Good for a "my rewards" page. Required
GET /partners Directory of iframe partner networks available on the wall. Optional
GET /wall/partner/{network} One partner network's wall, where {network} is its slug. Accepts subId, which is stored as the click's aff_sub. Optional
GET /wall/offers JSON used by the wall to filter offers. Returns { success, offers[], count }. Accepts type = all | premium | offers | survey, and device. Optional
GET /wall/live-conversions JSON ticker of recent conversions across the platform. Returns { success, items[] }. Presentational only. Optional
GET /api/track Registers a click and redirects to the advertiser. Requires apiKey, userId and offerId. Required

If you only need the wall, embed /wall and ignore the rest. The JSON endpoints are listed for reference; they are not needed for a working iframe integration.

Fraud checks

Preads scores clicks before recording them. If a click trips a fraud rule the request is refused with:

403 Access Denied: Suspicious Activity Detected (<reason>)

The wall collects a device fingerprint on every page load and stores it against your userId, then sends the fingerprint with each click. You do not have to do anything for this to work.

If a legitimate user is blocked, check the reason in the message. Repeated clicks from one userId or one IP in a short window is the most common cause.

Notes and limits

  • Offers are selected from the visiting user's detected country and device, not from your app's settings. Your app's platform and currency do not filter which offers appear; the currency only affects how rewards are displayed on the wall.
  • Your app must be approved. Approval is checked on every request.
  • Conversions are tracked through the platform's postback system. See Postback Setup.
  • The wall endpoints are not currently rate-limited. Do not build a server-side proxy around them.
  • The Content Locker and Link Locker are separate integrations and have their own documentation.

Troubleshooting

Symptom Cause and fix
The wall link lands visitors on your homepage The API key is missing or unknown, so the request is rejected at validation and redirected to the home page. Compare the key against the app's detail page character by character.
403 App not found or inactive The key is correct but the app is still pending approval.
Wall renders but no earnings ever appear Almost always a missing or empty userId. Clicks fail validation silently. Verify the iframe src contains a non-empty userId.
Tracking fails only for some users Their userId probably contains &, +, # or a space and is being corrupted. Use a URL-safe ID.
403 Access Denied: Suspicious Activity Detected A fraud rule fired. Check the reason; usually repeated clicks from one user or IP.
Wall shows offers for the wrong device Targeting uses the visitor's own device detection, not your app's platform setting.
404 opening the wall URL directly Missing apiKey, or the app has not been approved yet.

Related documentation