Offerwall Documentation

Introduction

An offer wall is a page that appears within your app that offers users rewards or different incentives in exchange for spending money or completing some action that is specified. For example, offer walls can award users in-game currency or extra “lives” in exchange for downloading another app you have created or watching an advertisement about a product you sell. Offer walls essentially create a win-win advertising situation for users because they can either choose to spend money or time digesting you advertising and be rewarded for it, or simply ignore your ad and continue with their experience.

Hang My Ads Offerwall can be included in:

Mobile Apps: You need to configure your app to read the response of the HMA offerwall URL and use either the HTML5 to create an offerwall screen using Hang My Ads design or use the JSON response to include Hang My Ads offers within your own design.
Mobile Web: If you have GPT mobile website or similar, you can include Hang My Ads offerwall and show it to your users. All it takes is to use the offerwall URL in an iframe and the offerwall will automatically adjust to your website.

Offerwall request example

Each offerwall request contains a query string of parameters, which are essentially key-value pairs that are used to reward your users with the correct amount of currency used and know which offers they should or should not be seeing. The offerwall automatically detects the country the user is at and the device he is on, therefor only showing relevant offers to the user.
Some of these parameters are required (such as Publisher ID) and others are optional (such as GAID).

All offerwall requests must contain the pub parameter, which specifies the ID of your registration within our platform, and an unique identifier of the install.
You can also include the device ID (GAID or IDFA) to have access to offers that require it, the currency you pay your users and the percentage of your payout that is attributed to them. For example:

https://offerwall.hangmyads.com/ow?pubid=1234&subid=UNIQUE_ID&google_aid=81b99d32-ef62-445d-9460-dce74066cb5a

Sample Response

The offerwall URL can provide a response in one of the following formats:

HTML: Returns full HTML5 ready to use code with all the offers matching the user device and geographic location.
JSON: Returns a JSON response for a single ad space or ad space group, containing creative details, tracking elements, details about the app being promoted, the payout of the campaign and HTML code ready to use.

If no format is requested, by default the full HTML5 offerwall will be returned. Please make sure it renders correctly in your app. Hang My Ads can assist all steps of the way so it can look like this:

Mobile Offerwall Parameters

Description

Each mobile offerwall request contains parameters, which are essentially key-value pairs that are used to correctly target the offerwall to your audience and keep track of which user did what offer for how much.

Parameters

Name	Data Type	Description	Required
pub	Integer	Your publisher ID on HangMyTracking. Contact your account manager if you don't know yours.	Yes
subid	String	A unique identifier of the click/conversion. Can be for example, the user ID on your side or a unique click ID generated.	Yes
curr	String	The currency of the reward you are giving your users (ex: points, coins, etc.)	No, inform your account manager that you want this set in the back office
percent	Integer	An integer that represents the percentage of your payout that you will give your users in the above currency.	No, inform your account manager that you want this set in the back office
subid2, subid3, subid4	String	These fields can be used to send any relevant information from your system. Should be used, especially if it's information needed to be returned on the S2S Postback.	No
ios_ifa	String	The iOS device identifier. When possible should be included as it will allow your users the possibility to be rewarded in the few iOS offers that require it.	No
google_aid	String	The Android device identifier. Like iOS IFA it should be sent so users can have access to the offers that require Device ID.	No
format	String	Parameter used to choose the type of response. Options are "html" or "json".	No, by default it will return the offerwall HTML

HTML Response

Description

By default the response of the Offerwall URL will be the HTML code, ready to display in the mobile app, which contains for each offer, the app name and icon, the reward and what the user needs to do to gain it, and also the proper click-tracking elements.

