Editor's Note: We are hosting a Skills GameOn SDK webinar on 7/31 to help you learn more. You can register here.

Leaderboards are a great way to keep players engaged with your game skills and drive retention. You can now use the Skills GameOn SDK (beta), powered by Amazon GameOn and optimized for Alexa skills, to easily integrate leaderboards into your game skills.

We are also excited to announce that we have a special offer to help more skill developers leverage the GameOn capabilities. If you publish an Alexa skill using the Skills GameOn SDK (or calling the GameOn service via other means) during the beta period, you will be eligible to use GameOn for free within the Alexa skill. Simply complete and submit this application to qualify for the offer. If your skill has been whitelisted for free plays, your skill can continue to use GameOn for free after the Skills GameOn SDK beta period ends. GameOn is available in any of the countries and regions where AWS is offered. Learn more here.

Best Practices for Designing with Leaderboards

The SDK provides easy access to all of the GameOn APIs and creates higher-level methods that simplify the most common actions skill developers need. It has a sample Alexa Presentation Language (APL) leaderboard template that can be used for building multimodal skills. For general best practices around leaderboard integration, you can read the GameOn best practices Ebook. Here are some tips and best practices for using the Skills GameOn SDK.

1. Getting Started

Check out our Skills GameOn SDK documentation to get started, and reference the Amazon GameOn documentation at your convenience. If you’ve never used Amazon GameOn, we recommend that you complete the prerequisites as outlined here and follow the "Simple Week-Long Tournament” tutorial.

2. Key Management

We recommend using a service such as AWS Key Management Service to secure your key, instead of exposing your GameOn public API key in cleartext in your source code. We provide two suggestions on how to do this in our documentation.

3. Profile Management

You can use our player name and icon generator to assign a funny name and a profile icon to each player. You can read more about the player name generator in our documentation.

4. Authenticate Player

To create a new player, simply call the SkillsGameOnApiClient.initializeNewAugmentedPlayer function with your Game API Key and appBuildType (‘development’ or ‘release’). Optionally, you can pass in a reference to the profile generator builder. Then, call the enterTournamentForPlayer function with the player and tournament ID to enter. Here's an example for initializing a new player.

const sdk = require("@alexa-games/skills-gameon-sdk");
const apiClient = new sdk.SkillsGameOnApiClient();
const generator = sdk.PlayerProfileGeneratorBuilder.getGenerator({
    locale: "en-US",
    avatarBaseUrl: "<<Avatar Base URL>>",
    numberOfUniqueAvatars: 50
});
…
const alexaPlayer = await apiClient.initializeNewAugmentedPlayer({ 
    gameApiKey: “<<GameOn gameApiKey>>”,
    appBuildType: “<<GameOn appBuildType>>”,
    playerProfileGenerator: generator 
});

await apiClient.enterTournamentForPlayer({ 
    tournamentId: “<<GameOn tournamentId>>”, 
    player: alexaPlayer 
});

​5. Session Management

We’ve also provided a refreshPlayerSession convenience method to help you easily manage when to invoke Authenticate Player. You will want to call this refresh method every time you make a call with the client after initializing your player. Read more here. Here's an example.

await apiClient.refreshPlayerSession({
    gameApiKey: “<<GameOn gameApiKey>>”,
    appBuildType: “<<GameOn appBuildType>>”,
    player: alexaPlayer
});

6. Tournaments

If you want to create a persistent, long-term leaderboard, create the tournament and set the end date to be a date far in the future. When first learning how to create recurring tournaments, only make a few at a time for practice, as you will have to manually delete them individually. If you would like to do daily or weekly tournaments, call SkillsGameOnApiClient.getTournamentsByTitle in order to get the correct tournament. Learn more here.

7. Visuals for Multimodal Leaderboard Skills

