ads
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.2.0
version 2.1.0
version 2.0.0
version 1.0.0
version 2.2.0
There are no differences from version 2.0.0
version 2.1.0
There are no differences from version 2.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
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. |
| } | |||
A template for a request using cURL on the command line:
curl -XPOST $URL -H 'Accept-Version: 1.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"}}An actual request with the example values:
curl -XPOST 'api.gameofwhales.com:8488/ads' -H 'Accept-Version: 1.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"}}
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. |
|
} ]
|
|||
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
}
]
}