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

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,
    "last_screen": "Lobby"
  },
  "old_properties": {
    "bankroll": 100000,
    "last_screen": "Bonus Collect"
  },
  "unknown_properties": ["XP"]
}

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"]}}