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.

Important Note: The Traffic Inspector and "Try It" tools on this page do not work correctly at the moment. You can use your favorite other HTTP client and our main API path if you wish to try things out.

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

Apps

Create, Update, and view details of GameThrive Apps

A GameThrive app represents a single iOS version and a single Android version of your mobile app. It can be configured with both a single Apple Push Notification Service certificate, and a single Google Cloud Messaging push token.

GameThrive apps can be created and modified from the GameThrive web dashboard. This API is made available for your convenience in the event that you wish to automate the process outside of the dashboard.

In order to call any of the "Apps" related API methods, you must supply your GameThrive user token. This token is visible on the following page when you're logged in: https://gamethrive.com/user/edit

Required Header Parameters:

name type example notes
Authorization: Basic string NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj Your "API User Secret Key" on the GameThrive User Settings page (https://gamethrive.com/user/edit). For some HTTP libraries, use this value as the username field. Data in the password field will be ignored.

Apps Collection

View Your Apps

GET

/api/v1/apps

Lists all of the GameThrive apps on your GameThrive account

Response

200 (OK)
Content-Type: application/json
[{name: "Your app 1", players: 21048, messagable_players: 18225, updated_at: "2014-04-01T04:20:02.003Z", created_at: "2014-04-01T04:20:02.003Z", gcm_key: "a gcm push key", apns_env: "sandbox", id: "e4e87830-b954-11e3-811d-f3b376925f15", apns_certificates: "Your apns certificate"},{name: "Your app 2", players: 10, messagable_players: 8, updated_at: "2014-04-01T04:20:03.003Z", created_at: "2014-04-01T04:20:03.003Z", gcm_key: "a gcm push key", apns_env: "sandbox", id: "e4e87830-b954-11e3-811d-f3b376925f16", apns_certificates: "Your apns certificate"}]

Create a new app

POST

/api/v1/apps

Required Body Parameters:

name type example notes
name string My game name

Other/Optional Body Paramters

(All or none of the attributes starting with "apns" should be included)

name type example notes
apns_env string sandbox Either "sandbox" or "production"
apns_p12 string MIIL0QIBAzCCC5cGCSqGSIb3DQEHAaCCC4gEgguEMIIL... Your apple push notification p12 certificate file, converted to a string and Base64 encoded.
apns_p12_password string FooBar Passwword for the p12 file
gcm_key string AIzaSyCSRBd9Oxuz4t-PZJL7wNMQQ0ZcqNyExqQ Your Google Push messaging auth key

Response

200 (OK)
Content-Type: application/json
{name: "Your app 1",
players: 0,
messagable_players: 0,
updated_at: "2014-04-01T04:20:02.003Z",
created_at: "2014-04-01T04:20:02.003Z",
gcm_key: "a gcm push key",
apns_env: "sandbox",
id: "e4e87830-b954-11e3-811d-f3b376925f15",
apns_certificates: "Your apns certificate"}     

App

View an app

GET

/api/v1/apps/{app-id}

Displays the details of a single app on your GameThrive account

Response

200 (OK)
Content-Type: application/json
{name: "Your app 1", players: 21048, messagable_players: 18225, updated_at: "2014-04-01T04:20:02.003Z", created_at: "2014-04-01T04:20:02.003Z", gcm_key: "a gcm push key", apns_env: "sandbox", id: "e4e87830-b954-11e3-811d-f3b376925f15", apns_certificates: "Your apns certificate"}

Update an app

PUT

/api/v1/apps/{app-id}

Optional Body Paramters

(All or none of the attributes starting with "apns" should be included)

name type example notes
apns_env string sandbox Either "sandbox" or "production"
apns_p12 string MIIL0QIBAzCCC5cGCSqGSIb3DQEHAaCCC4gEgguEMIIL... Your apple push notification p12 certificate file, converted to a string and Base64 encoded.
apns_p12_password string FooBar Passwword for the p12 file
gcm_key string AIzaSyCSRBd9Oxuz4t-PZJL7wNMQQ0ZcqNyExqQ Your Google Push messaging auth key

Response

200 (OK)
Content-Type: application/json
{name: "Your app 1",
players: 155,
messagable_players: 138,
updated_at: "2014-04-01T04:20:02.003Z",
created_at: "2014-04-01T04:20:02.003Z",
gcm_key: "a gcm push key",
apns_env: "sandbox",
id: "e4e87830-b954-11e3-811d-f3b376925f15",
apns_certificates: "Your apns certificate"}  

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, 3 = Windows Phone
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 Android = Advertising Id, iOS = identifierForVendor, WP8.0 = DeviceUniqueId, and WP8.1 = AdvertisingId

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 Android = Advertising Id, iOS = identifierForVendor, WP8.0 = DeviceUniqueId, and WP8.1 = AdvertisingId
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

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
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 Android = Advertising Id, iOS = identifierForVendor, WP8.0 = DeviceUniqueId, and WP8.1 = AdvertisingId

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

View Notification Details

View the details of a notification that has been queued or delivered

GET

/api/v1/notifications/{notificationId}?app_id={appId}

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.

Response

200 (OK)
Content-Type: application/json
{"id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"successful": 21,
"failed": 3,
"converted": 6,
"remaining": 0}

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 to a single GameThrive app

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, at least one device type must be true.
isAndroid boolean true Send notification to Android players. Defaults to false, at least one device type must be true.
isWP boolean true Send notification to Windows Phone 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 these registration ids do not correspond to players in our system, players will be automatically created. NOTE: Can NOT use with segements but does not require your "API Auth Key".
include_wp_uris Array of Strings ["http://s.notify.live.net/u/1/bn1/HmQAAACPaLDr-..."] Specific Windows Phone channel URI to send the notification to. If these channel URIs do not correspond to players in our system, players will be automatically created. 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 Sound file that is included in your app to play instead of the default device notification sound. NOTE: Leave off file extension for Android.
wp_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.
buttons Array of Hashes [{"id": "id1", "text": "button1"}, {"id": "id2", "text": "button2"}] Buttons to add to the notification. Supported by iOS 8.0 and Android 4.1+ devices.
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.
delayed_option string last-active Possible values are "" (blank string), "timezone" (Deliver at the same time-of-day as send_after, but in each users own timezone), and "last-active" (**Recommended** deliver at the same time of day as each user last used your app)

Response

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

Create and deliver a new a Notification to multiple GameThrive Apps

POST

/api/v1/notifications

This API method is used in case you have multiple apps that you wish to deliver a notificaiton to and where you don't want the notificaiton to be sent multiple times to a user that has 2 or more of your apps installed. De-duplication is handled automatically by GameThrive. Targetting parameters are not yet supported for this use case -- the notification will be delivered to all users on the chosen platforms.

Required Header Parameters:

name type example notes
Authorization: Basic string NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj Your "API User Secret Key" on the GameThrive User Settings page (https://gamethrive.com/user/edit). For some HTTP libraries, use this value as the username field. Data in the password field will be ignored. Note: This is different than your APP Api Auth Key, which only applies to a single app.

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

name type example notes
app_ids array of string ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"] A list of GameThrive Application Keys. They must all be under the same GameThrive account.
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.
isWP boolean true Send notification to Windows Phone 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.

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 Sound file that is included in your app to play instead of the default device notification sound. NOTE: Leave off file extension for Android.
wp_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.
buttons Array of Hashes [{"id": "id1", "text": "button1"}, {"id": "id2", "text": "button2"}] Buttons to add to the notification. Supported by iOS 8.0 and Android 4.1+ devices.
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
{"success": "true"
 "recipients": 3189945}