Offerwall Integration: Iframe, Link or API?

Offerwall integration: iframe, link or API?

There are five common ways to integrate an offerwall: open a link in a new tab, embed it in an iframe on your website, load it in a WebView inside your app, open it in an in-app browser tab, or load offers through an API and show them in your own design. For most websites, an iframe on its own page is the best balance of effort and experience. For native apps, open the link in a WebView or an in-app browser tab, or use a native SDK. Choose the API only if you need full control of the design and can build and maintain it.

On Moonetix, everything except the API opens the same signed offerwall link, so the real choice is between the offerwall link (opened, embedded, or behind the floating button), the Offers API, and the mobile SDKs for Android, iOS, Flutter, React Native, and Unity. Every app has all of them.

Whichever you choose, two parts stay the same: your server signs the link or request for the signed-in user, and your server credits rewards from postbacks. How to show the wall and how to credit users are separate decisions. This guide covers the first. For the second, the Postbacks docs have the verification code and the rules for each status.

Link, iframe, WebView, browser tab and API side by side

The three integrations on Moonetix

Every Moonetix app has three integrations:

• Offerwall: the hosted wall, opened with the app’s signed offerwall link. The link works anywhere: in a new tab, a mobile WebView, a browser extension tab, a Telegram bot or Mini App, a Discord message, or a game. On https pages of the website you registered for the app and its subdomains, you can also embed it in an iframe, or open it in a pop-up with the optional floating Earn button.
• Offers API: the offers as JSON, shown in your own design.
• Mobile SDK: the same offerwall in a native screen of your Android or iOS app, from com.moonetix:offerwall on Android, MoonetixOfferwall on iOS, the moonetix_offerwall Flutter plugin, the @moonetix/react-native-offerwall React Native package, or the com.moonetix.offerwall Unity plugin. Your server creates a single-use session token, and no key or salt ships in the app. The Android SDK, iOS SDK, Flutter SDK, React Native SDK, and Unity SDK docs have the setup.

All three use the same App ID, keys, and postback settings, and the Integration tab has a switch for the offerwall, the Offers API, and the mobile SDK for Android, iOS, Flutter, React Native, and Unity, each with its ready-to-copy code. You can use several at once or switch at any time, and your postbacks and reports show which integration each result came from, so you can see which earns more. The floating button is covered in Add a floating Earn button to any website.

The foundation: a signed link built on your server

On Moonetix, the wall for each user is one URL:

https://wall.moonetix.com/{APP_ID}?user_id={USER_ID}&hash={HASH}

The user ID is the ID of the signed-in user in your system and must never change for the same person. The hash is an HMAC-SHA256 of that user ID with your app’s link hash salt, so nobody can edit the link to open the wall as someone else. The salt is a secret: build the link on your server and send only the finished URL to the browser or app. The Offerwall link docs have the code in PHP, Node.js, and Python, and Check a link, in Integration status on the Integration tab, has a Test a link tool that shows the exact link your server should produce.

The link needs no SDK, and even the API hands you ready-signed start links for each offer.

Option 1: the offerwall link

The simplest integration is a button that opens the signed link in a new tab or window. It works everywhere, with no domain restrictions and no layout work: on any website, in a browser extension tab, from a Telegram bot or Mini App, in a Discord message or newsletter, or from a game with Unity’s Application.OpenURL. That makes it a good way to go live quickly.

The cost is that users leave your page, and some never come back to see their balance update. Generate the link when the user clicks, or when the page loads for a signed-in user, and never cache one user’s link where another user could get it.

In a native mobile app, there are two good ways to open the link without sending users out of your app.

In a mobile app: a WebView

A WebView renders the wall inside your app’s own screen, so you keep your header, a close button, and your look. Iframe domain rules do not apply because the page is not framed by a website: the Moonetix link opened directly in a WebView works anywhere. The flow is always the same:

1. The app asks your backend for the wall link, using the user’s normal session.
2. Your backend builds the signed link and returns it.
3. The app loads that link in the WebView.

What to handle on Android and iOS:

• JavaScript. Android’s WebView guide notes that JavaScript is disabled in a WebView by default. The wall needs it, so enable it for this screen.
• Store and external links. Many offers send users to an app store page or another app. Android’s documentation shows how to intercept navigation with a WebViewClient and shouldOverrideUrlLoading(), and hand links you do not want inside the WebView to the system. Do the equivalent on iOS, and test a store link from a real offer before release.
• Back and close. Give users an obvious way out, and make the back button go back inside the wall before it closes the screen.
• Balance refresh. Rewards reach your server through postbacks, not through the page. Reload the user’s balance from your backend when the WebView closes.
• No bridges you do not need. Do not expose app functions to pages in the WebView. Android’s documentation warns that a JavaScript interface lets JavaScript control your app and should only be used with content you wrote.

In a mobile app: an in-app browser tab

