Get Started for Developers

The Leaderboards and Tournaments Tournament Organizer extension on Twitch enables broadcasters to set up Leaderboards and Tournaments competitions for their viewers. You need to add some code into your game to integrate the Tournament Organizer Twitch extension into your game.

• Prerequisites for the Game Developer
  • Register your Game with Leaderboards and Tournaments
  • Create a Twitch Account
• Tasks for the Game Developer
  • Integrate with all Leaderboards and Tournaments APIs
  • Integrate Tournament Organizer into an Existing Leaderboards and Tournaments Client
  • Add UI Screens to the game
  • Optional UI
• Re-Linking Twitch Accounts
• Handling Player with Multiple Devices
• Handling Players with Multiple Devices: Example
• Suggested Integration Use Cases

Prerequisites for the Game Developer

You need to fulfill the following prerequisites before you start to integrate your game with Tournament Organizer.

1. Register your game with Leaderboards and Tournaments
2. Create a Twitch Account

These steps are described in the following sections.

Register your Game with Leaderboards and Tournaments

https://developer.amazon.com/gameon/console/home

1. Navigate to the Leaderboards and Tournaments Getting Started page
2. Click Your Leaderboards and Tournaments Console, and sign in with your Amazon Developer credentials.
3. If you are new Amazon developer, click Create your Amazon Developer account to create an account.
4. Register your game in the Leaderboards and Tournaments Console. Follow the directions on this page:
5. Save your game credentials (API key, GameId), which you will use in a subsequent step.

Create a Twitch Account

Create your own Twitch account for testing the extension and broadcaster-generated tournaments.

To create an account on Twitch

1. Navigate to the Twitch Home Page
2. Click Sign up in the top right corner.
3. Create a public user name and a password.
4. Provide your date of birth and an email.
5. Click Sign Up to complete the account creation process.

Tasks for the Game Developer

Follow the steps in the appropriate section below to integrate with the Tournament Organizer functionality, based on whether or not your game is already integrated with Leaderboards and Tournaments.

If you are starting with a new game (or your game is not integrated with Leaderboards and Tournaments), proceed with the directions in Integrate with all Leaderboards and Tournaments APIs, which covers both Leaderboards and Tournaments and Tournament Organizer integration.

If your game is already integrated with Leaderboards and Tournaments and you would like to add Tournament Organizer support, proceed with the directions in Integrate Tournament Organizer into an Existing Leaderboards and Tournaments Client.

Integrate with all Leaderboards and Tournaments APIs

This section describes how to integrate a game with the full set of Leaderboards and Tournaments API integration points. Once you have completed the initial integration with Leaderboards and Tournaments APIs, proceed to Section (B) to add Tournament Organizer support.

For overview information, see Leaderboards and Tournaments API workflows

To integrate with the Leaderboards and Tournaments APIs, including the Tournament Organizer API, your game will need all of the following integration points:

• Register a player
• Authorize a player
• Get the list of player tournaments (see step 1 in section B)
• Link Accounts (see step 2 in section B)
• Save Linked Status (see step 3 in section B)
• Enter the tournament
• Submit score
• For subsequent score submissions: -
  • Call Enter match
  • Call Submit score
• [Optional] Call Leaderboard or Leaderboard with Neighbors

Integrate Tournament Organizer into an Existing Leaderboards and Tournaments Client

This section describes how to add Tournament Organizer support to a game already integrated with Leaderboards and Tournaments:

1. Get the list of Player Tournaments. Use the Leaderboards and Tournaments Tournament Organizer API to show a list of Twitch tournaments, and to enable gamers to participate in these tournaments.

   WARNING: The Leaderboards and Tournaments get-tournaments API method does not return the Twitch tournaments. To get the Twitch tournaments, use get-player-tournament Set queryBy to game, and set streamingPlatform to twitch.

   For details, see Get Player Tournaments.

2. Link Accounts. The Twitch extension provides a unique code to each Twitch player when they click the Get Code button in the Twitch extension. Leaderboards and Tournaments prompts the user to enter their code. Leaderboards and Tournaments uses the code to link their Twitch account with their Leaderboards and Tournaments account, so that Leaderboards and Tournaments can display the players’ Twitch usernames in the leaderboard in the extension. The game client needs to provide a mechanism to validate the code that the player provides
   See Validate Access

3. Save Linked Status. The Game client should save the player’s linked status (true or false), because the player needs to perform this action only once for a given game.
   • You can save this status on the client or on the server.
4. Relinking Users can play from multiple devices. The user requests a code for each device, and enters that code when prompted by the game. You do not require any additional code in the game to handle this case.

Notes

• The player must complete the account-linking step before the player can be entered into a Twitch tournament.
• Account-linking is required only for Twitch tournaments.

Add UI Screens to the game

To add support for Twitch Tournaments, you need to consider the following additions and changes to the UI of your game

• Create a “Twitch Tournaments” (or equivalent) section in the game if not already available.
• Display active streamer tournament listings. Fields include: tournament name, end date and time, and entry button. Note: Some tournaments may require a password upon entry (this is specified by the broadcaster during tournament setup). Use the following instructions to handle a password for a tournament [insert link here].
• Leaderboards and Tournaments code validation mechanism. If the player has not linked their accounts, prompt the player to enter an account-linking code (provided to them from the Twitch extension) in order to link their Leaderboards and Tournaments account with their Twitch account.

Optional UI

Optionally, you can display the following additional information:

• Leaderboards for active tournaments.
• Max number of players and current number of players for active tournaments.
• Past tournaments, associated leaderboards, and/or number of players who participated.
• Future tournament listings and max number of players who can participate.

Re-Linking Twitch Accounts

The Twitch Extension provides a feature that enables players to get more than one code from the extension. A code is good for one player’s device. A player may need another code if they upgrade their device, play on multiple devices, or re-install the Leaderboards and Tournaments game.

Handling Player with Multiple Devices

We strongly recommend that you use VendorPlayerId when you register players in Tournament Organizer tournaments, so that you can handle the re-linking use cases.

See Register Player for details about the Admin API method to register a player. Assign a unique vendorPlayerId to each player. Use the player's vendorPlayerId when the player registers from each device. Leaderboards and Tournaments will recognize the player based on the vendorPlayerId in each registration.

If Game does not use VendorPlayerId field when it registers players with Leaderboards and Tournaments, each of the registrations is considered a new player.

Handling Players with Multiple Devices: Example

Consider a game that is integrated with Leaderboards and Tournaments (without the Leaderboards and Tournaments Tournament Organizer APIs method). On start up, the game registers a player, but doesn't supply vendorPlayerId. Leaderboards and Tournaments automatically creates a playerId for the player. If the same player plays the same game on a different device, a new playerId will be created for the player,even though it is the same person. If scores are submitted from both devices, the players will appear as multiple entries on the leaderboard. This scenario can be prevented by using VendorPlayerId.

This scenario is even more prevalent for a game that is integrated with Leaderboards and Tournaments and the Leaderboards and Tournaments Tournament Organizer APIs method. Similar to above, if the game registers the same player on multiple devices without supplying VendorPlayerID, the user will be considered to be different players in the Leaderboards and Tournaments system. If the player enters link codes from their Twitch account into multiple devices, all of the playerIds map to the same Twitch name. If the player submits scores from different devices, the player will appear as multiple entries on the leaderboard. Again, this scenario can be prevented by using VendorPlayerId.

Suggested Integration Use Cases