Bans #
You can restrict a player from logging into your game by issuing a ban on their account. Bans prevent the player from receiving a game authentication token.
Pragma Engine offers the following ban features:
- Ban an account to restrict a player from logging into your game
- View an account’s ban history including previously revoked and currently active bans
- Revoke a ban and remove its effects on the account
Operators can add, view, and revoke bans on an account using the Social Operator Portal. For more details, see the Social Operator Portal page.
Data classes #
There are two main data classes within the Bans feature: BanRecord
and Ban
.
Ban record #
Below is the data included in the BanRecord
object. BanRecord
contains additional data about the ban we expose to only Operators and not to players.
property | description |
---|---|
ban | contains information on the account’s ban |
bannedBy | Usually the Operator ID of the Operator who created the ban. Additional cases would be all 0s when submitted by the system. |
revokedBy | optional Usually the Operator ID of the Operator who revoked the ban. Additional cases would be all 0s when submitted by the system. This is only set if the ban has been revoked. |
comment | optional Additional context for the ban. |
Ban #
Ban
contains information regarding a ban issued on a player’s account.
property | description |
---|---|
banId | the ID of the ban |
pragmaSocialId | the account’s Pragma Social ID |
revoked | boolean that determines whether the ban is active |
gameShardId | optional This is only needed if the banScope is BAN_SCOPE_GAME_SHARD and is the game shard ID that you want to add a ban to. If you’re banning from the game server, this will be the current game shard the player is connected to. |
startTimestampMillis | time in milliseconds for when the ban started |
durationInMillis | optional Defaults to MAX_LONG which makes the ban permanent. This is the time in milliseconds the ban is active. |
banScope | enum that determines whether the ban applies to the current game shard or all game shardsBAN_SCOPE_GAME_SHARD : ban account from current game shardBAN_SCOPE_ALL_GAME_SHARDS : ban account from all game shards |
banReason | enum that describes the reason the account is receiving a banPragma has the EXT_BAN_REASON_UNSPECIFIED enum which can be used for your bans. To add your own custom ban reasons see Extension data. |
Ban an account #
The following Operator, Partner, and Service endpoints are available to ban an account:
AccountRpc.BanAccountOperatorV1Request
AccountRpc.BanAccountPartnerV1Request
AccountRpc.BanAccountServiceV1Request
Send BanAccount
to add a ban to an account:
{
"requestId": 1,
"type": "AccountRpc.BanAccountOperatorV1Request",
"payload": {
"pragmaSocialId": "eb683bf0-5d34-4580-8f78-ab1d787f94b6",
"gameShardId": "00000000-0000-0000-0000-000000000001",
"banScope": "BAN_SCOPE_GAME_SHARD",
"durationInMillis": "3600000",
"banReason": "EXT_BAN_REASON_CUSTOM",
"comment": "Player violated terms of service."
}
}
Below is a sample response:
{
"sequenceNumber": 0,
"response": {
"requestId": 1,
"type": "AccountRpc.BanAccountOperatorV1Response",
"payload": {
"banRecord": {
"ban": {
"banId": "d5cd35b6-c45b-4039-9910-479142a2c28a",
"pragmaSocialId": "eb683bf0-5d34-4580-8f78-ab1d787f94b6",
"revoked": false,
"startTimestampMillis": "1713224627060",
"gameShardId": "00000000-0000-0000-0000-000000000001",
"banScope": "BAN_SCOPE_GAME_SHARD",
"durationInMillis": "3600000",
"banReason": "EXT_BAN_REASON_CUSTOM"
},
"bannedBy": "fc734hf0-5d34-4580-8f78-ab1d787f92h4",
"comment": "Player violated terms of service."
}
}
}
}
Ban an account from all game servers using the SDK:
Server->Session()->BansApi().BanAccountFromGameShard(
SocialId,
AllGameShards,
DurationInMillis,
BanReason,
Comment,
Delegate
);
server.BansApi.BanAccountFromGameShard(
socialId,
allGameShards,
durationInMillis,
banReason,
comment,
completeDelegate
);
You can ban a player from a specific game shard. By default, allGameShards
is set to true
and issuing a ban will restrict a player from all game shards. When you set allGameShards
to false
, this will restrict the player only from the current game shard they’re connected to; the banned account will still receive a gameToken
when authenticating for all other game shards.
Once an account has been issued a ban, the currently connected player will receive a notification. The content of this message can be found in AccountRpc.BanV1Notification
.
Banning a player does not invalidate the player’s currently connected session. We recommend handling this event and removing the player when they receive their ban notification.
The player game client can listen to the ban notification using the SDK:
Player->Session()->BansApi().OnAccountBanned.AddLambda(
[this](const FPragmaBan& Ban) {
// handle ban event
});
player.BansApi.OnAccountBanned += ban =>
{
// handle ban event
};
View an account’s ban history #
The following Operator, Partner, and Service endpoints are available to view an account’s ban history:
AccountRpc.GetBansBySocialIdOperatorV1Request
AccountRpc.GetBansBySocialIdPartnerV1Request
AccountRpc.GetBansBySocialIdServiceV1Request
Retrieve an account’s ban history:
{
"requestId": 1,
"type": "AccountRpc.GetBansBySocialIdPartnerV1Request",
"payload": {
"pragmaSocialId": "eb683bf0-5d34-4580-8f78-ab1d787f94b6"
}
}
pragmaSocialId
: the account’s Pragma Social ID
Below is a sample response:
{
"sequenceNumber": 0,
"response": {
"requestId": 1,
"type": "AccountRpc.GetBansBySocialIdPartnerV1Response",
"payload": {
"banRecords": [
{
"ban": {
"banId": "24437d4e-3129-440b-8687-097e71c58148",
"pragmaSocialId": "eb683bf0-5d34-4580-8f78-ab1d787f94b6",
"revoked": true,
"gameShardId": "00000000-0000-0000-0000-000000000001",
"startTimestampMillis": "1711062051011",
"banScope": "BAN_SCOPE_GAME_SHARD",
"durationInMillis": "10000",
"banReason": "EXT_BAN_REASON_CUSTOM"
},
"bannedBy": "00000000-0000-0000-0000-000000000000",
"revokedBy": "7553608f-90bf-439e-a257-98d46ed8f099",
"comment": ""
},
]
}
}
}
Show a player their account’s ban history:
Player->Session()->BansApi().GetBans(Delegate);
Player.BansApi.GetBans();
The player will retrieve a list of bans.
Revoke a ban #
The following Operator, Partner, and Service endpoints are available to revoke a ban:
AccountRpc.RevokeBanAccountOperatorV1Request
AccountRpc.RevokeBanAccountPartnerV1Request
AccountRpc.RevokeBanAccountServiceV1Request
Send RevokeBanAccount
with a banId
:
{
"requestId": 1,
"type": "AccountRpc.RevokeBanAccountOperatorV1Request",
"payload": {
"banId": "d5cd35b6-c45b-4039-9910-479142a2c28a"
}
}