Opt Out Category Management
An Opt Out Category is a grouping of Messages that players may independently opt out of receiving. For example, a player could choose to opt out of receiving messaging regarding sales, but continue to receive messaging regarding events, if the game has separate Opt Out Categories for sales and events.
Opt Out Categories are shared across all messaging channels, but player preferences are managed for each channel. For example, if you create a Sale Opt Out Category, then players may opt out of receiving Sale messaging on push, desktop web push, and email separately.
Opt Out Categories are additionally mapped on a 1 to 1 basis to Android Notification Channels. On Android, players may use the native settings application to manage their notification preferences, in addition to any in-game preference management you provide.
Please note that on Android any configured sound or badge display state cannot be modified once the corresponding Android Notification Channel has been created on a device. While you may update those settings for an Opt Out Category, they will not take effect on existing installs until the player uninstalls and reinstalls the application.
Listing
Endpoint |
|
Request Type |
GET |
Rate Limiting |
5 requests per second |
Description: The GET v2/opt_out_categories
endpoint retreives all Opt Out Categories for the game.
Success Response
Status Code |
200 |
||||
Response Body |
JSON dictionary with 'status' and 'opt_out_categories' keys.
|
||||
Example |
|
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 |
|
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 |
|
Reading
Endpoint |
|
Request Type |
GET |
Rate Limiting |
5 requests per second |
Description: The GET v2/opt_out_categories/:identifier
endpoint retrieves the current configuration for the Opt Out Category with the identifier identifier
in the request path.
Success Response
Status Code |
200 |
||||
Response Body |
JSON dictionary with 'status' and 'opt_out_category' keys.
|
||||
Example |
|
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 |
|
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 |
|
Creating
Endpoint |
|
Request Type |
POST |
Rate Limiting |
5 requests per second |
Description: The POST v2/opt_out_categories
endpoint creates a new Opt Out Category.
Required Parameters
game_id |
Your Teak App ID |
secret_key |
Your Teak Server Secret |
identifier |
The identifier to use for the Opt Out Category in all subsequent API calls. Must be shorter than 32 charaters. Must be unique. May not be changed. May not start with 'teak'. May not be 'default' or 'miscellaneous'. |
name |
The player visible name of the Opt Out Category. Must be shorter than 32 characters. |
Optional Parameters
description |
The player visible description of the Opt Out Category. |
ios_sound_file |
The default sound that should be played on iOS devices when a push notififcation with this Opt Out Category is received. This may be overridden on a per notification basis. |
android_sound_file |
The sound that should be played on Android devices when a push notification with this Opt Out Category is received. This may not be changed. |
android_show_badge |
A boolean indicating if a badge should be shown when a push notification with this Opt Out Category is received on an Android device. This may not be changed after the game is installed. |
ios_show_badge |
A boolean indicating if a badge should be shown by default when a push notification with this Opt Out Category is received on an iOS device. This may be overridden on a per notification basis. |
archived |
A boolean indicating if this Opt Out Category is archived. Archived categories will not be displayed when setting up new Messages, will not be shown on the Email opt out page, will not be created as Android Notification Channels for new installs, and will not be provided to the game client. |
Success Response
Status Code |
200 |
||||||
Response Body |
JSON dictionary with 'status', 'action', 'exclusion', 'purged_channels', and 'previous_expire_at' keys.
|
||||||
Example |
|
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 |
|
Invalid Parameter
Status Code |
422 |
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 |
|
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 |
|
Updating
Endpoint |
|
Request Type |
PUT |
Rate Limiting |
5 requests per second |
Description: The PUT v2/opt_out_categories/:identifier
endpoint updates settings for the Opt Out Category with the identifier identifier
in the request path.
Optional Parameters
name |
The player visible name of the Opt Out Category. Must be shorter than 32 characters. |
description |
The player visible description of the Opt Out Category. |
ios_sound_file |
The default sound that should be played on iOS devices when a push notififcation with this Opt Out Category is received. This may be overridden on a per notification basis. |
android_sound_file |
The sound that should be played on Android devices when a push notification with this Opt Out Category is received. This may not be changed. |
android_show_badge |
A boolean indicating if a badge should be shown when a push notification with this Opt Out Category is received on an Android device. This may not be changed after the game is installed. |
ios_show_badge |
A boolean indicating if a badge should be shown by default when a push notification with this Opt Out Category is received on an iOS device. This may be overridden on a per notification basis. |
archived |
A boolean indicating if this Opt Out Category is archived. Archived categories will not be displayed when setting up new Messages, will not be shown on the Email opt out page, will not be created as Android Notification Channels for new installs, and will not be provided to the game client. |
Success Response
Status Code |
200 |
||||||
Response Body |
JSON dictionary with 'status', 'action', 'exclusion', 'purged_channels', and 'previous_expire_at' keys.
|
||||||
Example |
|
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 |
|
Invalid Parameter
Status Code |
422 |
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 |
|
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 |
|