Static Public Member Functions
static Task< AchievementUpdate >	AddCount (string name, long count, byte[] extraData)
	Adds a count to a specified count achievement. The count will be added to the current count. For example, if the current count is 1 and the count you would like to add is 7, the final count will be 8 if the request succeeds. More...

static Task< AchievementUpdate >	AddFields (string name, string fields, byte[] extraData)
	Unlocks the bit(s) of a specified bitfield achievement. The status of the bit(s) is then unchangeable. More...

static Task< AchievementDefinitionList >	GetAllDefinitions (int pageIdx, int pageSize)
	Gets the information about all achievements, including API names, descriptions, types, the targets which must be reached to unlock those achievements, and more. More...

static Task< AchievementProgressList >	GetAllProgress (int pageIdx, int pageSize)
	Gets the user's progress on all achievements, including API names, whether or not the achievements are unlocked, the time at which they were unlocked, achievement types and, depending on the type, the progress made towards unlocking them, and more. More...

static Task< AchievementDefinitionList >	GetDefinitionsByName (string[] names)
	Gets the information about specified achievements, including API names, descriptions, types, the targets which must be reached to unlock those achievements, and more. More...

static Task< AchievementProgressList >	GetProgressByName (string[] names)
	Gets the user's progress on specified achievements, including API names, whether or not the achievements are unlocked, the time at which they were unlocked, achievement types and, depending on the type, the progress made towards unlocking them, and more. More...

static Task< AchievementUpdate >	Unlock (string name, byte[] extraData)
	Unlocks a specified achievement of any type even if the target for unlocking this achievement is not reached. More...

Detailed Description

The Achievements service can help build a "positive feedback mechanism" in your games. You can create prizes such as trophies and badges and distribute them to players when they hit a goal, like completing the beginner tutorial or reaching level x. Advanced achievements such as completing a hidden level/task should be closely integrated with game content design and, meanwhile, collaborate with prizes like diamonds or props to make your games more challenging and further enhance players' engagement.

Member Function Documentation

◆ AddCount()

static Task< AchievementUpdate > AddCount	(	string	name,
		long	count,
		byte[]	extraData
	)

inlinestatic

Adds a count to a specified count achievement. The count will be added to the current count. For example, if the current count is 1 and the count you would like to add is 7, the final count will be 8 if the request succeeds.

Note: Available to count achievements only.

Parameters

name	The API name of the achievement.
count	The count you want to add. The largest count supported by this function is the maximum value of a signed 64-bit integer. If the count is larger than that, it is clamped to that maximum value before being passed to the servers.
extraData	Custom extension fields that can be used to record key information when unlocking achievements.

Returns

The request ID of this async function.

Error Code	Error Message
10729	invalid api name
10733	invalid count
10725	extra data too long
10720	achievement is not exist
10723	load achievement data failed
10726	achievement is unreleased
10727	achievement is archived
10722	no write permission
10736	invalid parameter
10735	invalid extra data
10734	operation is not allowed on the type
10728	achievement is unlocked
10724	save achievement data failed

A message of type MessageType.Achievements_AddCount will be generated in response. First call Message.IsError() to check if any error has occurred. If no error has occurred, the message will contain a payload of type AchievementUpdate. Extract the payload from the message handle with Message.Data.

AchievementUpdate contains the following:

JustUnlocked: Whether the achievement has been successfully unlocked.
Name: The API name of the achievement.

◆ AddFields()

static Task< AchievementUpdate > AddFields	(	string	name,
		string	fields,
		byte[]	extraData
	)

inlinestatic

Unlocks the bit(s) of a specified bitfield achievement. The status of the bit(s) is then unchangeable.

Note: Available to bitfield achievements only.

Parameters

name	The API name of the achievement to unlock bit(s) for.
fields	A string containing either the `0` or `1` characters, for example, `100011`. Every `1` will unlock a bit in the corresponding position of a bitfield.
extraData	Custom extension fields that can be used to record key information when unlocking achievements.

Returns

The request ID of this async function.

Error Code	Error Message
10729	invalid api name
10731	invalid field
10725	extra data too long
10720	achievement is not exist
10723	load achievement data failed
10726	achievement is unreleased
10727	achievement is archived
10722	no write permission
10736	invalid parameter
10735	invalid extra data
10734	operation is not allowed on the type
10728	achievement is unlocked
10724	save achievement data failed

A message of type MessageType.Achievements_AddFields will be generated in response. First call Message.IsError() to check if any error has occurred. If no error has occurred, the message will contain a payload of type AchievementUpdate. Extract the payload from the message handle with Message.Data.

AchievementUpdate contains the following:

JustUnlocked: Whether the achievement has been successfully unlocked.
Name: The API name of the achievement.

◆ GetAllDefinitions()

static Task< AchievementDefinitionList > GetAllDefinitions	(	int	pageIdx,
		int	pageSize
	)

inlinestatic

Gets the information about all achievements, including API names, descriptions, types, the targets which must be reached to unlock those achievements, and more.

Parameters

pageIdx	Defines which page of achievements to return. The first page index is `0`.
pageSize	The size of the page.

Returns

The request ID of this async function.

Error Code	Error Message
10721	invalid api name
10736	invalid parameter
10720	achievement is not exist
10723	load achievement data failed

A message of type MessageType.Achievements_GetAllDefinitions will be generated in response. First call Message.IsError() to check if any error has occurred. If no error has occurred, the message will contain a payload of type AchievementDefinitionList. Extract the payload from the message handle with Message.Data.

AchievementDefinitionList contains the following:

