> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primeearn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Survey IFrame Integration

> Embed the Prime Earn survey wall into your app or website using an IFrame or WebView. Step-by-step setup guide covering URL parameters, design customisation, postback handling, and go-live checklist.


# Survey IFrame Integration Guide

Embed the Prime Earn survey wall directly into your app or website using an IFrame or WebView. This guide walks you through the full setup in six steps.

***

## Step 1 — Get Your URL

Your dedicated survey wall URL is:

```
https://monetize.primeearn.com/?app=XXXXXXXX&uuid=Test123
```

Replace `XXXXXXXX` with your **Publisher App ID** and `Test123` with your **user's unique identifier** (see [Step 3](#step-3--pass-parameters)).

<Info>
  **Need the combined wall (Surveys + Games)?** Use `https://monetize.primeearn.com/featured?app=XXXXXXXX&uuid=Test123` instead.
</Info>

***

## Step 2 — Implement in Your App or Website

Choose the integration method that fits your platform:

### WebView (Mobile Apps)

Load the URL inside a native WebView component. Make sure the WebView has:

* JavaScript enabled
* DOM storage enabled
* Redirect/navigation handling so external links open in a browser

### IFrame (Web)

```html theme={null}
<iframe
  src="https://monetize.primeearn.com/?app=XXXXXXXX&uuid=Test123"
  width="100%"
  height="700"
  frameborder="0"
  allow="clipboard-write"
  title="Prime Earn Survey Wall"
></iframe>
```

### New Browser Tab

If an IFrame is not suitable, open the URL in a new tab:

```js theme={null}
window.open(
  'https://monetize.primeearn.com/?app=XXXXXXXX&uuid=Test123',
  '_blank',
  'noopener,noreferrer'
);
```

***

## Step 3 — Pass Parameters

Replace the `uuid` placeholder with a **unique, stable identifier** for the current user. This ties survey completions to the correct account.

| Parameter   | Required     | Description                                                                                                                              |
| ----------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `app`       | Yes          | Your Publisher App ID (provided in your dashboard)                                                                                       |
| `uuid`      | Yes          | A unique, persistent ID for the end user                                                                                                 |
| `maid`      | If available | Mobile Advertising ID — IDFA on iOS or GAID on Android. Must be provided when available; significantly improves performance.             |
| `age`       | No           | User age (`0–150`). Passing this skips the age onboarding question in surveys.                                                           |
| `gender`    | No           | User gender: `m` (Male) or `f` (Female). Passing this skips the gender onboarding question.                                              |
| `zip`       | No           | Postal / ZIP code. Passing this skips the location onboarding question.                                                                  |
| `locale`    | No           | Interface language. Pass `en` or `en-US` to set the wall language to English. Currently only English is supported.                       |
| `source`    | No           | Numeric traffic source ID. Use the ID from the lookup table below.                                                                       |
| `network`   | No           | Numeric network ID. Use the ID from the lookup table below.                                                                              |
| `placement` | No           | Describes where in your app the wall is embedded (e.g. `post_level`, `main_menu`). Helps compare performance across multiple placements. |

<Tip>
  When `zip`, `gender`, or `age` are passed, users skip related onboarding questions in surveys — significantly improving their experience and match rate.
</Tip>

**Source & Network ID Reference**

Pass the numeric `ID` as the value for both `source` and `network`. Choose the row that best describes how the user arrived in your app.

| ID | Network                  | Source type     |
| -- | ------------------------ | --------------- |
| 1  | Google                   | Paid UA         |
| 2  | Facebook                 | Paid UA         |
| 3  | Instagram                | Paid UA         |
| 4  | Organic Google           | Organic         |
| 5  | Unknown                  | Other           |
| 6  | Other                    | Other           |
| 7  | Referral / Tell a friend | Organic         |
| 8  | Apple Search Ads         | Paid UA         |
| 9  | TikTok Ads               | Paid UA         |
| 10 | Bidease                  | Paid UA         |
| 11 | Mintegral                | Paid UA         |
| 12 | AppLovin                 | Paid UA         |
| 13 | iOS organic              | Organic         |
| 14 | IronSource / Unity Ads   | Paid UA         |
| 15 | Moloco                   | Paid UA         |
| 16 | Liftoff                  | Paid UA         |
| 17 | Vungle                   | Paid UA         |
| 18 | Email                    | Organic / Owned |
| 19 | Push notification        | Organic / Owned |

**Example with a real user ID:**

```
https://monetize.primeearn.com/?app=myApp1234&uuid=user_abc_987
```

<Warning>
  Never reuse `uuid` values across different users. Each user must have a stable, unique ID to ensure rewards are attributed correctly.
</Warning>

***

## Step 4 — Customize Design

The survey wall supports several design parameters you can append to the URL.

| Parameter | Values                   | Description                      |
| --------- | ------------------------ | -------------------------------- |
| `theme`   | `light` / `dark`         | Sets the color scheme            |
| `color`   | Hex code (e.g. `3498db`) | Primary accent color (no `#`)    |
| `logo`    | URL-encoded image URL    | Your brand logo displayed at top |

**Example:**

```
https://monetize.primeearn.com/?app=XXXXXXXX&uuid=Test123&theme=dark&color=3498db
```

<Tip>
  Match the `theme` parameter to your app's current color mode for a seamless user experience.
</Tip>

***

## Step 5 — Handle Rewards via Postback

When a user completes a survey, Prime Earn fires a **server-to-server postback** to your configured callback URL.

### Postback URL Format

Configure your callback URL in the dashboard. Prime Earn will substitute the placeholders at the time of the event:

```
https://your-server.com/reward?user={user_id}&amount={reward}&type={type}&tx={tx_id}
```

### Postback Parameters

| Parameter  | Type    | Description                                    |
| ---------- | ------- | ---------------------------------------------- |
| `{reward}` | Integer | Amount of in-app currency to award to the user |
| `{payout}` | Float   | Publisher payout in USD                        |
| `{type}`   | Integer | Event type (see table below)                   |
| `{user}`   | String  | The unique user ID you passed as `uuid`        |
| `{tx_id}`  | String  | Unique transaction ID for deduplication        |

### Survey Event Types (`{type}`)

| Value | Event          | Description                                 |
| ----- | -------------- | ------------------------------------------- |
| `1`   | Complete       | User successfully finished a survey         |
| `2`   | Screenout      | User was screened out mid-survey            |
| `3`   | Bonus          | Bonus reward event                          |
| `4`   | Reconciliation | A previously paid event has been reconciled |

### Whitelisting IPs

Ensure your server accepts postback requests from these Prime Earn IPs:

```
168.119.57.82
49.12.33.196
49.13.14.251
```

<Warning>
  Reject any postback requests that do **not** originate from these IPs to prevent reward fraud.
</Warning>

***

## Step 6 — Go Live

Before enabling for all users, run through this checklist:

* [ ] Replace `XXXXXXXX` with your real Publisher App ID
* [ ] Replace `Test123` / `uuid` with your real user ID logic
* [ ] Configure your postback URL in the Prime Earn dashboard
* [ ] Whitelist the Prime Earn IP addresses on your server
* [ ] Test a full survey completion in a staging environment and verify your postback receives the correct parameters
* [ ] Verify deduplication logic using `{tx_id}`

Once all checks pass, deploy and start earning!