Amazon GameOn: Create Prizes And Requirement Groups

When working with the Amazon GameOn API, you may wish to limit who is eligible to enter a tournament through Requirement Groups, and/or you may also wish to give out Prizes (digital only). These things require you to have set them up beforehand using the GameOn Admin Api, and so in this article we explain how to go ahead and do this.

Note that before continuing, we recommend that you have set up the Amazon GameOn dashboard and already initialised the asset in your test project or game. For details on how to do this, please see here:

This article shows two methods for setting up Prizes and Requirement Groups - either through the GameOn Developer Console, or by using some command line tools and JSON. If you wish to use the Developer Console only (which is recommended) then skip the following section on "Setting Up The Command Line Tools".

While the sections below give a basic outline of how to set up prizes and requirement groups, you can find the complete information from the Amazon docs.

 

Setting Up Command Line Tools

If you prefer not to use the Amazon Developer Console and want to create prizes or requirement groups using the command line, you must first have installed some kind of client-side URL transfer library. We recommend cURL for this, which you can get from the following link (if you are on macOS, then it is already installed with the OS):

Once you have installed cURL you'll also need to get your Admin API Key from the GameOn dashboard (click the "Details" section of the registered project):

GameON_AdminKey.png

You will then need to open up Terminal (on macOS) or Command Prompt (on Windows, with Admin rights), as cURL is a command line tool. We will be using it to send data to the GameOn Admin API and set up our prizes/groups.

NOTE: On Windows, open the command prompt in the "bin" folder of your cURL installation - e.g. if you unzipped the contents of the downloaded cURL package to "C:\curl", you will need to go to the "C:\curl\bin" folder in your command line tool as the first command you run, by entering: cd "C:\curl\bin"

Later, we will be using cURL to upload JSON files to the Amazon servers, supplying information to the GameOn Admin API. However, it should be noted that the Amazon JSON parser is very sensitive to how your JSON is formatted and we recommend that you check your compatibility with this before uploading any files (there are plenty of online tools like this one which can help).

 

Prizes

As mentioned at the start of this article, there are two ways that you can set up prizes for GameOn tournaments: the first is to use the GameOn Developer console and the second is to use the command line. We'll cover both methods here, starting with setting them through the GameOn Developer console.

When you've signed-in to your GameOn Developer Console, you need to click the Your Prizes link at the top of the window: GameOn_PrizeDashboard.png

From this section of the console you can create the prizes for the different games that are set up. To create a prize, you first select the game from the drop-down on the left and then click the Create Prizes button. This will open the following window:

GameOn_PrizeSetup.png

Here you must give a Name to identify your prize as well as an Info string which is used when claiming your prize through the API. You also have the option to add an Image via a URL as well as a short text description of the prize.

When you are finished, click the Create Prize button at the bottom and you will be taken back to the main Your Prizes screen, where you can see the new prize listed along with any others you make:

GameOn_PrizeList.png

For further information on prizes in the Admin API, please see the following Amazon documentation:

 

Prizes Using The Command Line

To set up prizes using the command line tools, you need to first make a JSON file with the appropriate prize data. This JSON should be structured as shown in the following example - note that you are required to supply "title" and "prizeInfo" strings, but the "description" and "imageURL" are optional (the image URL used below is for an example image from Amazon, but you can supply your own URL):

{
  "prizes": [
    {
      "description": "Test prize",
      "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
      "title": "Test prize A",
      "prizeInfo": "TEST_PRIZE_A"
    },
    {
      // More prizes as required
    }
  ]
}

Once you've saved that to a file - like "GameOnPrizes.json" - you can go to the command line and run the following command:

curl -X POST -H "X-Api-Key: <ADMIN API KEY>" -H "Content-Type: application/json" -d "@<FULL PATH TO FILE>" https://admin-api.amazongameon.com/v1/prizes

So an actual example would look like this:

curl -X POST -H "X-Api-Key: cb373cdd-4702-cc30-992f-1b6253a84763" -H "Content-Type: application/json" -d "@C:\Users\JohnSmith\Documents\GameOnPrizes.json" https://admin-api.amazongameon.com/v1/prizes

If successful, you should see a response similar to this in your command line:

{
  "addedPrizes": [
    {
    "prizeId": "186f9f08-0677-40a1-8ca6-22e69f5ad80c",
    "title": "Test prize A",
    "description": "Test prize",
    "imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
    "prizeInfoType": "VENDOR",
    "prizeInfo": "TEST_PRIZE_A"
    }
  ]
}

Note that you can retrieve all currently defined prizes at any time using the following:

