Table of Contents

    API

    Mock Server

    Use this URL to access a mockup of the API server. Your traffic will be recorded and compared to the documentation. You'll find your traffic analysis in the inspector or directly here in the documentation, right next to each resource.

GameThrive

GameThrive is a free cross-platform push notification delivery service. To use it, you must first sign up at https://gamethrive.com and create a new application.

Our API serves two purposes:

  1. Programatically delivering notifications from your server or from one mobile device to another.
  2. Adding, updating, of fetching data for players of your game. This is normally taken care of by our SDKs, but we make these methods available in the event that you find them useful.

Need help? Visit https://gamethrive.com or contact us at support@gamethrive.com.

Players

Create, Update, and view details of Players

A GameThrive app can have many players, each of which corresponds to a unique user that has installed and run your application.

A player has the following attributes:

  • app_id
  • id
  • device_type
  • identifier
  • language
  • session_count
  • last_active
  • device_os
  • timezone
  • ad_id
  • badge_count
  • game_version
  • created_at
  • amount_spent
  • tags
  • playtime
  • invalid_identifier
  • badge_count

The id and created_at values are assigned by the GameThrive API when a player is created. app_id is available on the GameThrive website after creating a new app. invalid_identifier is set to true if the user does not have an identifier, or if they failed to receive a push notification (usually because they uninstalled the app).

Players Collection

Create a Player

POST

/api/v1/players

Create a new player.

Note: If you pass in an identifier of a player that already exists, the existing player will be updated instead of a new one being created.

Required Body Parameters:

name type example notes
device_type integer 0 0 = iOS, 1 = Android, 2 = Amazon
app_id string "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" Your GameThrive Application Key

Recommended Body Parameters

name type example notes
identifier string ce777617da7f548fe7a9ab6febb56 Push notification identifier from Google or Apple. For Apple push identifiers, you must strip all non alphanumeric characters.
language string zh-Hans Language code. Typically lower case two letters, except for chinese where it must be one of "zh-Hans" or "zh-Hant"
timezone integer -28800 number of seconds away from GMT
device_model string iPhone5,1 device make and model
device_os string 7.0.4 device operating system version
game_version string 1.0.5 version of the game
ad_id string 96bd03b6-defc-4203-83d3-dc1c730801f7 Advertising id for Android devices and identifierForVendor for iOS devices

Other/Optional Body Paramters