Example Response

                                
<body>
    <div class="wrapper-demo">
        <div id="dd" class="wrapper-dropdown-2" tabindex="1">
            <div class="top-tittle">Earn points<i><img src="inc/images/arrow3.png"/></i></div>
                <ul class="dropdown" style="margin-top: 4px">	
                    <div id="ticker"><div style="width: 100%;" class="innerWrap">
                        <div class="friends-grids list">
                            <div class="grids-left">
                                <a target="_blank" href="https://tracking.hangmytracking.com/click.php?oid=12251&aid=767&type=offertest&subid=UNIQUE_ID&subid5=37" >
                                    <img class="img-thumbnail img-circle" src="https://lh3.googleusercontent.com/QgmZeTp_1K_xFMoo_z4xWb5nTnYsOfAkF9tEbUFjZ7ZZf9v-QjunKjtHhiCSwgBs9HI=w300" />
                                </a>
                            </div>	
                            <a target="_blank" href="https://tracking.hangmytracking.com/click.php?oid=12251&aid=767&type=offertest&subid=UNIQUE_ID&subid5=37" >
                                <div class="friend-grid"> 
                                    <div class="reward">
                                        <button class="btn btn-success">+37 points</button>
                                    </div>
                                </div>
                            </a>
                            <div class="grids-right">
                                <a target="_blank" href="https://tracking.hangmytracking.com/click.php?oid=12251&aid=767&type=offertest&subid=UNIQUE_ID&subid5=37" ><h2>Lovoo</h2></a>
                            <ul class="grids-right-info">
                                <li class="chat"> Install + Facebook Login + Swipe 3 times</li>
                                    <div class="clear"> </div>
                            </ul>
                            </div>
                            <div class="clear"> </div>
                        </div>
                        <div class="friends-grids list">
                            <div class="grids-left">
                                <a target="_blank" href="https://tracking.hangmytracking.com/click.php?oid=12508&aid=767&type=offertest&subid=UNIQUE_ID&subid5=35" >
                                    <img class="img-thumbnail img-circle" src="https://lh3.googleusercontent.com/QgmZeTp_1K_xFMoo_z4xWb5nTnYsOfAkF9tEbUFjZ7ZZf9v-QjunKjtHhiCSwgBs9HI=w300" />
                                </a>
                            </div>	
                            <a target="_blank" href="https://tracking.hangmytracking.com/click.php?oid=12508&aid=767&type=offertest&subid=UNIQUE_ID&subid5=35" >
                                <div class="friend-grid"> 
                                    <div class="reward">
                                        <button class="btn btn-success">+35 points</button>
                                    </div>
                                </div>
                            </a>
                            <div class="grids-right">
                                <a target="_blank" href="https://tracking.hangmytracking.com/click.php?oid=12508&aid=767&type=offertest&subid=UNIQUE_ID&subid5=35" ><h2>Lovoo</h2></a>
                            <ul class="grids-right-info">
                                <li class="chat"> Install + Register with Facebook + swipe 10 times in the match game</li>
                                    <div class="clear"> </div>
                            </ul>
                            </div>
                            <div class="clear"> </div>
                        </div>
                    </div></div>
                </ul>
            </div>
    </div>
    <div class="copy-right">
                    <p>Install for free</p>
    </div>
</body>

JSON Response

Description

When the request URL includes the parameter format=json the response will be a JSON enconded response with the following fields:

id: ID of the Offer on Hang My Tracking platform.
categories: Geos and Categories of the offer.
offer_name: Name of the app being promoted.
description: The steps that the user needs to do in order to get the reward (conversion).
categoriesID: IDs of the Categories of the campaign.
countries: Country codes of the campaign.
epc: Current EPC value of the campaign.
conditions: General conditions of the campaign.
preview_URL: Landing page (generally App Store or Google Play page) where the user is taken after clicking on the offer.
daily_cap: The number of daily conversions available on that offer.
installed: 1 if the current user already concluded this offer or 0 if he hasn't.
daily_convs: The number of times your users already converted on this offer today.
payout_cents: How much, in cents, the offerwall owner receives for each conversion.
pay_type: The business model of the campaign. CPI if the conversion is on install and open, CPA if at an event inside the app or CPC if users get payed on theclick.
pay_curr: The currency of the amount in "payout_cents" (ex: USD, EUR).
thumbnail: Icon of the app that should be used to display the offer on the offerwall.
tracking_url: The URL that needs to be called every time the user clicks on the offer and that will take them to the "preview_URL".
promo: 1 if there is an active promotion with extra reward".
prev_reward: the amount of reward without promotion".
reward: the total amount of reward of the campaign".
currency: the currency of reward of the offerwall".
goals: array of the post attribution events available in the campaign".

Example Response


