Interface IAchievementPlatformGateway

Application port for mirroring achievements to a storefront or console account (Steam, Xbox, Epic, PlayStation).

Namespace: Serenity.Achievements.Application.Interfaces.Gateways

Assembly: Serenity.Achievements.Application.dll

Syntax

public interface IAchievementPlatformGateway

Remarks

A gateway is a sync target, never the source of truth: it stores none of the screenshot key, the Serenity points, the exact progress numerator or the hidden-until-unlocked rule. Every operation returns whether it succeeded rather than throwing — an unavailable platform is the normal case in the editor, in a headless build and on a PC with the client closed.

Properties

IsAvailable

Whether the platform is reachable right now.

Declaration

bool IsAvailable { get; }

Property Value

Type	Description
bool

PlatformName

The human-readable name of the platform this gateway talks to.

Declaration

string PlatformName { get; }

Property Value

Type	Description
string

Methods

ClearAsync(CancellationToken)

Clears every achievement on the platform account. Intended for debugging and QA.

Declaration

Task<bool> ClearAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<bool>	True when the platform accepted the clear; otherwise false.

InitializeAsync(CancellationToken)

Brings the platform session up. Returns whether the gateway is usable afterwards.

Declaration

Task<bool> InitializeAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<bool>

QueryUnlockedAsync(CancellationToken)

Reads back which achievements the platform account already has.

Declaration

Task<PlatformUnlockQueryResult> QueryUnlockedAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<PlatformUnlockQueryResult>

Remarks

The result keeps "the account has nothing unlocked" apart from "the platform could not be asked": a gateway that genuinely has no account to be wrong about (no SDK configured, no storefront targeted) answers Answered(IReadOnlyList<AchievementId>) with an empty list, while a gateway that talks to a real storefront answers Unreachable() when the client is down, the call throws, or it cannot otherwise vouch for the account it is reporting. Collapsing the two makes an unreachable storefront indistinguishable from an empty one, which is the exact invariant PlatformUnlockQueryResult exists to protect.

SetProgressAsync(AchievementDefinition, long, long, CancellationToken)

Reports progress towards a progressive achievement on the platform account.

Declaration

Task<bool> SetProgressAsync(AchievementDefinition definition, long current, long target, CancellationToken cancellationToken)

Parameters

Type	Name	Description
AchievementDefinition	definition	The achievement being advanced, carrying its platform identifiers.
long	current	The current numerator.
long	target	The numerator that unlocks the achievement.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<bool>	True when the platform accepted the progress; otherwise false.

UnlockAsync(AchievementDefinition, CancellationToken)

Marks an achievement as unlocked on the platform account.

Declaration

Task<bool> UnlockAsync(AchievementDefinition definition, CancellationToken cancellationToken)

Parameters

Type	Name	Description
AchievementDefinition	definition	The achievement to unlock, carrying its platform identifiers.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<bool>	True when the platform accepted the unlock; otherwise false.