offers
offers method of REST API is used to get information about valid special offers for the user. The method returns the best offer for every product. So the response can't contain the duplicate products.
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/offers
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
|
optional | 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/offers
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/offers' -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. |
offers | required | object | The list of valid special offers for the user. If there are no the offers the empty object will be returned. The data about every offer looks like a pair product:{offerDetails}. The response can't contain the duplicate products. The offer details include the following properties: |
{ | |||
product
|
required | string | The product name. |
{
|
|||
activatedAt
|
required | timestamp | The date when the offer was activated by the user. |
camp
|
required | string | ID of the special offer campaign. |
countFactor
|
required | number | The value influences the number of the product (coins, for example) which the user will get if he makes the purchase by the offer. The count by the offer should be calculated as regularCount*countFactor. This factor is applied only for in-app products. |
createdAt
|
required | timestamp | The date when the offer was created in Game of Whales. |
custom
|
optional | object | The additional data can be used by game developers for working with the offer. The data is returned as a kit of key-value pairs. The value can be string, number or boolean. |
decisionTime
|
required | number | Shows how much time (in hours) the user has for using the offer. The counting is begun from the time of activation (activatedAt property). |
description
|
optional | string | The special offer's description. |
finishedAt
|
required | timestamp | The date when the offer will be finished. |
name
|
required | string | The name of the special offer. |
payload
|
required | string | Encrypted data about the special offer. It can be used to verify the offer on the game server side. |
priceFactor
|
required | number | The value influences the regular price of the product. The price of the offer should be calculated as regularPrice*priceFactor. This factor is applied only for in-game products. |
redeemable
|
required | boolean |
Shows how many purchases the user can make by the offer. true means that the user can use the offer only once. false means that the user can make a lot of purchases. |
rest
|
required | number | How much time (in milliseconds) rests until the finish of the offer. |
}
|
|||
} |
Pay attention that "offers" method doesn't return the data about the experiment in which the user takes part.
An example of a response:
{ "serverTime": 1545648704229, "properties": { "user": "3A15982E-C4CB-0000-0000-D88861BA0C49", "group": "b", "revenue": 2 }, "offers": { "item1": { "camp": "personal_1545649781204", "custom": { "place": "shop", "showForEveryone": true, "additionalNumber": 123 }, "priceFactor": 0.1, "countFactor": 1, "finishedAt": 1545736201925, "redeemable": true, "activatedAt": 1545649801925, "createdAt": 1545649781204, "name": "Personal offer", "decisionTime": 2, "rest": 86400000, "payload": "952d5211b9..." }, "product_10": { "camp": "5c2099fb8b756237132c6e45", "priceFactor": 1, "countFactor": 1.5, "finishedAt": 1545735104212, "redeemable": false, "activatedAt": 1545648704212, "createdAt": 1545640443021, "name": "Black Friday", "description": "Big sale", "decisionTime": 24, "rest": 85302287, "payload": "782d5211b9..." } } }
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/offers
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/offers' -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. |
offers | required | object | The list of valid special offers for the user. If there are no the offers the empty object will be returned. The data about every offer looks like a pair product:{offerDetails}. The response can't contain the duplicate products. The offer details include the following properties: |
{ | |||
product
|
required | string | The product name. |
{
|
|||
activatedAt
|
required | timestamp | The date when the offer was activated by the user. |
camp
|
required | string | ID of the special offer campaign. |
countFactor
|
required | number | The value influences the number of the product (coins, for example) which the user will get if he makes the purchase by the offer. The count by the offer should be calculated as regularCount*countFactor. This factor is applied only for in-app products. |
createdAt
|
required | timestamp | The date when the offer was created in Game of Whales. |
custom
|
optional | object | The additional data can be used by game developers for working with the offer. The data is returned as a kit of key-value pairs. The value can be string, number or boolean. |
decisionTime
|
required | number | Shows how much time (in hours) the user has for using the offer. The counting is begun from the time of activation (activatedAt property). |
description
|
optional | string | The special offer's description. |
finishedAt
|
required | timestamp | The date when the offer will be finished. |
name
|
required | string | The name of the special offer. |
payload
|
required | string | Encrypted data about the special offer. It can be used to verify the offer on the game server side. |
priceFactor
|
required | number | The value influences the regular price of the product. The price of the offer should be calculated as regularPrice*priceFactor. This factor is applied only for in-game products. |
redeemable
|
required | boolean |
Shows how many purchases the user can make by the offer. true means that the user can use the offer only once. false means that the user can make a lot of purchases. |
rest
|
required | number | How much time (in milliseconds) rests until the finish of the offer. |
}
|
|||
} |
An example of a response:
{ "serverTime": 1545648704229, "properties": { "user": "3A15982E-C4CB-0000-0000-D88861BA0C49", "group": "b", "revenue": 2 }, "offers": { "item1": { "camp": "personal_1545649781204", "custom": { "place": "shop", "showForEveryone": true, "additionalNumber": 123 }, "priceFactor": 0.1, "countFactor": 1, "finishedAt": 1545736201925, "redeemable": true, "activatedAt": 1545649801925, "createdAt": 1545649781204, "name": "Personal offer", "decisionTime": 2, "rest": 86400000, "payload": "952d5211b9..." }, "product_10": { "camp": "5c2099fb8b756237132c6e45", "priceFactor": 1, "countFactor": 1.5, "finishedAt": 1545735104212, "redeemable": false, "activatedAt": 1545648704212, "createdAt": 1545640443021, "name": "Black Friday", "description": "Big sale", "decisionTime": 24, "rest": 85302287, "payload": "782d5211b9..." } } }