GearN Server | Rest Api references | Game Player

Overview

Update or create key-value custom data entries for a player.

Client

Require permission rules gamePlayer.setCustomData.selfEnable. See PermissionRules

HTTP

POST /api/rJson/gamePlayer/client/setCustomData

Request Headers

Name	Required	Description
Auth-Token	true	A token used to authenticate the user. It is issued after successful login from the client type authenticate (e.g., loginByAccount, loginWithCustomId, etc.) or when an admin logs in via the GearN Dashboard. This token identifies the request sender and determines their access level.
Secret-Key	true	The SecretKey in SecretInfo with role must is Player.
Game-Id		Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting.
Content-Type	true	application/json

Request Body

Code	Type	Required	Description
userId	string		Unique identifier of the player who is the subject of the request. (10 characters)
customDatas	CustomDataParam[]	true	CustomDatas parameter. (1 - 32 elements) See CustomDataParam

Server

Require permission rules gamePlayer.setCustomData.serverSelfEnable. See PermissionRules

HTTP

POST /api/rJson/gamePlayer/server/setCustomData

Request Headers

Name	Required	Description
Secret-Key	true	The SecretKey in SecretInfo with role must is Server.
Game-Id		Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting.
Content-Type	true	application/json

Request Body

Code	Type	Required	Description
userId	string	true	Unique identifier of the player who is the subject of the request. (10 characters)
customDatas	CustomDataParam[]	true	CustomDatas parameter. (1 - 32 elements) See CustomDataParam

Admin

Require permission rules gamePlayer.setCustomData.adminSelfEnable. See PermissionRules

HTTP

POST /api/rJson/gamePlayer/admin/setCustomData

Request Headers

Name	Required	Description
Secret-Key	true	The SecretKey in SecretInfo with role must is Admin.
Game-Id		Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting.
Content-Type	true	application/json

Request Body

Code	Type	Required	Description
userId	string	true	Unique identifier of the player who is the subject of the request. (10 characters)
customDatas	CustomDataParam[]	true	CustomDatas parameter. (1 - 32 elements) See CustomDataParam

Response Body

200 Ok

Code	Type	Required	Description
returnCode	ReturnCode	true	Additional metadata that can be attached to any request. Especially useful when working with advanced features such as EventCallbackScript. See ReturnCode
debugMessage	string		A developer-oriented message that provides additional context useful for debugging and internal logging. This field is not intended for end-users and may include stack traces, validation failures, or internal error diagnostics.
invalidRequestParameters	InvalidMember[]		Just had data when the returnCode is InvalidRequestParameters.A list of members that failed validation or could not be processed during the request. Each entry typically includes identifying information and an error reason. This is useful for partial success scenarios where some members are accepted and others are rejected. See InvalidMember
parameters	ResponseData		Just had data when the returnCode is Ok. A dynamic set of key-value pairs included in the response to provide additional context or metadata. These parameters may vary depending on the operation and typically contain optional fields such as timestamps, identifiers, or computed values relevant to the result. See ResponseData

ReturnCode

Name	Code	Description
SecretInvalid	-10	Secret token is invalid (removed, expired or does not contains).
MaxSizeRequestReject	-9	Request rejected due to exceeding maximum allowed size.
MaxRequestReject	-8	Request rejected because the number of requests has exceeded the allowed limit per user or IP or exceeds the total number of pending requests the server is waiting to process..
MaxCCUReject	-7	Connection rejected due to exceeding the allowed CCU (Concurrent Users).
OperationNotAuthorized	-6	You are not authorized to perform this operation. Possibly due to missing or invalid token, or insufficient permissions.
InvalidRequestParameters	-5	Request parameters are invalid or missing.
OperationInvalid	-4	The requested operation is invalid or not supported.
InternalServerError	-3	Internal server error. Could be due to an unhandled exception or logic failure.
OperationNotAllow	-2	This operation is not allowed in the current context.
OperationTimeout	-1	The operation timed out. No response received within the expected time.
UnknownError	0	An unknown error occurred. The cause could not be determined.
Ok	1	Success. The operation completed successfully and returned a valid result.

ResponseData

Code	Type	Required	Description
errorCode	ErrorCode		A string that represents the status of the operation. It indicates whether the request was successful or failed due to a specific error condition. See ErrorCode
infoResponseParameters	InfoResponseParameters	true	InfoResponseParameters field in model GamePlayerResponseData. See InfoResponseParameters

CustomDataParam

Represents a key-value pair for custom player data.

Code	Type	Required	Description
key	string	true	The key used to identify a custom data entry. (2 - 32 characters)
value	any	true	The value assigned to a custom or structured data key.

InfoResponseParameters

Contains optional metadata fields returned when requesting player info.

