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:

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.

propertydescription
banContains information on the account’s ban.
bannedByUsually the Operator ID of the Operator who created the ban. Additional cases would be all 0s when submitted by the system.
revokedByoptional

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.
commentoptional

Additional context for the ban.

Ban #

Ban contains information regarding a ban issued on a player’s account.

propertydescription
banIdThe ID of the ban.
pragmaSocialIdThe account’s Pragma Social ID.
revokedBoolean that determines whether the ban is active.
gameShardIdoptional

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.
startTimestampMillisTime in milliseconds for when the ban started.
durationInMillisoptional

Defaults to MAX_LONG which makes the ban permanent. This is the time in milliseconds the ban is active.
banScopeenum that determines whether the ban applies to the current game shard or all game shards.

BAN_SCOPE_GAME_SHARD: Ban account from current game shard.
BAN_SCOPE_ALL_GAME_SHARDS: Ban account from all game shards.
BAN_SCOPE_FULL_ACCOUNT: Ban account from both social and all game shards.
banReasonenum that describes the reason the account is receiving a ban

Pragma 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,
  comment,
  banReason,
  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.

You can also ban a player from all social and game shards using the SDK:

Server->Session()->BansApi().BanAccount(
  SocialId, 
  DurationInMillis, 
  BanReason,
  Comment,
  Delegate
);
server.BansApi.BanAccount(
  socialId, 
  durationInMillis,
  comment,
  banReason,
  completeDelegate
);

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.

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
};

Remove a player from their active social session #

The BAN_SCOPE_FULL_ACCOUNT can automatically remove a player from their active social session. To disable this behavior follow this config:

social:
  serviceConfigs:
    AccountServiceConfig:
      blockSessionOnBan: false

Banning a player from a game shard does not invalidate the player’s currently connected game session. We recommend handling the OnAccountBanned event and removing the player when they receive their ban notification.

In the event you need to remove players from their currently connected game session, see Remove and block players from their active session for more details.

Show a player their ban duration and reason #

When a player with active bans attempts to authenticate, the authenticateorcreate endpoint will respond with an AccountApplicationError which contains a list of associated active bans. You can use the list of associated active bans to customize what ban information (duration, reason) is shown to the player.

The Player Social Portal will display an Account Banned error page for banned players attempting to log in. This error page is a customizable swappable component under Account.Bans.AccountBannedDisplay. See Swappable Components for more details.

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",
        "includeExpiredBans": false,
        "includeRevokedBans": false
    }
}
  • pragmaSocialId: the account’s Pragma Social ID
  • includeExpiredBans: Boolean that determines whether to include expired bans when retrieving an account’s ban history. Default value is false.
  • includeRevokedBans: Boolean that determines whether to include revoked bans when retrieving an account’s ban history. Default value is false.

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