Achievements

The Y8 SDK allows your game to retrieve configured achievements, unlock achievements for authenticated players, and display achievements using the built-in Y8 interface.

Select your engine to view the appropriate implementation.

Get Achievements

Retrieve all achievements configured for your application.

JavaScriptUnityConstruct 3Haxe

y8Sdk.getAchievements()
    .then((achievements) => {
        console.log(achievements);
    })
    .catch((error) => {
        console.error(error.message);
    });

If the player is authenticated, each achievement includes player-specific unlock information.

Achievement Object

Property	Type	Description
`achievementid`	`string`	Unique achievement identifier.
`achievement`	`string`	Achievement title.
`description`	`string`	Achievement description.
`achievementkey`	`string`	Achievement key.
`icon`	`string`	Achievement icon URL.
`difficulty`	`string`	Achievement difficulty.
`secret`	`boolean`	Whether the achievement is hidden until unlocked.
`awarded`	`number`	Unlock marker.
`game`	`string`	Associated game.
`link`	`string`	Achievement link.
`player`	`object`	Present when the signed-in player has unlocked it.

Field names here are lowercase

The keys you read back are lowercase — achievementkey, not the achievementKey you pass when awarding one. The two are easy to transpose.

Checking whether an achievement is unlocked

Test for player rather than awarded. It is what the Y8 platform's own achievements panel uses, and it is either present or absent, where awarded is a number whose meaning is less obvious:

const unlocked = achievement.player != null;

JsResponse response = await Y8.Instance.GetAchievements();

if (response.IsSuccess)
{
    Debug.Log(response.Data);
}

If the player is authenticated, each achievement includes player-specific unlock information.

GetAchievements → On clicked
                → Call getAchievement

When the achievement data is loaded, the onAchievementsLoaded function is triggered.

On function onAchievementsLoaded
    → achievementsData

GetAchievements

The achievement data is provided as a JSON string.

Y8.getAchievements(function(achievements:Dynamic) {
    if (achievements == null) {
        trace("Failed to get achievements");
        return;
    }

    trace("[Y8] Achievements:");
    trace(haxe.Json.stringify(achievements, null, "  "));
});

The callback receives the available achievement data.

If the request fails, the callback receives null.

Award an Achievement

Unlock an achievement for the authenticated player.

JavaScriptUnityConstruct 3Haxe

y8Sdk.awardAchievement({
    achievement: "First Win",
    achievementKey: "abc123...",
    overwrite: false,
    allowDuplicates: false
})
.then(() => {
    console.log("Achievement unlocked");
})
.catch((error) => {
    console.error(error.message);
});

Parameters

Property	Type	Required	Description
`achievement`	`string`	Yes	Achievement title configured in the Y8 dashboard.
`achievementKey`	`string`	Yes	Achievement key configured in the Y8 dashboard.
`overwrite`	`boolean`	No	Allow the achievement to be awarded again. Default: `false`.
`allowDuplicates`	`boolean`	No	Allow multiple unlock records. Default: `false`.

JsResponse<AchievementSave> response =
    await Y8.Instance.AwardAchievementAsync(
        "First Win",
        "abc123...",
        false,
        false
    );

if (response.IsSuccess)
{
    Debug.Log("Achievement unlocked");
}

Parameters

Parameter	Type	Required	Description
`achievement`	`string`	Yes	Achievement title configured in the Y8 Developer Portal.
`achievementKey`	`string`	Yes	Achievement key configured in the Y8 Developer Portal.
`overwrite`	`bool`	No	Allow the achievement to be awarded again. Default: `false`.
`allowDuplicates`	`bool`	No	Allow multiple unlock records. Default: `false`.

AwardAchievement → On clicked
                 → Call unlockAchievement
                    name: "First Win"
                    key: "abc123..."
                    overwrite: false
                    duplicate: false

Y8.awardAchievement(
    "First Win",
    "abc123...",
    false,
    false
);

Parameters

Parameter	Type	Required	Description
`achievement`	`String`	Yes	Achievement title configured in the Y8 dashboard.
`achievementKey`	`String`	Yes	Achievement key configured in the Y8 dashboard.
`overwrite`	`Bool`	No	Allow the achievement to be awarded again. Default: `false`.
`allowDuplicates`	`Bool`	No	Allow multiple unlock records. Default: `false`.

Display Achievements

Display the built-in achievements interface.

If the player is authenticated, previously unlocked achievements are highlighted together with their unlock dates.

JavaScriptUnityConstruct 3Haxe

y8Sdk.showAchievements()
    .then(() => {
        console.log("Achievements dialog closed");
    });

await Y8.Instance.ShowAchievementsAsync();

Debug.Log("Achievements dialog closed");

ShowAchievements → On clicked
                 → Call showAchievement

GetAchievements

Y8.showAchievements();

Embed Achievements

The embedded achievements view is currently documented for JavaScript.

JavaScriptUnityConstruct 3Haxe

const achievements = y8Sdk.embedAchievements({
    target: "#achievements-panel"
});

Remove the embedded view when it is no longer needed.

achievements.destroy();

Parameters

Property	Type	Required	Description
`target`	`string \\| HTMLElement`	Yes	CSS selector or HTML element that will contain the achievements view.

Important

The embedded achievements view automatically fills the width and height of its container.

Ensure the target element has explicit dimensions; otherwise, the embedded view may collapse.

Not available on this platform. Use the full-screen achievements view described above.

Call embedAchievements from your event sheet, giving it the HTML element to place the view into:

embeddedAch = y8Sdk.embedAchievements({
    target: "#achievements-panel"
});

Remove it with destroyAchievements.

The container needs explicit dimensions, or the view collapses to nothing.

Not available on this platform. Use the full-screen achievements view described above.

Best Practices

Load achievements during game startup or when opening achievement-related screens.
Retrieve achievements when your game needs to display or work with achievement data.
Award achievements only after the required gameplay conditions have been met.
Ensure the player is authenticated before attempting to award an achievement.
Keep achievement names and keys synchronized with those configured in the Y8 dashboard.
Handle asynchronous operations and errors appropriately for your engine.
Use the built-in achievements interface for a quick platform experience.
Use the embedded achievements view when integrating achievements into your own JavaScript UI.