> For the complete documentation index, see [llms.txt](https://docs.perkox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkox.com/readme/web-offerwall-integration.md).

# Web Offerwall Integration

## Perkox Web Offerwall Integration

The **Perkox Web Offerwall** allows publishers to integrate the Perkox Offerwall into a web application, website, or web-based reward experience.

You can integrate the offerwall in two ways:

1. **Direct Link Integration** — redirect users to the Perkox Offerwall.
2. **iFrame Integration** — embed the Perkox Offerwall directly inside your web page.

Both methods require your **App ID** and a unique **Player ID** for each user.

***

## Integration URL

The Perkox Web Offerwall uses the following base URL:

```
https://perkwall.com
```

Example URL:

```
https://perkwall.com?app_id={YOUR_APP_ID}&player_id={YOUR_PLAYER_ID}&click_id={YOUR_CLICK_ID}
```

***

<figure><img src="/files/RyS67i17xtJRmm5paQcM" alt=""><figcaption></figcaption></figure>

## Required Parameters

| Parameter   | Description                                        | Required |
| ----------- | -------------------------------------------------- | -------- |
| `app_id`    | Your unique Perkox App ID                          | Yes      |
| `player_id` | Unique ID of the user inside your platform         | Yes      |
| `click_id`  | Optional tracking ID for click/session attribution | No       |

***

## Parameter Details

### `app_id`

Your `app_id` identifies your app or property inside Perkox.

You can find your App ID inside the Perkox Publisher Dashboard under your app/property integration settings.

Example:

```
app_id=83f34460********
```

***

### `player_id`

The `player_id` is the unique user identifier from your system.

This value allows Perkox and your backend to know which user should receive a reward after completing an offer.

Best practices:

* Use a stable internal user ID
* Do not use random temporary values
* Do not use sensitive personal information
* Make sure the same user keeps the same Player ID across sessions

Example:

```
player_id=user_12345
```

***

### `click_id`

The `click_id` is optional.

You can use it to track a session, click, or traffic source inside your own system.

Example:

```
click_id=click_98765
```

If you do not use click-level tracking, you can omit this parameter.

***

## Method 1: Direct Link Integration

Use the direct link method when you want to open the Perkox Offerwall in a new browser tab, new window, or full-page redirect.

### Direct Link Example

```html
<a href="https://perkwall.com?app_id={YOUR_APP_ID}&player_id={YOUR_PLAYER_ID}&click_id={YOUR_CLICK_ID}" target="_blank">
  Open Offerwall
</a>
```

Replace:

```
{YOUR_APP_ID}
```

with your Perkox App ID.

Replace:

```
{YOUR_PLAYER_ID}
```

with the unique user ID from your platform.

Replace:

```
{YOUR_CLICK_ID}
```

with your optional click/session tracking ID.

***

### JavaScript Example

```html
<button onclick="openPerkoxOfferwall()">
  Earn Rewards
</button>

<script>
  function openPerkoxOfferwall() {
    const appId = "YOUR_APP_ID";
    const playerId = "YOUR_PLAYER_ID";
    const clickId = "YOUR_CLICK_ID";

    const url = `https://perkwall.com?app_id=${encodeURIComponent(appId)}&player_id=${encodeURIComponent(playerId)}&click_id=${encodeURIComponent(clickId)}`;

    window.open(url, "_blank");
  }
</script>
```

***

## Method 2: iFrame Integration

Use the iFrame method when you want to embed the Perkox Offerwall directly inside your web application.

This is useful for dashboards, web reward apps, member areas, loyalty platforms, or web-based gaming experiences.

### Basic iFrame Example

```html
<iframe
  src="https://perkwall.com?app_id={YOUR_APP_ID}&player_id={YOUR_PLAYER_ID}&click_id={YOUR_CLICK_ID}"
  frameborder="0"
  style="width: 100%; height: 100%;"
></iframe>
```

***

### Recommended Responsive iFrame Example

```html
<div style="width: 100%; height: 100vh; overflow: hidden;">
  <iframe
    src="https://perkwall.com?app_id={YOUR_APP_ID}&player_id={YOUR_PLAYER_ID}&click_id={YOUR_CLICK_ID}"
    frameborder="0"
    allow="clipboard-read; clipboard-write"
    style="width: 100%; height: 100%; border: none;"
  ></iframe>