When you integrate a leaderboard to your skill, you can display it visually on Alexa-enabled devices with screens, such as the Echo Show and the Fire TV. When creating visuals using the Alexa Presentation Language, make sure to create an optimized experience for each of the four viewport profiles. Check out our sample that include 4 different viewport profiles. To enhance your experience with visuals, you can use a wrapper. Here's an example:

const sdk = require('@alexa-games/skills-gameon-sdk');
const defaultClient = new sdk.SkillsGameOnApiClient();
…
/**
 * Retrieve a rendered leaderboard APL document. This function assumes that you always want the score and rank
 * stored with GameOn. If you configure the leaderboard to only persist the best score, but want to display how the
 * player performed in this particular instance, you can use the SkillsGameOnApiClient.renderLeaderboard and pass in
 * an AugmentedPlayer with the desired PlayerScore.
 *
 * @param {Player} alexaPlayer
 * @param {SkillsGameOnApiClient} [client=defaultClient]
 * @returns Alexa APL document directive
 */
async function getLeaderboard(alexaPlayer, client = defaultClient) {
    const leaderboard = await client.getCombinationLeaderboards({
        matchId: “<<GameOn matchId>>”,
        topScoresLimit: <<number of top places to display>>,
        playerNeighborsLimit: <<number of neighboring places above/below to display>>,
        player: alexaPlayer
    });
    
    const currentScore = await client.getPlayerScore(
        “<<GameOn matchId>>”,
        alexaPlayer
    );
    
    alexaPlayer.score.ordinalRank = currentScore.ordinalRank;
    alexaPlayer.score.rank = currentScore.rank;
    alexaPlayer.score.score = currentScore.score;
    const renderOptions = { 
        backgroundImageUrl: “<<LeaderBoard Background URL>>” 
    };
    
    return sdk.renderLeaderboard(alexaPlayer, leaderboard, renderOptions, generator);
}

To support Alexa enabled devices without screens, you can fetch the player score directly to read it out.

playerscore = await apiClient.getPlayerScore(
        match, 
        alexaPlayer);

8. Saving Scores

You can save a player’s score only after they have entered the tournament. To do so, call the SkillsGameOnApiClient.submitScoreForPlayer function with the match ID, score object, and Alexa player object. Don’t forget to refresh the session, if needed.

await refreshPlayerSession(alexaPlayer);
await apiClient.submitScoreForPlayer({
    matchId: “<<GameOn matchId>>”,
    submitScoreRequest: { score },
    player: alexaPlayer, 
    ensureMatchEntered: true 
});

Get Inspired by Trying our Reference Skill

Check out Word Word, our reference skill that showcases daily tournaments and many of the features in the Skills GameOn SDK. Word Word is a fun tongue-twisting challenge available in the US skill store or the UK skill store. The skill gives you a silly, random word, and you simply repeat the word as many times as you can. The skill keeps track of your standings against the larger Alexa community. Try the skill by saying “Alexa, open Word Word”.

You can also access the Word Word Lite code sample, inspired by the Word Word skill. Just like the original skill, it leverages the Skills GameOn SDK, but has a modified game loop and does not include the production audio assets.

Apply Now to Use GameOn for Free for Your Skills

To apply for the special offer, submit this application, and we will whitelist your skill within 3 business days until the end of public beta. Please note that you need to provide your skill ID, and GameOn Game ID to apply. You can either use the Skills GameOn SDK in Node.js for easier integration for skills written in Node.js or integrate Amazon GameOn directly for skills written in other languages including Java. To learn more, check out the Skills GameOn SDK GitHub repository, and read the documentation.

Additional Resources

• Alexa Skills Kit Gaming Hub
• Alexa Game Skill Guide
• Alexa Presentation Language for rich multimodal experiences
• In-Skill Purchasing for monetization
• Amazon GameOn documentation: In addition to leaderboards, you can use GameOn to strengthen your fanbase with leagues, awarding in-game prizes, and allowing players and streamers to create their own user-generated competitions.These features can be combined to create complex team based seasons, recurring competitions, and more. You can learn more by reading the full Amazon GameOn documentation.