> AffiliateOS Help Center. Index of every article for AI tools: https://www.affiliateos.ai/help/llms.txt

# Listen for wall events in your app

Hosted Offerwall · For publishers · Updated 30 October 2026
Web version: https://www.affiliateos.ai/help/offerwall/listen-for-wall-events

Inside an iframe or a WebView, the wall posts a message for each thing that happens, with a `type` that starts with `affiliateos.offerwall.`. Use them to size the frame, close the wall and log what users do. Never credit a user from an event: real conversions reach you only as postbacks.

## The events

| `type` | Payload | Sent when |
|---|---|---|
| `affiliateos.offerwall.ready` | `{ sessionId }` | The wall has loaded for a valid launch. |
| `affiliateos.offerwall.height_changed` | `{ height, tab }` | The wall loads, the user switches tab (`all`, `trending` or `my`), or an offer page opens or closes. Set your frame's height to `height`. |
| `affiliateos.offerwall.offer_started` | `{ offerId, sessionId, testMode }` | The user tapped **Get** and the start was recorded, just before they're sent to the offer. |
| `affiliateos.offerwall.offer_redirect` | `{ offerId, sessionId, url }` | Iframes only: the wall is about to open `url` in a new tab. A notice, not a request. |
| `affiliateos.offerwall.conversion_updated` | `{ offerId, goalId, sessionId }` | Only when a test goal completes. Test goals are switched off on live walls, so you won't receive it today, and it's never sent for real conversions. |
| `affiliateos.offerwall.close_requested` | `{ sessionId }` | The user tapped the wall's close control. Hide the frame or dismiss the WebView: the wall can't close itself. |
| `affiliateos.offerwall.error` | `{ error, offerId }` | Something failed. Codes below. |

## Listen in a web page

Give your iframe `id="offerwall"`, and check where each message came from before you trust it.

```js
const WALL = "https://offerwall.affiliateos.xyz";
const frame = document.getElementById("offerwall");

window.addEventListener("message", (event) => {
  if (event.origin !== WALL) return;
  const msg = event.data;
  if (!msg || typeof msg.type !== "string") return;

  switch (msg.type) {
    case "affiliateos.offerwall.height_changed":
      frame.style.height = msg.height + "px";
      break;
    case "affiliateos.offerwall.close_requested":
      frame.remove();
      break;
    case "affiliateos.offerwall.error":
      console.warn("Wall error", msg.error, msg.offerId);
      break;
  }
});
```

In a WebView, the wall posts to its own window instead. Inject a script that listens for the same messages there and forwards them through your WebView's bridge. [Add the wall to an app](https://www.affiliateos.ai/help/offerwall/add-to-mobile-app#host-it-in-a-webview) explains it.

## Error codes

| `error` | What happened | What the user sees |
|---|---|---|
| `click_failed` | The start couldn't be recorded. | "The offer didn't open. Try again." |
| `missing_redirect_url` | The start was recorded but came back with no offer link. | "The offer didn't open. Try again." |
| `redirect_blocked` | Iframes only: the browser blocked the new tab. The wall then tries to move your whole page to the offer. | Your page may change to the offer. If it can't, nothing opens, so open `url` from the `offer_redirect` you just received. |

## Who receives them

| Where the wall runs | Who hears the events |
|---|---|
| An iframe, on a wall with allowed origins | Your page, when its origin is on the list. Other pages hear nothing, and the browser won't show the frame there anyway. |
| An iframe, on a wall with no list | Any page that frames it. The events carry no session token and no secret. |
| Your own WebView | The wall's own window, where your injected script picks them up. |
| A browser tab (SFSafariViewController, Custom Tabs, a plain browser) | Nobody. Your app gets no events from a tab. |

## About sessionId

`sessionId` is the same on every event of one visit and different on the next. Use it to group events and match them to your own logs. It isn't a credential, it can't be used to call our API and its format has changed before, so store it as an opaque string.

> **Events never mean money.** No event says a user earned anything. Credit users from the [postback](https://www.affiliateos.ai/help/postbacks/set-up-postback-url) we send to your server, which is signed and carries `user_payout`. On the wall, `offer_started` means a tap, not a conversion.