Type: The type of the achievement.
Name: The API name of the achievement.
BitfieldLength: The total bits in the bitfield. For bitfield achievements only.
Target: The number of events to complete for unlocking the achievement. For count or bitfield achievements only.
Description: The description of the achievement.
Title: The display name of the achievement that users see.
IsArchived: Whether the achievement is archived. Archiving will not delete the achievement or users' progress on it.
IsSecret: Whether the achievement is hidden until it is unlocked by users.
ID: The data ID.
UnlockedDescription: The message displayed to users when they unlock the achievement.
WritePolicy: Who are able to write achievement progress.
LockedImageURL: The local path to the image displayed to users before they unlock the achievement.
UnlockedImageURL: The local path to the image displayed to users after they unlock the achievement.

◆ GetAllProgress()

static Task< AchievementProgressList > GetAllProgress	(	int	pageIdx,
		int	pageSize
	)

inlinestatic

Gets the user's progress on all achievements, including API names, whether or not the achievements are unlocked, the time at which they were unlocked, achievement types and, depending on the type, the progress made towards unlocking them, and more.

Parameters

pageIdx	Defines which page of achievements to return. The first page index is `0`.
pageSize	The size of the page.

Returns

The request ID of this async function.

Error Code	Error Message
10721	invalid api name
10723	load achievement data failed

A message of type MessageType.Achievements_GetAllProgress will be generated in response. First call Message.IsError() to check if any error has occurred. If no error has occurred, the message will contain a payload of type AchievementProgressList. Extract the payload from the message handle with Message.Data.

AchievementProgressList contains the following:

ID: The data ID.
Bitfield: A bitfield displaying the bits unlocked for a bitfield achievement, for example, 1110001.
Count: The number of events completed for unlocking a count achievement.
IsUnlocked: Whether the achievement is unlocked.
Name: The API name of the achievement.
UnlockTime: The time at which the achievement was unlocked.
ExtraData: The key information recorded when unlocking the achievement.

◆ GetDefinitionsByName()

static Task< AchievementDefinitionList > GetDefinitionsByName ( string[] names )

inlinestatic

Gets the information about specified achievements, including API names, descriptions, types, the targets which must be reached to unlock those achievements, and more.

Parameters

names The API names of the achievements.

Returns

The request ID of this async function.

Error Code	Error Message
10729	invalid api name
10730	too many api names
10721	invalid request
10736	invalid parameter
10720	achievement is not exist
10723	load achievement data failed

A message of type MessageType.Achievements_GetDefinitionsByName will be generated in response. First call Message.IsError() to check if any error has occurred. If no error has occurred, the message will contain a payload of type AchievementDefinitionList. Extract the payload from the message handle with Message.Data.

AchievementDefinitionList contains the following:

Type: The type of the achievement.
Name: The API name of the achievement.
BitfieldLength: The total bits in the bitfield. For bitfield achievements only.
Target: The number of events to complete for unlocking the achievement. For count or bitfield achievements only.
Description: The description of the achievement.
Title: The display name of the achievement that users see.
IsArchived: Whether the achievement is archived. Archiving will not delete the achievement or users' progress on it.
IsSecret: Whether the achievement is hidden until it is unlocked by users.
ID: The data ID.
UnlockedDescription: The message displayed to users when they unlock the achievement.
WritePolicy: Who are able to write achievement progress.
LockedImageURL: The local path to the image displayed to users before they unlock the achievement.
UnlockedImageURL: The local path to the image displayed to users after they unlock the achievement.

◆ GetProgressByName()

static Task< AchievementProgressList > GetProgressByName ( string[] names )

inlinestatic

Gets the user's progress on specified achievements, including API names, whether or not the achievements are unlocked, the time at which they were unlocked, achievement types and, depending on the type, the progress made towards unlocking them, and more.

Parameters

names The API names of the achievements.

Returns

The request ID of this async function.

Error Code	Error Message
10729	invalid api name
10730	too many api names
10721	invalid request
10723	load achievement data failed

A message of type MessageType.Achievements_GetProgressByName will be generated in response. First call Message.IsError() to check if any error has occurred. If no error has occurred, the message will contain a payload of type AchievementProgressList. Extract the payload from the message handle with Message.Data.

AchievementProgressList contains the following:

ID: The data ID.
Bitfield: A bitfield displaying the bits unlocked for a bitfield achievement, for example, 1110001.
Count: The number of events completed for unlocking a count achievement.
IsUnlocked: Whether the achievement is unlocked.
Name: The API name of the achievement.
UnlockTime: The time at which the achievement was unlocked.
ExtraData: Records the key information when unlocking the achievement.

◆ Unlock()

static Task< AchievementUpdate > Unlock	(	string	name,
		byte[]	extraData
	)

inlinestatic

Unlocks a specified achievement of any type even if the target for unlocking this achievement is not reached.

Parameters

name	The API name of the achievement to unlock.
extraData	Custom extension fields that can be used to record key information when unlocking achievements.

Returns

The request ID of this async function.

Error Code	Error Message
10729	invalid api name
10725	extra data too long
10720	achievement is not exist
10723	load achievement data failed
10726	achievement is unreleased
10727	achievement is archived
10722	no write permission
10736	invalid parameter
10735	invalid extra data
10728	achievement is unlocked
10724	save achievement data failed

A message of type MessageType.Achievements_Unlock will be generated in response. First call Message.IsError() to check if any error has occurred. If no error has occurred, the message will contain a payload of type AchievementUpdate. Extract the payload from the message handle with Message.Data.

AchievementUpdate contains the following:

JustUnlocked: Whether the achievement has been successfully unlocked.
Name: The API name of the achievement.

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ AddCount()

◆ AddFields()

◆ GetAllDefinitions()

◆ GetAllProgress()

◆ GetDefinitionsByName()

◆ GetProgressByName()

◆ Unlock()