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 ?? error);
    });

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`	Icon file name, not a URL. The 64×64 image is at `https://cdn.y8.com/achievements/<appId>/<icon>`.
`difficulty`	`string`	`easy`, `medium` or `hard`. Default: `easy`.
`secret`	`boolean`	Whether the achievement should stay hidden until unlocked. The response still includes its real title, description and icon, so hiding them is up to your game.
`awarded`	`number`	How many times this achievement has been awarded, across all players. It says nothing about the signed-in player.
`game`	`string`	Your game's name, as set on its Y8 application. The same for every achievement.
`link`	`string`	Your game's URL, as set on its Y8 application. The same for every achievement.
`player`	`object`	Present when the signed-in player has unlocked it: `playerid`, `playername`, `date` (when it was unlocked, in Unix seconds) and `rdate` (that time as display text, such as `"3 hours ago"`, `"yesterday"` or `"Oct. 2 2026"`).

New achievements take a while to appear

An achievement added or changed in the Developer Portal can take up to two hours to show up here. Until it does, awarding it fails with error code 503.

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<AchievementsData> response =
    await Y8.Instance.GetAchievements();

if (response.IsSuccess)
{
    foreach (Achievement achievement in response.Data.achievements)
    {
        Debug.Log(achievement.achievement);
    }
}

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

Each Achievement has the fields listed in the JavaScript tab. Its player is a PlayerAchievement with playerid, playername, date and rdate.

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 ?? error);
});

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

Errors

Code	Meaning
`503`	No achievement has that title, or the key does not match it.
`505`	The player already has this achievement. Nothing was saved.

If no player is signed in, the call rejects with a plain string rather than an error object — see "Two different failure shapes" under Handling errors.

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`	Yes	Allow the achievement to be awarded again.
`allowDuplicates`	`Bool`	Yes	Allow multiple unlock records.

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.

The event sheet has no function for this, so call embedAchievements() from a script action. It takes no arguments and always uses this target, which is written in main.js — edit it there to suit your game:

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

The page needs an HTML element with the id achievements-panel. Remove the view 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.