Web Offerwall Integration Guide
There are two available methods to integrate the AdGem Offerwall into your website or app:
- Direct Link - Opens the Offerwall in a new tab/window
- iFrame / WebView - Embeds the Offerwall within your page
Requirements
Account Requirements:
- You have an active AdGem Account
- You have added your app to your Account
App Approval:
- Your app has been approved in the AdGem system
By default, your app will not have access to AdGem's offers until you complete the initial integration steps and your app is approved. Contact your dedicated Publisher Support Advocate with any questions about the approval process.
:::
Platform Requirements
Web Offerwall Requirements
- Modern web browser with JavaScript enabled
- HTTPS-enabled website (recommended for production)
- Server-side postback endpoint
- Android: 9.0 and higher
- iOS: 15.8 and higher
Step 1 - Create a New Property
- Click on Properties & Apps in the left navigation
- Click on the New Property button
- Select Desktop/Web from the Platform dropdown
- Complete the form and create the property
You must have a unique Property/App ID for each website you want to integrate the Offerwall on. For example, if you have multiple website URLs, they each must be set up separately from the AdGem Dashboard.
Step 2 - Get Your Integration Links
- Click Options > Edit on your property
- Navigate to the Offerwall tab
Integration Links
Once on the Offerwall settings page, you can find the integration links to add to your website:
- Direct Link - Labeled "Web Offerwall Direct Link"
- iFrame - Labeled "Full Screen iFrame Code"
Required Parameters
Player ID
IMPORTANT: The Player ID is Required
The player_id parameter must be set with a unique identifier for each user in your application. This identifies the player so that virtual currency can be attributed to their account via the postback request. The player ID must remain constant for each unique player to:
- Prevent players from completing an offer more than once
- Ensure players receive their rewards correctly
Missing Player ID
Tracking URL clicks that do not contain a player_id value will be redirected to a 404 error page.
Player ID Structure Requirements
| Requirement | Details |
|---|---|
| Case | Letters must be lowercase |
| Characters | Alphanumeric characters, hyphens, and underscores only |
| Max Length | 256 characters |
| Forbidden | Emojis, special characters, uppercase letters |
Good Examples:
abc-123-efg-456user_12345player-a1b2c3d4
Bad Examples:
aBc-123-Efg-456(contains uppercase)player@123!(contains special characters)user-😀(contains emoji)
Mobile Advertising IDs (for in-app traffic)
When possible, please append the following parameters:
| Parameter | Description |
|---|---|
gaid | Google Advertising ID, available when using Google Play Services |
idfa | Apple Advertising ID, available when the user has not limited ad tracking |
Optional Parameters
All parameter names and their values are case-sensitive.
| Parameter | Description |
|---|---|
limit | Limit the amount of offers returned to a set number |
app_version | The version of your app where the click originated |
device | The user's device type (e.g., "Moto E Plus") |
device_name | The user's device name |
ip | The IP Address for the user |
useragent | The User Agent from the user's default browser app |
os_version | The user's Operating System version number |
platform | The platform the user's device is using (e.g., "ios") |
player_age | The user's age as set by the publisher |
player_gender | The user's gender as set by the publisher |
player_payer | A boolean value indicating if user has made purchases |
player_iap_total_usd | Total in-app purchase amount in USD |
player_created_at | A datetime stamp without the time zone |
player_level | The level achieved by the player |
placement | Integer value representing the ad unit placement |
c1 - c5 | Custom parameter values as set by the publisher |
Example Integration
Direct Link
<a href="https://api.adgem.com/v1/wall?appid=YOUR_APP_ID&playerid=USER_ID" target="_blank" rel="noopener noreferrer">
Open Offers
</a>
iFrame
<iframe
src="https://api.adgem.com/v1/wall?appid=YOUR_APP_ID&playerid=USER_ID"
width="100%"
height="600"
frameborder="0">
</iframe>
Best Practices
iFrame / WebView
For Publishers integrating the AdGem Web Offerwall via an iFrame or WebView:
- Ensure the iFrame or WebView is scalable according to device resolution
- Include a header image or divider to clearly indicate where your site ends and the Offerwall begins
- This helps your users understand what actions to take and improves navigation
- Makes the AdGem Offerwall better match with your native UI
Displaying offers natively
AdGem allows Publishers to pull offers and display them natively on their website or app. This integration type works especially well for featured placement sections.
Confirm user is eligible for the offer shown
We recommend that you receive Install Postbacks. Once you receive the install postback, check off the install to confirm that the user is eligible to continue the offer to receive rewards.
Common reasons a user may not be eligible:
- The user has previously completed or downloaded the offer
- The user is ineligible due to incorrect geo or device targeting
Track goal progression based on postbacks
The user should be able to see in your UI when a goal has been completed.
Show remaining days to complete an offer
Each offer in the API response includes an attribution_window_days value. Use this to dynamically show users how many days they have to complete the offer.
Follow up with users regarding their progression
Engage with users through in-app messaging or external channels (email, SMS, push notifications) to encourage them to complete in-progress offers. This provides achievement recognition and motivates users to engage with additional offers.
Additional Information
Customization
You can customize the Offerwall appearance including virtual currency name, icon, and multiplier. See the Customization Guide for details.
Postback Setup
If you have opted for a "Server Postback", on each successful offer completion AdGem will send a request to your server. See Postbacks to learn more.