curl -X GET -H "X-Api-Key: <ADMIN API KEY>" -H "Content-Type: application/json" "https://admin-api.amazongameon.com/v1/prizes"

This will return a response similar to that shown above.

For further information on prizes in the Admin API, please see the following Amazon documentation:

  

Requirement Groups

Requirement groups, like prizes, can be created either through the Developer Console or through the use of the command line.

If you prefer to use the Developer Console, then you need to create the Requirement Groups at the same time as you create a tournament, as outlined in the Amazon GameOn docs here:

If you would prefer to use the command line, then you will first be required to have created a properly formatted JSON file with the group information. There are four different types of requirement group that you can set up:

  • GPS (location) - Use the user device location
  • Range - Use a range of values
  • Regex - Use  a regular expression
  • Value  - Use a single value

This JSON should be structured as shown in the following example:

{
  "requirements": [
    {
      "name": "TEST VALUE",
      "description": "This is a test VALUE requirement.",
      "type": "value",
      "key": "val",
      "value": "1"
    },
    {
      "name": "Test Range Req.",
      "description": "This is a test RANGE requirement.",
      "type": "range",
      "key": "rng",
      "high": 10,
      "low": 0
    },
    {
      "name": "Test Regex Req.",
      "description": "This is a test REGEX requirement (input must be numbers only).",
      "type": "regex",
      "key": "nums",
      "value": "^[0-9]+$"
    },
    {
      "name": "Test GPS Req.",
      "description": "This is a test GPS requirement (Greater Seattle Area)",
      "type": "gps",
      "key": "coords",
      "permittedAreas": [
        {
        "gpsCoordinates": {
            "latitude": 47.60604,
            "longitude": -122.3328
          },
          "radius": 10,
          "radiusUnits": "KILOMETERS"
        }
      ]
    }
  ]
}

Once you've saved that to a file - like "GameOnReqGroups.json" - you can go to the command line and run the following command:

curl -X POST -H "X-Api-Key: <ADMIN API KEY>" -H "Content-Type: application/json" -d "@<FULL PATH FILE>" https://admin-api.amazongameon.com/v1/requirements

So an actual example would look like this:

curl -X POST -H "X-Api-Key: cb373cdd-4702-cc30-992f-1b6253a84763" -H "Content-Type: application/json" -d "@C:\Users\JohnSmith\Documents\GameOnReqGroups.json" https://admin-api.amazongameon.com/v1/requirements

If successful, you should see a response similar to this in your command line:

{
  "addedRequirements": [{
    "requirementId": "43ae1bd1-e627-44f1-9015-243ec4c70c06",
    "name": "Test value req.",
    "description": "This is a test VALUE requirement.",
    "type": "value",
    "key": "val",
    "value": "1"
  }, {
    "requirementId": "59de1b23-5ffa-49b5-8a8e-7306dd40104e",
    "name": "Test range req.",
    "description": "This is a test RANGE requirement.",
    "type": "range",
    "key": "rng",
    "low": 0.0,
    "high": 10.0
  }, {
  "addedRequirements": [{
    "requirementId": "57ab1be4-6e27-61f1-5779-456dd1d867a99",
    "name": "Test regex req.",
    "description": "This is a test REGEX requirement (input must be numbers only).",
    "type": "regex",
    "key": "nums",
    "value": "^[0-9]+$"
  }, {
    "requirementId": "bf72f5a9-d806-45d2-b8ef-fe07de15f4b7",
    "name": "Test GPS req.",
    "description": "This is a test GPS requirement (Greater Seattle Area)",
    "type": "gps",
    "key": "coords",
    "permittedAreas": [{
          "gpsCoordinates": {
            "latitude": 47.60604,
            "longitude": -122.3328
          },
          "radius": 10.0,
          "radiusUnits": "KILOMETERS"
        }
      ]
    }
  ]
}

Note that you can retrieve a list of all the requirement groups currently defined by calling the following:

curl -X GET -H "X-Api-Key: <ADMIN API KEY>" -H "Content-Type: application/json" "https://admin-api.amazongameon.com/v1/requirements"

This will return a response similar to that shown above.

 For further information on requirement groups in the Admin API, please see the following Amazon documentation:

 

Summary

This article aims to get you started with using the Amazon GameOn Admin API, but it does not cover everything possible in GameOn; only those things relevant to the GameMaker Studio 2 GameOn sample asset. For full Admin API details, please see the Amazon documentation:

Once you have set up your prizes and requirement groups, you can continue to set up the rest of the asset, as explained here:

 

 

 

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.