Desktop Web Subscription Management

In Teak a player’s desktop web subscription status is not connected to their per device opt-in/out state. That is, if a player denies desktop web notifications from the browser specific push notification permission prompt, their subscription status reported by this API will still be opt_in. This API applies across all of a player’s desktop devices and browsers, and the subscription status may be changed even if the player has no desktop devices or browsers.

The subscription status set by this API applies to Facebook Canvas App to User Notifications and Desktop Web push notifications.

The subscription status set by this API applies to both locally scheduled notifications and dashboard managed schedules.

Reading

Endpoint

https://api.gocarrot.com/v2/desktop_push/subscription_status

Request Type

GET

Rate Limiting

300 requests per second

Description: The GET v2/desktop_push/subscription_status endpoint retrieves the current desktop web push subscription status for a game assigned player id.

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 retrieving desktop web push subscription status for. This must match the value provided by the game client’s Teak SDK integration.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'channel', 'user_id', 'state', 'reachable', and 'categories' keys.

status

'ok'

channel

'desktop_push'

user_id

The game assigned player id of the player opt out status was retrieved for.

state

One of 'opt_out' or 'opt_in'.
'opt_out' indicates that the player has opted out of receiving desktop web push notifications through set preferences.
'opt_in' indicates that the player has not opted out of receiving desktop web push notifications.

reachable

true if the player has any registered desktop web push devices or browsers, otherwise false.

categories

A map of Opt Out Category identifiers to one of 'opt_out or 'opt_in'.
'opt_out' indidicates that the player has opted out of receiving desktop web push notifications for that category through set preferences.
'opt_in' indicates that the player has not opted out of receiving esktop web push notifications for that category.

Example

 
{"status":"ok", "channel":"desktop_push", "user_id":"example_user", "state":"opt_in", "reachable": false, "categories": {"sales": "opt_in", "events": "opt_out"}}

Error Responses

Player 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":{"user_id":["No player with 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/desktop_push/subscription_status may only be called 300 times per second. Please wait a second and try again"]}}

Updating

Endpoint

https://api.gocarrot.com/v2/desktop_push/subscription_status

Request Type

POST

Content-Type

application/json or application/x-www-form-urlencoded

Rate Limiting

300 requests per second

Description: The POST v2/desktop_push/subscription_status endpoint updates the desktop web push subscription status for a given player.

The state will apply to all of a player’s desktop devices and browsers. However please be aware that if the user has chosen to opt out of desktop web notifications in their browser settings or by denying notifications from the browser specific push notification permission prompt, this API cannot be used to cause a player to receive desktop web notifications on that device or browser.

It is not necessary for the player to have any desktop devices to make this call.

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 desktop web push subscription status for. This must match the value provided by the game client’s Teak SDK integration.

state

One of 'opt_out' or 'opt_in'

opt_out

Desktop web notifications should be sent to this player.

opt_in

Desktop web notifications may be sent to this player.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'channel', 'user_id', 'previous_state', 'state', 'reachable', and categories keys.

status

'ok'

channel

'desktop_push'

user_id

The game assigned player id of the player opt out status was retrieved for.

previous_state

The previously set desktop web notification subscription state for this player.

state

One of 'opt_out' or 'opt_in'.
'opt_out' indicates that the player has opted out of receiving desktop web push notifications through set preferences.
'opt_in' indicates that the player has not opted out of receiving desktop web push notifications.

reachable

true if the player has any registered desktop web push devices or browsers, otherwise false.

categories

A map of Opt Out Category identifiers to one of 'opt_out or 'opt_in'.
'opt_out' indidicates that the player has opted out of receiving desktop web push notifications for that category through set preferences.
'opt_in' indicates that the player has not opted out of receiving esktop web push notifications for that category.

Example

 
{"status":"ok", "channel":"desktop_push", "user_id":"example_user", "previous_state": "opt_out", state":"opt_in", "reachable": false, "categories": {"sales": "opt_in", "events": "opt_out"}}

Error Responses

Unknown State

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 parameters were invalid, with values being an array of human readable error messages..

Example

 
{"status":"error","errors":{"state":["Unknown state opted_in"]}}

Player 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":{"user_id":["No player with 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/desktop_push/subscription_status may only be called 300 times per second. Please wait a second and try again"]}}

Category Update

Endpoint

https://api.gocarrot.com/v2/desktop_push/subscription_status/:category_identifier

Request Type

POST

Content-Type

application/json or application/x-www-form-urlencoded

Rate Limiting

300 requests per second

Description: The POST v2/desktop_push/subscription_status/:category_identifier endpoint updates the desktop web push subscription status for a given player and Opt Out Category.

The state will apply to all of a player’s desktop devices and browsers. However please be aware that if the user has chosen to opt out of desktop web notifications in their browser settings or by denying notifications from the browser specific push notification permission prompt, this API cannot be used to cause a player to receive desktop web notifications on that device or browser.

It is not necessary for the player to have any desktop devices to make this call.

Required Parameters

category_identifier

Note that this is a path parameter. The identifier of the opt out category the player’s desktop web push subscription status is being updated for.

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 desktop web push subscription status for. This must match the value provided by the game client’s Teak SDK integration.

state

One of 'opt_out' or 'opt_in'

opt_out

Mobile notifications should be sent to this player.

opt_in

Mobile notifications may be sent to this player.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'channel', 'user_id', 'previous_state', 'state', 'reachable', and 'category' keys.

status

'ok'

channel

'push'

user_id

The game assigned player id of the player opt out status was retrieved for.

previous_state

The previously set desktop web notification subscription state for this player and Opt Out Category.

state

One of 'opt_out' or 'opt_in'.
'opt_out' indicates that the player has opted out of receiving desktop web push notifications through set preferences for this Opt Out Category.
'opt_in' indicates that the player has not opted out of receiving desktop web push notifications for this Opt Out Category.

reachable

true if the player has any registered desktop web push devices or browsers, otherwise false.

category

The identifier of the Opt Out Category that the desktop web push subscription status was updated for.

Example

 
{"status":"ok", "channel":"desktop_push", "user_id":"example_user", "previous_state": "opt_out", state":"opt_in", "reachable": false, "category": "sales"}

Error Responses

Unknown State

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 parameters were invalid, with values being an array of human readable error messages..

Example

 
{"status":"error","errors":{"state":["Unknown state opted_in"]}}

Player 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":{"user_id":["No player with 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/desktop_push/subscription_status/:category_identifier may only be called 300 times per second. Please wait a second and try again"]}}