ads | Game of Whales

ads method of REST API is used to get information about active cross-promotion advertisements for the user.

If the user has never logged the game in before, the method returns the error: {"code": "InternalServer", "message": "caused by UnprocessableEntityError: Profile not found"}.

 POST https://api.gameofwhales.com:8488/ads

version 2.0.0
version 1.0.0

version 2.0.0

REQUEST ARGUMENTS

Arguments are in JSON format with the Content-Type application/json.

Request argument	Required or optional	Type	Description
game	required	string	Game key.
user	required	string	User’s ID. Any string can be used, but it should be unique for each user.
common	required	object	Common information about the user. The object includes the following parameters:
{
ip	optional	string	User's IP. It's used to define country, timezone, timezone offset, weather. If the argument is not set, "country" argument should be defined.
country	optional	string	Code of the user's country. It's required if "ip" parameter is not defined. If "ip" is set, "country" argument will be ignored. The list of supporting countries is here.
locale	required	string	User's device's locale defined by RFC 1766. It's used to select the language of push notifications.
platform	required	enum	User's device's platform. Allowed values are "android", "ios", "macosx", "uwp", "web".
store	required	enum	Used store. Allowed values are "AmazonStore", "AppleAppStore", "Facebook", "GooglePlay", "HuaweiStore", "Kongregate", "MacAppStore", "Odnoklassniki", "SamsungApps", "SFRPixtel", "VK", "WindowsStore", "XiaomiStore", "Other".
version	required	string	User's application version.
expId	required	string	ID of A/B testing experiment. Should be sent as a confirmation of the user's participation in the experiment.
}

A template for a request using cURL on the command line:

curl -XPOST $URL -H 'Accept-Version: 2.0.0' -H 'Content-Type: application/json' -d @- << EOF 
$REQUEST_JSON
EOF

An example values:

URL = api.gameofwhales.com:8488/ads

REQUEST_JSON = {"game": "$YOUR_GAME_KEY", "user": "3A15982E-C4CB-0000-0000-D88861BA0C49", "common": {"ip": "91.232.111.204", "locale": "en_EN", "platform": "ios", "store": "AppleAppStore", "version": "1.0.0", "expId": "5d2effe09236b00e38e34c3b"}}

An actual request with the example values:

curl -XPOST 'api.gameofwhales.com:8488/ads' -H 'Accept-Version: 2.0.0' -H 'Content-Type: application/json' -H 'Content-Type: application/json' -d @- << EOF
{"game": "$YOUR_GAME_KEY", "user": "3A15982E-C4CB-0000-0000-D88861BA0C49", "common": {"ip": "91.232.111.204", "locale": "en_EN", "platform": "ios", "store": "AppleAppStore", "version": "1.0.0", "expId": "5d2effe09236b00e38e34c3b"}}
EOF

RESPONSE ARGUMENTS

Response argument	Required or optional	Type	Description
properties	required	object	User's properties. The object includes the following properties:
{
user	required	string	User’s ID.
group	required	string	User's group. The property is used for analyzing of push and special offer campaigns.
revenue	required	number	The current amount of the user's purchases.
custom property	optional	string, boolean, object	Additional custom properties. They are returned only if they are defined on Game of Whales side.
}
serverTime	required	timestamp	The current time of Game of Whales server.
ads	required	array	The list of active cross-promotion advertisements for the user. If there are no the ads the empty object will be returned. The ad details include the following properties:
[ {
content	required	object	The information about the advertisement.
{
portrait	required*	array	The array of images with the advertisement for portrait orientation. The array can include data about several images for several types of devices. * - at least one image in "portrait" or "landscape" section is required.
[{
url	required	string	The link to load the image.
height	required	number	The height of the image in px.
width	required	number	The width of the image in px.
}]
landscape	required*	array	The array of images with the advertisement for landscape orientation. The array can include data about several images for several types of devices. * - at least one image in "portrait" or "landscape" section is required.
[{
url	required	string	The link to load the image.
height	required	number	The height of the image in px.
width	required	number	The width of the image in px.
}]
title	required	string	The text title of the advertisement.
message	required	string	The text message of the advertisement.
}
camp	required	string	The ad campaign ID.
finishedAt	required	timestamp	The date of the ad finish. The advertisement will not be active after this date.
showedAt	optional	timestamp	The date when the advertisement was showed to the player.
bundleId	required	string	The bundle ID of the promoted game.
url	required	string	The link to download the promoted game from the store.
showFrequencyInMinutes	required	number	Defines how often the ad will be shown to the player.
} ]

Pay attention that "ads" method doesn't return the data about the experiment in which the user takes part.

An example of a response:

{
    "serverTime": 1558523473067,
    "properties": {
        "user": "3A15982E-C4CB-0000-0000-D88861BA0C49",
        "group": "b",
        "revenue": 30
    },
    "ads": [
        {
            "camp": "ad_cross_1558523400000_58ff3e2e30bb6d070389efff",
            "finishedAt": 1558609828883,
            "content": {
                "portrait": [
                    {
                        "url": "https://gow-iaps.s3.amazonaws.com/ads_portrait_...",
                        "width": 375,
                        "height": 812
                    },
                    {
                        "url": "https://gow-iaps.s3.amazonaws.com/7_ads_portrait_...",
                        "width": 1200,
                        "height": 1920
                    },
                    {
                        "url": "https://gow-iaps.s3.amazonaws.com/10_ads_portrait_...",
                        "width": 768,
                        "height": 1024
                    }
                ],
                "landscape": [
                    {
                        "url": "https://gow-iaps.s3.amazonaws.com/ads_landscape_...",
                        "width": 800,
                        "height": 450
                    },
                    {
                        "url": "https://gow-iaps.s3.amazonaws.com/7_ads_landscape_...",
                        "width": 640,
                        "height": 360
                    },
                    {
                        "url": "https://gow-iaps.s3.amazonaws.com/10_ads_landscape_...",
                        "width": 1024,
                        "height": 576
                    }
                ],
                "title": "Hey!",
                "message": "Look at the new game!"
            },
            "bundleId": "com.something.xxx",
            "url": "https://play.google.com/....",
            "showFrequencyInMinutes": 1440
        }
    ]
}

version 1.0.0