</div>
```

This makes the offerwall fill the available screen height and provides a better full-page experience.

***

## Dynamic iFrame Example

If your app generates the user ID dynamically, you can build the iFrame URL with JavaScript.

```html
<div id="perkox-offerwall-container" style="width: 100%; height: 100vh;"></div>

<script>
  const appId = "YOUR_APP_ID";
  const playerId = "USER_ID_FROM_YOUR_SYSTEM";
  const clickId = "OPTIONAL_CLICK_ID";

  const offerwallUrl = `https://perkwall.com?app_id=${encodeURIComponent(appId)}&player_id=${encodeURIComponent(playerId)}&click_id=${encodeURIComponent(clickId)}`;

  document.getElementById("perkox-offerwall-container").innerHTML = `
    <iframe
      src="${offerwallUrl}"
      frameborder="0"
      style="width: 100%; height: 100%; border: none;"
      allow="clipboard-read; clipboard-write"
    ></iframe>
  `;
</script>
```

***

## Recommended User Flow

A typical web offerwall flow looks like this:

```
User logs into your platform
→ Your system identifies the user
→ You generate the Perkox Offerwall URL with app_id and player_id
→ User opens the offerwall
→ User completes an offer
→ Perkox validates the conversion
→ Perkox sends a postback to your server
→ Your backend credits the user
```

***

## Reward Handling

Do **not** rely only on frontend behavior to credit rewards.

For production integrations, rewards should be handled server-side through your **Postback URL** configured in the Perkox Dashboard.

Recommended reward validation flow:

```
User completes offer
→ Perkox validates event
→ Perkox sends postback to your backend
→ Your backend checks player_id, click_id, status, and transaction ID
→ Your backend credits the user
```

This helps prevent:

* duplicate rewards
* fake client-side reward claims
* missed rewards
* incorrect user credits

***

## Postback Recommendation

Before going live, make sure your app has a working postback endpoint.

Example postback URL:

```
https://yourdomain.com/perkox/postback?user_id={player_id}&click_id={click_id}&reward={reward_amount}&payout={payout}&status={status}
```

Your backend should return HTTP `200` when the postback is received successfully.

***

## Best Practices

For a reliable integration:

* Always pass a valid `app_id`
* Always pass a stable `player_id`
* Use `click_id` if you need session or traffic-source tracking
* URL-encode all parameter values
* Use HTTPS on your website
* Make the iFrame container responsive
* Test the offerwall on desktop and mobile browsers
* Configure server-side postbacks before launch
* Do not credit rewards directly from frontend code

***

## Troubleshooting

### Offerwall Not Loading

Check the following:

* `app_id` is correct
* `player_id` is not empty
* URL parameters are properly encoded
* Your browser allows iFrames
* Your website is served over HTTPS
* The app/property is active in the Perkox Dashboard

***

### User Rewards Not Appearing

Check the following:

* The user completed the offer requirements
* Your postback URL is configured correctly
* Your backend is receiving Perkox postbacks
* Your backend is mapping `player_id` correctly
* Your backend prevents duplicate rewards
* The conversion status is `approved`

***

### iFrame Display Issues

Check the following:

* The parent container has a defined height
* The iFrame width is set to `100%`
* The iFrame height is set to `100%` or `100vh`
* CSS is not hiding or clipping the iFrame
* Test on both desktop and mobile devices

***

## Example Full Page Integration

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Earn Rewards</title>

  <style>
    html, body {
      margin: 0;
      padding: 0;
      width: 100%;
      height: 100%;
      background: #0b0f14;
    }

    .offerwall-container {
      width: 100%;
      height: 100vh;
      overflow: hidden;
    }

    .offerwall-frame {
      width: 100%;
      height: 100%;
      border: none;
    }
  </style>
</head>
<body>
  <div class="offerwall-container">
    <iframe
      class="offerwall-frame"
      src="https://perkwall.com?app_id=YOUR_APP_ID&player_id=YOUR_PLAYER_ID&click_id=YOUR_CLICK_ID"
      frameborder="0"
      allow="clipboard-read; clipboard-write"
    ></iframe>
  </div>
</body>
</html>
```

***

## Support

For questions, issues, or integration support, contact:

```
support@perkox.com
```

When contacting support, include:

* App ID
* Website URL
* Integration method used: Direct Link or iFrame
* Example Player ID
* Screenshot or screen recording of the issue
* Browser and device details