Player Properties

Player Properties are strings or numbers associated with each player of your game in Teak. Player Properties have several uses, including

  • Targeting players for a send by using the player properties Audience rule

  • Personalizing push notification content using custom tags

  • Personalizing email content using custom tags

  • Personalizing deep links from Links, push notifications, and emails to take players to a meaningful location in your game

Player Properties must be configured on the Teak dashboard before they can be updated or used. Additionally, the property must permit server updates before you can set it using this API. If you attempt to set a property that is not configured in the dashboard or does not permit server updates, this endpoint will indicate that it is an unknown property but will process updates for all known properties in the same request.

Please note that

  • Number Player Properties can store values between -999999999999999999999999999.999999999 and 999999999999999999999999999.999999999.

  • String Player Properties can store up to 16,384 unicode characters (including emoji)

Updating

Endpoint

https://api.gocarrot.com/v2/player_properties

Request Type

POST

Rate Limiting

1000 requests per second

Required Parameters

Name Description

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

user_id

The Game Assigned Player ID of the player you are updating player properties for. This must match the value provided by the game client’s Teak SDK integration.

properties

A map of player property names to the values of those properties for the given player.

Alternate Parameters

Instead of providing the user_id parameter, which is the Game Assigned Player ID, you can provide teak_internal_user_id with Teak’s internal user id for the player. This ID is exposed in certain Data Sync configurations. If both user_id and teak_internal_user_id are provided, this endpoint will ignore the user_id parameter.

Success Response

Status Code

200

Response Body

JSON dictionary.

status

'ok'

new_properties

A map of player property names to the new values of those properties set by this call.

old_properties

A map of player property names to the previous values of those properties before being updated by this call.

unknown_properties

An array of keys from the properties parameter which are not configured for the game or cannot be updated through the server API.

Example

 
{
  "status":"ok",
  "new_properties": {
    "bankroll": 123456.0,
    "last_screen": "Lobby"
  },
  "old_properties": {
    "bankroll": 100000.0,
    "last_screen": "Bonus Collect"
  },
  "unknown_properties": ["XP"]
}
Number Player Property values in new_properties and old_properties are always returned as decimals (e.g. a stored 50000 is returned as 50000.0), regardless of the format submitted.

Error Responses

Not Found

Status Code

404

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary containing keys indicating which resources were not found, with values being an array of human readable error messages.
Example
{"status":"error","errors":{"game_id":["Unknown app id foo"]}}

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'
Example
{"status":"rate_limit","errors":{"rate_limit":["/v2/player_properties may only be called 1000 times per second. Please wait a second and try again"]}}

Batch Updating

Endpoint

https://api.gocarrot.com/v2/player_properties/batch

Request Type

POST

Rate Limiting

100 requests per second

Batch Size

Up to 100 players per request

Use this endpoint to update player properties for multiple players in a single request. This is more efficient than making individual requests when you need to update many players at once.

Required Parameters

Name Description

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

players

An array of player objects, each containing a player identifier and properties to update. Maximum of 100 players per request.

Player Object Structure

Name Description

user_id

The Game Assigned Player ID of the player you are updating. Alternatively, use teak_internal_user_id.

teak_internal_user_id

Teak’s internal user id (alternative to user_id). If both are provided, teak_internal_user_id takes precedence.

properties

A map of player property names to values for this player.

Example Request

{
  "game_id": "your_teak_app_id",
  "secret_key": "your_server_secret",
  "players": [
    {
      "user_id": "player_123",
      "properties": {
        "bankroll": 50000,
        "last_screen": "Lobby"
      }
    },
    {
      "user_id": "player_456",
      "properties": {
        "bankroll": 75000
      }
    }
  ]
}

Processing Order

Player objects in players are applied in array order. If the same player is identified more than once in a request - by repeating user_id, by mixing user_id and teak_internal_user_id for the same player, or by any other means - the properties they share are last-write-wins: whichever entry appears later in the array determines the value that lands in the database for that property. Each entry’s new_properties in the response reflects the value that actually landed, not necessarily the value that entry itself submitted. old_properties always reflects the value before any entry in the request was applied, for every entry.

Success Response

Status Code

200

Response Body

JSON dictionary.

status

'ok'

results

An array of result objects, one for each player in the request. Each result contains status, player identifier, and either property changes or errors.

summary

A summary object with total_players, successful_updates, and failed_updates counts.

Example

 
{
  "status": "ok",
  "results": [
    {
      "status": "ok",
      "user_id": "player_123",
      "new_properties": {"bankroll": 50000.0},
      "old_properties": {"bankroll": 40000.0},
      "unknown_properties": []
    },
    {
      "status": "error",
      "user_id": "unknown_player",
      "errors": {"user_id": ["could not be found"]}
    }
  ],
  "summary": {
    "total_players": 2,
    "successful_updates": 1,
    "failed_updates": 1
  }
}
Individual player failures do not prevent other players in the batch from being processed. Check the results array to determine which players were updated successfully.
If the same player appears in more than one entry, see Processing Order above for how conflicting property values are resolved.

Error Responses

Bad Request

Status Code

400

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will contain validation errors for the request.
Example
{"status":"error","errors":{"players":["must be a non-empty array"]}}

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'
Example
{"status":"rate_limit","errors":{"rate_limit":["/v2/player_properties/batch may only be called 100 times per second. Please wait a second and try again"]}}