Documentation

Advertising using the Fair Advertising Network (F.A.N)

Overview

Displaying F.A.N ads helps the community and helps you. You earn credits into your balance which you can use for Wirthwhile Gaming services, such as promoting your own games.

F.A.N packages will be generated periodically using the lowest performing promotions at the time of creation. Creating a self balancing system where no one promotion is dominant.

F.A.N is best used in an area of your game where players can explore other games they might be interested in. Feel free to use F.A.N on your website as well.

Create a Package

Packages are created at https://wirthwhilegaming.com/developer/advertise/create.

Field Description
Name A reference just for you to easily find a advertisement package.
Maximum Advertisements Returned The most ads you will have returned. This number is not guaranteed to be this value, but will not exceed it.
Own Games This allows you to only display your own games, none of your games or mix them into the results. It is recommended that you display your own games but also the games from others.
Exclude Game Use this to make sure that the game you are advertising in is not shown in the results. This will ensure that a game is not advertising itself.
Adult Only Content This mostly pertains to violence levels in games. Pornographic and other inappropriate promotions will not be approved so you do not have to worry about those types of images appearing in your ads.
Category This is the first category used for filling ad results. If there are not enough ads in the category to fill to the maximum advertisements desired, games from other categories will be used so that you will always have results.

Making a Request

Using the package key for an advertising package found at https://wirthwhilegaming.com/developer/advertise, make a HTTP GET request to Wirthwhile Gaming to get your package that has been generated.

Here are some test packages to aid development.

Android

https://wirthwhilegaming.com/api/ads/get?package_key=test_android_key

iOS

https://wirthwhilegaming.com/api/ads/get?package_key=test_ios_key

Steam

https://wirthwhilegaming.com/api/ads/get?package_key=test_steam_key

Understanding the Response

When retrieving an Advertising Package, you will get an list of promotions in JSON format looking similar to this:

{
    "ads": [
        {
            "ref": "test_ad_ios_1",
            "title": "Sum Gems",
            "description": "How high can you sum your gems?",
            "store_url": "itms-apps://itunes.apple.com/app/id878367187",
            "web_url": "https://itunes.apple.com/app/sum-gems/id878367187",
            "callback_url": "https://wirthwhilegaming.com/api/track/ad_click?ad=test_ad_ios_1&pkey=test_package_key_ios",
            "image_url": "https://wirthwhilegaming.com/assets/img/sum_gems_ad_ios.png",
            "icon_url": "https://wirthwhilegaming.com/assets/img/sum_gems_icon.png"
        },
        {
            "ref": "test_ad_ios_2",
            "title": "That 9 Game",
            "description": "What game is it? Oh it is that 9 game.",
            "store_url": "itms-apps://itunes.apple.com/app/id944123579",
            "web_url": "https://itunes.apple.com/app/that-9-game/id944123579",
            "callback_url": "https://wirthwhilegaming.com/api/track/ad_click?ad=test_ad_ios_2&pkey=test_package_key_ios",
            "image_url": "https://wirthwhilegaming.com/assets/img/that_9_game_ad_ios.png",
            "icon_url": "https://wirthwhilegaming.com/assets/img/that_9_game_icon.png"
        }
    ]
}

Key Description
ref A unique reference to that promotion
title Usually the name of the game, but can be any text specified by the promoter
description A short description of the game to a maximum of 100 characters
store_url The place to buy the game. The URL should follow the formats:

Android

market://details?id=[Bundle Identifier]

iOS

itms-games://itunes.apple.com/app/id[App ID]

Steam

http://store.steampowered.com/app/[App ID]
web_url The place to to find out more about the game on the web. This could be the game homepage or a web URL for the store. The URLs will usually follow the formats:

Android

https://play.google.com/store/apps/details?id=[Bundle Identifier]

iOS

https://itunes.apple.com/app/[App Name]/id[App ID]

Steam

http://store.steampowered.com/app/[App ID]
callback_url The URL to send a request to when the player clicks on the promotion to record that it has been clicked
image_url The promotional image for the game
icon_url The icon image for the game

Tracking Clicks

To track clicks that a player makes on promotion make a HTTP GET request to the callback_url for that promotion. Using the example response above for the first ad in the list, you make a request to:

https://wirthwhilegaming.com/api/track/ad_click?ad=test_ad_ios_1&pkey=test_package_key_ios

It is suggested that you send a request to the callback_url without waiting for the response, then send the player to either the store_url or web_url. If the player is using the target platform that the ads are being delivered on, use the store_url instead of the web_url as they will go straight to the store. In the above example response, if the player is on an iOS device and click the Sum Gems advertisement, they should be sent to the URL:

itms-apps://itunes.apple.com/app/id878367187

How to Show Ads

The JSON response gives you all of the information you need to build the ads in the best way for your game. The data allows you to make banners, interstitials, app walls or something more creative.

  1. Make a web request to https://wirthwhilegaming.com/api/ads/get?package_key=your_key_here
  2. Display the ad image and/or the ad icon image using either image_url or icon_url image location URL.
    • Typically use the image_url for large interstitial ads
    • Typically use the icon_url for banner ads or app walls along with the app title and/or description.
  3. Make the ad clickable using the store_url or web_url. We recommend using the store_url if on a mobile device.
  4. When the player clicks on the ad, make a web request to callback_url, then send the player to the store_url or web_url.

This unity package shows examples of how to use the data to display ads.

Earnings

You will earn credits into your balance depending on the number of clicks you provided for the promotion. This is calculated on a daily basis per promotion.

Here is a simple example using 1 promotion and 2 advertisers:

  • The promotion has 100 credits available for the day. Wirthwhile Gaming takes 30 credits leaving 70 for the advertisers.
  • There were 1000 clicks for the promotion over the 24 hour period.
  • Advertiser 1 provided 600 clicks and Advertiser 2 provided 400 clicks for the promotion over the 24 hour period.
  • Advertiser 1 will be credited 42 credits as they accounted for 60% of the clicks for the promotion.
  • Advertiser 2 will be credited 28 credits as they accounted for 40% of the clicks for the promotion.