Code	Type	Description
segments	string[]	Include player segment information in the response.
customDatas	GenericModels.DataItem[]	Include key-value custom data fields in the response. See GenericModels.DataItem
displayName	string	Include the player's display name in the response.
avatar	GenericModels.AvatarItem	Include the player's avatar URL or image reference. See GenericModels.AvatarItem
tsCreate	number	Include the timestamp when the player account was created.
tags	GenericModels.TagItem[]	Include tags assigned to the player. See GenericModels.TagItem
playerBan	GenericModels.BanItem	Include any ban status information in the response. See GenericModels.BanItem
playerDatas	GenericModels.DataItem[]	PlayerDatas field in model InfoResponseParameters. See GenericModels.DataItem
playerCurrencies	GenericModels.CurrencyItem[]	Include the player's virtual currency balances. See GenericModels.CurrencyItem
playerStatistics	GenericModels.StatisticsItem[]	Include the player's statistics. See GenericModels.StatisticsItem
playerCharacters	GenericModels.CharacterItem[]	PlayerCharacters field in model InfoResponseParameters. See GenericModels.CharacterItem
playerInventories	GenericModels.InventoryItem[]	PlayerInventories field in model InfoResponseParameters. See GenericModels.InventoryItem
playerGroups	GenericModels.GroupItem[]	PlayerGroups field in model InfoResponseParameters. See GenericModels.GroupItem
playerFriends	GenericModels.FriendItem[]	PlayerFriends field in model InfoResponseParameters. See GenericModels.FriendItem
tsLastLogin	number	TsLastLogin field in model InfoResponseParameters.
ipAddressCreate	string	IpAddressCreate field in model InfoResponseParameters.
countryCode	string	CountryCode field in model InfoResponseParameters.

Generic.DataItem

Represents a structured key-value data pair stored in a player or group profile.

Code	Type	Required	Description
key	string	true	Key used in a structured data pair.
value	any	true	Value assigned to the specified key.

Generic.AvatarItem

Represents avatar-related metadata such as image, icon, and background colors.

Code	Type	Required	Description
type	number	true	Type field in AvatarItem.
value	string	true	Value assigned to the specified key.

Generic.TagItem

Represents a tag or category label used for filtering or grouping entities.

Code	Type	Required	Description
key	string	true	Key used in a structured data pair.
value	string	true	Value assigned to the specified key.

Generic.BanItem

Details information about a ban applied to a player or entity.

Code	Type	Required	Description
tsExpire	number	true	TsExpire field in BanItem.
reason	string	true	Text explaining why the ban or action was applied.

Generic.CurrencyItem

Defines a virtual currency identifier and its current amount.

Code	Type	Required	Description
key	string	true	Key used in a structured data pair.
value	number	true	Value assigned to the specified key.

Generic.StatisticsItem

Represents a named statistic and its numeric value.

Code	Type	Required	Description
key	string	true	Key used in a structured data pair.
value	number	true	Value assigned to the specified key.

Generic.CharacterItem

Describes a character entity associated with a player.

Code	Type	Required	Description
characterId	string	true	Unique identifier of the character.
catalogId	string	true	CatalogId field in CharacterItem.

Generic.InventoryItem

Summarizes the inventory contents and counts for a player or group.

Code	Type	Required	Description
itemId	string	true	ItemId field in InventoryItem.
catalogId	string	true	CatalogId field in InventoryItem.
classId	string	true	ClassId field in InventoryItem.

Generic.GroupItem

Basic reference information about a group entity.

Code	Type	Required	Description
groupId	string	true	Unique identifier of the group.
catalogId	string	true	CatalogId field in GroupItem.
status	number	true	Current state or flag representing the object’s availability.
tsLastStatusUpdate	number	true	TsLastStatusUpdate field in GroupItem.

Generic.FriendItem

Represents a friendship relationship between players.

Code	Type	Required	Description
friendId	string	true	FriendId field in FriendItem.
catalogId	string	true	CatalogId field in FriendItem.
status	number	true	Current state or flag representing the object’s availability.
tsLastStatusUpdate	number	true	TsLastStatusUpdate field in FriendItem.

ErrorCode

Name	Code
Ok	1
GamePlayerNotFound	17

InvalidMember

Code	Type	Description
code	string	The parameterCode invalid.
invalidMemberType	InvalidMemberType	The invalid member type of this parameterCode. See InvalidMemberType

InvalidMemberType

Name	Code	Description
UnknownError	1	An unspecified or unexpected error has occurred.
DataRequired	2	A required data field is missing or not provided.
TypeInvalid	3	The data type provided does not match the expected type.
StringNull	4	A string value is null or has not been assigned.
StringMinLength	5	The string value is shorter than the minimum required length.
StringMaxLength	6	The string value exceeds the maximum allowed length.
NumberMinValue	7	The numeric value is less than the minimum allowed value.
NumberMaxValue	8	The numeric value exceeds the maximum allowed value.
NumberMustInt	9	The numeric value must be an integer but is not.
GNHashtableNull	10	The hashtable object is null or not provided.
GNHashtableMinLength	11	The hashtable contains fewer entries than the minimum required.
GNHashtableMaxLength	12	The hashtable contains more entries than the maximum allowed.
GNArrayNull	13	The array object is null or not provided.
GNArrayMinLength	14	The array contains fewer elements than the minimum required.
GNArrayMaxLength	15	The array contains more elements than the maximum allowed.