[
	{
        "id": 43122,
        "categories": "US 2029 Incent/iOS/CPA/Utilities",
        "offer_name": "VPN Surfshark",
        "description": "Buy 1 Year Subscription (New Users Only) ",
        "conditions": "End Date: TBD. Requires iOS 13.0.0 or later.",
        "preview_URL": "https://apps.apple.com/US/app/id1391782046?mt=8",
        "daily_cap": 5,
        "categoriesID": " 6, 21, 8, 47",
        "countries": " US",
        "installed": 0,
        "daily_convs": 0,
        "payout_cents": 1470,
        "pay_type": "CPA",
        "pay_curr": "USD",
        "thumbnail": "https://banners.hangmyads.com/files/uploads/Off_A_73117.png",
        "last_name": "VPN Surfshark",
        "epc": 122.5,
        "goals": {
            "1": {
                "goal_name": "Purchase",
                "pay_cents": "1470",
                "event_desc": "Complete a 1 Year Subscription",
                "reward": 1029
            }
        },
        "promo": 0,
        "prev_reward": 1029,
        "reward": 1029,
        "currency": "Points",
        "tracking_url": "https://tracking.hangmytracking.com/click.php?oid=43122&aid=7777&subid=USER_ID&subid2=&subid3=&ios_ifa="
    },
    {
        "id": 37355,
        "categories": "US 5162 Incent/iOS/Direct/CPE/MultiReward/Games",
        "offer_name": "Dice Dreams",
        "description": "Play the game and Reach Kingdom 50 getting rewarded along the way (New Users Only).",
        "conditions": "End Date: TBD. Required iOS 12.0 and up",
        "preview_URL": "https://apps.apple.com/US/app/id1484468651",
        "daily_cap": 250,
        "categoriesID": " 17, 22, 44, 45, 8, 6",
        "countries": " US",
        "installed": 0,
        "daily_convs": 0,
        "payout_cents": 11262,
        "pay_type": "CPA",
        "pay_curr": "USD",
        "thumbnail": "https://banners.hangmyads.com/files/uploads/Off_A_71611.png",
        "last_name": "Dice Dreams",
        "epc": 35.54,
        "goals": [
            {
                "goal_name": "tutorial_completion",
                "pay_cents": "35",
                "event_desc": "Complete the Tutorial",
                "reward": 14
            },
            {
                "goal_name": "purchase",
                "pay_cents": "182",
                "event_desc": "Make a Purchase",
                "reward": 73
            },
            {
                "goal_name": "kingdom_8_restored",
                "pay_cents": "105",
                "event_desc": "Reach Kingdom 8",
                "reward": 42
            },
            {
                "goal_name": "kingdom_12_restored",
                "pay_cents": "175",
                "event_desc": "Reach Kingdom 12",
                "reward": 70
            },
            {
                "goal_name": "kingdom_30_restored",
                "pay_cents": "592",
                "event_desc": "Reach Kingdom 30",
                "reward": 237
            },
            {
                "goal_name": "kingdom_40_restored",
                "pay_cents": "3500",
                "event_desc": "Reach Kingdom 40",
                "reward": 1400
            },
            {
                "goal_name": "kingdom_50_restored",
                "pay_cents": "4800",
                "event_desc": "Reach Kingdom 50",
                "reward": 1920
            }
        ],
        "promo": 0,
        "prev_reward": 4505,
        "reward": 4505,
        "currency": "Points",
        "tracking_url": "https://tracking.hangmytracking.com/click.php?oid=37355&aid=7777&subid=USER_ID&subid2=&subid3=&ios_ifa="
    },
    {
        "id": 46346,
        "categories": "US 5174 Incent/iOS/Search CPI/DS/Games",
        "offer_name": " Block Blitz: Skillz Puzzle Win",
        "description": "Install the app from results page and open it (New Users Only)",
        "conditions": "Requires iOS 12.0 or later.",
        "preview_URL": "https://apps.apple.com/us/app/block-blitz-skillz-puzzle-win/id1200942200",
        "daily_cap": 35,
        "categoriesID": " 6, 45, 8, 26, 36",
        "countries": " US",
        "installed": 0,
        "daily_convs": 0,
        "payout_cents": 50,
        "pay_type": "CPI",
        "pay_curr": "USD",
        "thumbnail": "https://banners.hangmyads.com/files/uploads/Off_A_71579.png",
        "last_name": " Block Blitz: Skillz Puzzle Win",
        "epc": 11.17,
        "promo": 0,
        "prev_reward": 20,
        "reward": 20,
        "currency": "Points",
        "tracking_url": "https://tracking.hangmytracking.com/click.php?oid=46346&aid=7777&subid=USER_ID&subid2=&subid3=&ios_ifa="
    }
]

Hang My Ads Offerwall Documentation

Offerwall

Details