Android Custom Tabs and iOS SFSafariViewController open a page in a browser view on top of your app. Google’s Custom Tabs overview describes them as powered by the user’s preferred browser, with a shared cookie jar and permissions model, so saved sign-ins and passwords work as usual. Apple’s SFSafariViewController documentation says interactions with the web interface are not visible to your app. The result is fewer edge cases with store redirects and sign-ins.

The trade-off is less control: you cannot restyle the browser chrome or read what happens inside. That is fine for an offerwall, since everything your app needs arrives through postbacks. If your WebView keeps fighting store links, an in-app browser tab is often the quickest fix. For a game engine, How to add an offerwall to a Unity game walks through the browser and WebView options in C#.

Option 2: embed the offerwall in an iframe

An iframe puts the wall inside your own page, under your header and navigation. The basic embed from the docs is:

<iframe title="Offerwall" src="https://wall.moonetix.com/{APP_ID}?user_id={USER_ID}&amp;hash={HASH}"
  style="border:0;width:100%;height:100vh"></iframe>

The frame is as tall as the screen and scrolls on its own, so there is no height to guess. Under a fixed header, use something like calc(100vh - 64px). The embed docs list every option, and How to add an offerwall to WordPress and Offerwall PHP integration show the server code for two common stacks.

Three details decide whether it works well:

• It only loads on your registered website. For safety, the wall only loads inside frames on https pages of the website you registered for the app and its subdomains. Browsers enforce this with the frame-ancestors rule of Content Security Policy, which MDN’s frame-ancestors reference describes as the list of valid parents that may embed a page. If the frame stays blank on a staging domain or a second site, that is why. Embed it on the registered domain or a subdomain, or register the other site as its own app. An app’s website cannot be changed after you create the app, so a new domain needs a new app.
• Give it space. Put the wall on its own page, so users do not get a scroll bar inside a scroll bar, and keep the style from the code: without it, browsers show a small 300 by 150 pixel box. Check it at phone width.
• Test in more than one browser. The wall runs on a different site from yours, so browsers treat what it stores as third-party. The WebKit team wrote that Safari now blocks cookies for cross-site resources by default, and Mozilla made Total Cookie Protection, a separate cookie jar for each website, the default for all Firefox desktop users. If an offer flow misbehaves only inside the frame, open the same link directly in the same browser to narrow it down.

Build the iframe URL on your server when you render the page, exactly like the offerwall link. Never put the salt in front-end JavaScript to build it in the browser.

Prefer not to give the wall a page of its own? On the same registered website, the optional floating Earn button opens the same offerwall in a pop-up from any page after a click, with the same App ID and signed link. Add a floating Earn button to any website shows the snippet and its options.

Option 3: the Offers API

With the Offers API, your server calls GET https://api.moonetix.com/v1/offers with the app’s API key for one user at a time and gets that user’s offers as JSON: titles, requirements, rewards already converted to your currency, and a start_url for each offer. You show them in your own cards and filters. When a user picks one, they open its start link, which shows the offer on a Moonetix page styled with your Design tab colors and sends them on to the advertiser’s app or site. The response also includes a link to the user’s My offers page on the offerwall.

The extra freedom comes with extra work. Before choosing it, make sure you can:

• Show each offer’s requirements accurately, so users know what counts as complete. Unclear instructions lead to rejections and support tickets.
• Keep the list fresh. Caching one user’s list for a few minutes is fine; hours is not.
• Give users a visible way to My offers, so they can follow their offers and report a missing reward.
• Keep the API key on your server, never in a page or an app bundle.

The full walkthrough, with caching, sorting, and an offer card template, is in Build your own offerwall with an Offers API. If you are not sure, start with the ready-made wall. Its Design tab covers currency icon, colors, corner radius, card padding, and font size, which is enough for most brands to make the wall feel native.

Which offerwall integration should you choose?

• A website with signed-in users: the iframe on its own page, or the floating button if users browse many pages.
• A native mobile app or game: the offerwall link in a WebView if you want it inside your UI and can test store links, or in an in-app browser tab for the least effort.
• A website and a mobile app with the same users: one app covers both. Embed the iframe on the site and open the same offerwall link in the mobile app, with the same user ID in both, so users see one My offers list on both.
• A community such as Discord or Telegram: the offerwall link, built per member by your bot. For Mini Apps, see Add an offerwall to a Telegram Mini App.
• A product with a strict design system: the Offers API, if you can take on the work above. The hosted offerwall keeps running on the same app while you build it.

Common integration mistakes

1. Building the hash in the browser or the app, which exposes the salt. Anyone with it can open the wall as any user.
2. Using a device ID as the user ID, so a reinstall creates a new user and earlier rewards cannot be matched.
3. Mixing up keys: the link hash salt signs the wall link, and the postback secret key verifies postbacks. They are different values.
4. Testing the iframe on a domain you did not register and assuming the wall is broken.
5. Crediting from the page instead of from postbacks.

The Testing and troubleshooting docs list the error pages you may see, such as Link not valid or Missing user ID, with the fix for each.

Frequently asked questions