(Typically you wouldn't send these unless importing players from another database)

name type example notes
session_count integer 5 Number of times the player has played the game, defaults to 1
tags key/value pairs {"foo":"bar","this":"that"} Custom tags for the player
amount_spent float 5.30 Amount the player has spent in USD, up to two decimal places
created_at integer 1395096859 Unixtime when the player joined the game
last_active integer 1395096859 Unixtime when the player was last active
playtime integer 60 Seconds player was running your app.
badge_count integer 1 Current iOS badge count displayed on the app icon.

Response

200 (OK)
Content-Type: application/json
{"success": true, "id": "ffffb794-ba37-11e3-8077-031d62f86ebf" }

Player

Get details of a single player

GET

/api/v1/players/{playerId}

Required URL Parameters

Subsitute {player-id} with the identifier of the player. Obtained when creating the player.

Response

200 (OK)
Content-Type: application/json
{"identifier":"ce777617da7f548fe7a9ab6febb56cf39fba6d382000c0395666288d961ee566",
"session_count":1,
"language":"en",
"timezone":-28800,
"game_version":"1.0",
"device_os":"7.0.4",
"device_type":0,
"device_model":"iPhone",
"ad_id":null,
"tags":{"a":"1","foo":"bar"},
"last_active":1395096859,
"amount_spent":"0",
"created_at":1395096859,
"invalid_identifier":false,
"badge_count": 0}

Update a single Player

PUT

/api/v1/players/{playerId}

All of the player's attributes can be updated with the exception of app_id and id.

On iOS, this should be called any time the badge count is changed by your app to update our server side tracking of the player's badge number. Note, we also set badge_count to 0 when you call on_session.

Note: Updating tags will append to the player's existing tags. To remove an existing tag, update the tag with a value of a blank string.

Required URL Parameters

Subsitute {player-id} with the identifier of the player. Obtained when creating the player.

Required Body Parameters

None

Optional Body Parameters

name type example notes
identifier string ce777617da7f548fe7a9ab6febb56 Push notification identifier from Google or Apple. For Apple push identifiers, you must strip all non alphanumeric characters.
language string zh-Hans Language code. Typically lower case two letters, except for chinese where it must be one of "zh-Hans" or "zh-Hant"
timezone integer -28800 number of seconds away from GMT
device_model string iPhone5,1 device make and model
device_os string 7.0.4 device operating system version
game_version string 1.0.5 version of the game
ad_id string 96bd03b6-defc-4203-83d3-dc1c730801f7 Advertising id for android users, and identifierForVendor for iOS users
session_count integer 5 Number of times the player has played the game
tags key/value pairs {"foo":"bar","this":"that"} Custom tags for the player
amount_spent float 5.30 Amount the player has spent in USD, up to two decimal places
created_at integer 1395096859 Unixtime when the player joined the game
last_active integer 1395096859 Unixtime when the player was last active
badge_count integer 1 Current iOS badge count displayed on the app icon.

Response

200 (OK)
Content-Type: application/json
{"success": true }

Player's amount spent

Increment player's total amount spent

POST

/api/v1/players/{playerId}/on_purchase

Required URL Parameters

Subsitute {player-id} with the identifier of the player. Obtained when creating the player.

Required Body Parameters. Must be in the form of a JSON key/value hash.:

name type example notes
amount number 3.99 The amount value in USD the player just spent.

Response

200 (OK)
Content-Type: application/json
{"success": true }

New player session

Should be called each time the player runs the app.

POST

/api/v1/players/{playerId}/on_session

Required URL Parameters

Subsitute {player-id} with the identifier of the player. Obtained when creating the player.

Required Body Parameters. Must be in the form of a JSON key/value hash.:

None

Optional Body Parameters

name type example notes
identifier string ce777617da7f548fe7a9ab6febb56 Push notification identifier from Google or Apple. For Apple push identifiers, you must strip all non alphanumeric characters.
language string zh-Hans Language code. Typically lower case two letters, except for chinese where it must be one of "zh-Hans" or "zh-Hant"
timezone integer -28800 number of seconds away from GMT
game_version string 1.0.5 version of the game
device_model string iPhone5,1 device make and model
device_os string 7.0.4 device operating system version
ad_id string 96bd03b6-defc-4203-83d3-dc1c730801f7 Advertising id for Android users and identifierForVendor for iOS users

Response

200 (OK)
Content-Type: application/json
{"success": true }

Player's playtime

Increment the player's total playtime

POST

/api/v1/players/{playerId}/on_focus

We recommend calling this every 60 seconds, but do not call it more frequently than that.

Required URL Parameters

Subsitute {player-id} with the identifier of the player. Obtained when creating the player.

Required Body Parameters. Must be in the form of a JSON key/value hash.:

name type example notes
state string "ping" Required to indicate we are incrementing
active_time integer 60 Number of seconds player was running your app.

Response

200 (OK)
Content-Type: application/json
{"success": true }

Notifications

Notification

Track that a push notification was opened

PUT

/api/v1/notifications/{notificationId}

Required URL Parameters

Subsitute {notification-id} with the identifier of the notification. This is passed along as additional data in the notification delivered to the device by GameThrive.

Required Body Parameters. Must be in the form of a JSON key/value hash.:

name type example notes
opened boolean true Required to indicate the notification was openned.
app_id string "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" Your GameThrive Application Key

Response

200 (OK)
Content-Type: application/json
{"success": true }

Notification

Create and deliver a new a Notification

POST

/api/v1/notifications

Create a new notification.

Required Header Parameters:

name type example notes
Authorization: Basic string NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj Your "API Auth Key" on the GameThrive Application Settings page. For some HTTP libraries, use this value as the username field. Data in the password field will be ignored. NOTE: Only required when using segments

Required Body Parameters. Must be in the form of a JSON key/value hash:

name type example notes
app_id string "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" Your GameThrive Application Key
isIos boolean true Send notification to iOS players. Defaults to false, one device type must be true.
isAndroid boolean true Send notification to Android players. Defaults to false, one device type must be true.
contents Hash {"en": "English Message"} Message contents to send to players, "en" (English) is required. The key of each hash is either a a 2 character language code or one of zh-Hans/zh-Hant for Simplified or Traditional Chinese. The value of each key is the message that will be sent to users for that language. If do not specify a langauge English will be used.

Target Parameters. These are used to specify who the notification will be sent to. Must be in the form of a JSON key/value hash:

name type example notes
included_segments Array of Strings ["Free Players", "New Players"] Names of segments to send the message to. Any player in any of these segements will be sent this notification. Note: Your API Auth Key is required to use segments. Do not include this field if you use include_player_ids.
excluded_segments Array of Strings ["Free Players", "New Players"] Names of segments to exclude players from. Any players in any of these segments will not be sent the notification even if they are a member of included_segments. Note: Your "API Auth Key" is required to use segments. Do not include this field if you use include_player_ids.
include_player_ids Array of Strings ["1dd608f2-c6a1-11e3-851d-000c2940e62c"] Specific players to send your notification to. Do not include this field if you send included_segments. NOTE: Can NOT use with segements but does not require your "API Auth Key".
include_ios_tokens Array of Strings ["ce777617da7f548fe7a9ab6febb56cf39fba6d38203..."] Specific iOS device tokens to send the notification to (all non-alphanumeric characters must be removed from the tokens) . If any of these tokens do not correspond to players in our system, a player will be automatically created for each of them. NOTE: Can NOT use with segements but does not require your "API Auth Key".
include_android_reg_ids Array of Strings ["APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_..."] Specific Android registration ids to send the notification to. If any of these registration ids do not correspond to players in our system, a player will be automatically created for each of them. NOTE: Can NOT use with segements but does not require your "API Auth Key".

Optional Body Paramters. Must be in the form of a JSON key/value hash.

name type example notes
ios_badgeType string SetTo Options are: None, SetTo, or Increase. None leaves the count unaffected on the device. If you use Increase, it will be based on the current value of the player's badge_count.
ios_badgeCount integer 1 Sets or increases the badge icon on the device depending on the ios_badgeType value
ios_sound string notification.wav Sound file that is included in your app to play instead of the default device notification sound.
android_sound string notification.wav Sound file that is included in your app to play instead of the default device notification sound.
data Object Hash {"abc":"123","foo":"bar"} Custom key value pair hash that you can programmatically read in your app's code.
url string http://google.com When the player opens the notification their web browser will open this url.
send_after datetime Fri May 02 2014 00:00:00 GMT-0700 (PDT) Schedule notification for future delivery.
send_at_user_active_time boolean true Sends your notification at the time of day the user last opened your app.

Response

200 (OK)
Content-Type: application/json
{"id": "458dcec4-cf53-11e3-add2-000c2940e62c"
 "recipients": 4}