Get Started for Developers
The GameOn Tournament Organizer extension on Twitch enables broadcasters to set up GameOn 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
- Tasks for the Game Developer
- 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.
- Register your game with GameOn
- Create a Twitch Account
These steps are described in the following sections.
Register your Game with GameOn
- Navigate to the GameOn Getting Started page
- Click Your GameOn Console, and sign in with your Amazon Developer credentials.
- If you are new Amazon developer, click Create your Amazon Developer account to create an account.
- Register your game in the GameOn Console. Follow the directions on this page:
- 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
- Navigate to the Twitch Home Page
- Click Sign up in the top right corner.
- Create a public user name and a password.
- Provide your date of birth and an email.
- 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 GameOn.
If you are starting with a new game (or your game is not integrated with GameOn), proceed with the directions in Integrate with all GameOn APIs, which covers both GameOn and Tournament Organizer integration.
If your game is already integrated with GameOn and you would like to add Tournament Organizer support, proceed with the directions in Integrate Tournament Organizer into an Existing GameOn Client.
Integrate with all GameOn APIs
This section describes how to integrate a game with the full set of GameOn API integration points. Once you have completed the initial integration with GameOn APIs, proceed to Section (B) to add Tournament Organizer support.
For overview information, see GameOn API workflows
To integrate with the GameOn 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 GameOn Client
This section describes how to add Tournament Organizer support to a game already integrated with GameOn:
Get the list of Player Tournaments. Use the GameOn Tournament Organizer API to show a list of Twitch tournaments, and to enable gamers to participate in these tournaments.
WARNING: The GameOn get-tournaments API method does not return the Twitch tournaments. To get the Twitch tournaments, use get-player-tournament Set
queryByto game, and set
For details, see Get Player Tournaments.
Link Accounts. The Twitch extension provides a unique code to each Twitch player when they click the Get Code button in the Twitch extension. GameOn prompts the user to enter their code. GameOn uses the code to link their Twitch account with their GameOn account, so that GameOn 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
- 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.
- 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.
- 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].
- GameOn 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 GameOn account with their Twitch account.
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 GameOn 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. GameOn will recognize the player based on the vendorPlayerId in each registration.
If Game does not use VendorPlayerId field when it registers players with GameOn, each of the registrations is considered a new player.
Handling Players with Multiple Devices: Example
Consider a game that is integrated with GameOn (without the GameOn Tournament Organizer APIs method). On start up, the game registers a player, but doesn't supply vendorPlayerId. GameOn 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 GameOn and the GameOn 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 GameOn 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
|1||Player discovery of GameOn code entry.||Game UI presents an in-game mechanism for the player to enter the account-linking code|
|2||Player enters valid GameOn code.||Success. Player enters the code and receives a success message from the game.|
|3||Player enters invalid GameOn code.||Sample Error Message: The account-linking code has expired. Please get a new code from the tournament listing on Twitch.|
|4||Player discovery of broadcaster-created tournament.||Game UI presents a list of player-tournaments for players to discover. Players must be able to join the tournament from within the game.|
|5||Player attempts to join tournament, but has not linked account with GameOn code.||Sample Error Message: To join the tournament, you must first link your Twitch account. Please get a code from the tournament listing on Twitch and return to the game to enter the code, then you can join the tournament.|
|6||Player attempts to join tournament, and has already linked account with GameOn code.||Success. Player successfully joins the tournament.|
|7||Player attempts to join a tournament that requires a password and provides a valid password.||Success. Player successfully joins the tournament.|
|8||Player attempts to join a tournament that requires a password and provides an invalid password.||Sample Error Message: This tournament requires a password. Please return to the tournament on Twitch to request a password from the streamer.|