REST API
Examples

Examples

Here is a list of scenarios and examples of how you could implement the Event API to track.

User Account Management

To make sure we know which user an event is referring to, we provide a method to pass common user identifiers associated with your primary user id. Unlike the first version of our event api, where all of these user identifiers had to be sent together with every event, we have now opted for a dedicated method that only needs to be called once when the account is created and only again if there are any changes to a user's details.

Creating / Updating accounts

  • [CLIENT_ID]: Unique identifier for the client application, provided by Earn Alliance
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Earn Alliance
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID]: The game's own internal user identifier
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "identifiers": [
    {
      "userId": "[USER_ID]",
      "discordId": "123456789",
      "email": "john@doe.com",
      "twitterId": "987654321",
      "walletAddress": "0xb794f5ea0ba39494ce839613fffba74279579268"
      },
  ]
}

A full list of supported identifiers:

  • userId (required): string - in-game user identifier
  • discordId: string - numeric Discord ID
  • twitterId: string - numeric Twitter ID
  • appleId: string - Apple ID
  • steamId: string - Steam ID
  • email: string - User Email
  • epicGamesId: string - Epic Games ID
  • walletAddress: string - a valid Ethereum address

Examples of quests this enables:

  • Create an account at Amazing Game
  • Connect Discord to your account at Amazing Game

In addition, sending these user identifiers, will usually be a pre-requisite before a user can start a Challenge for your game on Earn Alliance.

Removing identifiers from an account

  • [CLIENT_ID]: Unique identifier for the client application, provided by Earn Alliance
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Earn Alliance
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID]: The game's own internal user identifier
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "identifiers": [
    {
      "userId": "[USER_ID]",
      "discordId": null,
      "email": null,
      "twitterId": null,
      "walletAddress": null
      },
  ]
}

To remove a user identifier, the value must explicitly be null. What this means is that if a previously set identifier is omitted from the request, it will not be removed. Here is an example flow:

  1. The following identifier payload will create a user record with the email identifier:
{ "userId": "[USER_ID]", "email": "john@doe.com" }
  1. A subsequent request is sent to add the discordId identifier to the already existing user, which will NOT remove the email:
{ "userId": "[USER_ID]", "discordId": "123456789" }
  1. A third request is sent to remove the email identifier from the existing user, leaving only the identifier discordId in place.
{ "userId": "[USER_ID]", "email": null }

A full list of supported identifiers:

  • userId (required): string - in-game user identifier
  • discordId: string - numeric Discord ID
  • twitterId: string - numeric Twitter ID
  • appleId: string - Apple ID
  • steamId: string - Steam ID
  • email: string - User Email
  • epicGamesId: string - Epic Games ID
  • walletAddress: string - a valid Ethereum address

Game Events

Launch the game

  • [CLIENT_ID]: Unique identifier for the client application, provided by Earn Alliance
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Earn Alliance
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID]: The game's own internal user identifier
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"userId": "[USER_ID]", "event": "START_GAME", "time": "2023-10-24T03:42:12.650Z"},
  ],
}

Examples of quests this enables:

  • Install & Login to Amazing Game
  • Login to Amazing Game during the Halloween event

In addition, sending these events, will usually be a pre-requisite for games that needs to be installed (i.e. non web games) before a user can start a Challenge for your game on Earn Alliance.

Track game score

  • [CLIENT_ID]: Unique identifier for the client application, provided by Earn Alliance
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Earn Alliance
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID]: The game's own internal user identifier
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"userId": "[USER_ID]", "event": "GAME_OVER", "value": 1000, "time": "2023-10-24T03:42:12.650Z"},
  ],
}

Examples of quests this enables:

  • Play a round of Amazing Game
  • Play Amazing Game during the Halloween event

Examples of Challenges this enables:

  • Get a score of at least 5,000
  • Get an accumulated score of at least 1,000,000 during one hour

Multiplayer Events

Each event can only point to one user. For multiplayer games, this means that shared events (i.e. MATCH_START) must be sent for each player in the match. But they can all be bundled together in one API request.

Starting a match

  • [CLIENT_ID]: Unique identifier for the client application, provided by Earn Alliance
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Earn Alliance
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID_*]: The game's own internal user identifiers for each player in the match
  • [GROUP_ID]: The game's own internal identifier of the match
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_1]", "event": "MATCH_START", "time": "2023-10-24T03:42:12.650Z"},
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_2]", "event": "MATCH_START", "time": "2023-10-24T03:42:12.650Z"},
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_3]", "event": "MATCH_START", "time": "2023-10-24T03:42:12.650Z"},
  ],
}

PvP Kills

  • [CLIENT_ID]: Unique identifier for the client application, provided by Earn Alliance
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Earn Alliance
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID_*]: The game's own internal user identifiers for each player in the match
  • [GROUP_ID]: The game's own internal identifier of the match
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_1]", "event": "KILL_PLAYER", "traits": {"weapon": "KNIFE", "player": "[USER_ID_2]"}, "time": "2023-10-24T03:45:00.000Z"},
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_2]", "event": "KILLED_BY_PLAYER", "traits": {"weapon": "KNIFE", "player": "[USER_ID_1]"}, "time": "2023-10-24T03:45:00.000Z"},
  ],
}

Note that in the example above, we send individual events for the two players involved in the game event. Since one API event belongs to a specific player, we send one event for each of the involved players of the game event.

Examples of Challenges this enables:

  • Kill at least one other player
  • Kill 3 other players without getting killed
  • Kill another player using a Knife

NPC Kills

  • [CLIENT_ID]: Unique identifier for the client application, provided by Earn Alliance
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Earn Alliance
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID_*]: The game's own internal user identifiers for each player in the match
  • [GROUP_ID]: The game's own internal identifier of the match
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_1]", "event": "KILL_NPC", "traits": {"weapon": "BASEBALL_BAT", "type": "ZOMBIE"}, "time": "2023-10-24T03:45:00.000Z"},
  ],
}

Examples of Challenges this enables:

  • Kill 5 zombies in one match
  • Kill a Zombie using a Baseball Bat

Match Ended

  • [CLIENT_ID]: Unique identifier for the client application, provided by Earn Alliance
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Earn Alliance
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID_*]: The game's own internal user identifiers for each player in the match
  • [GROUP_ID]: The game's own internal identifier of the match
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_1]", "event": "MATCH_END", "traits": {"isSurvivor": true}, "time": "2023-10-24T03:49:00.000Z"},
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_2]", "event": "MATCH_END", "traits": {"isSurvivor": false}, "time": "2023-10-24T03:49:00.000Z"},
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_3]", "event": "MATCH_END", "traits": {"isSurvivor": false}, "time": "2023-10-24T03:49:00.000Z"},
  ],
}

Examples of Challenges this enables:

  • Survive a match in Amazing Game
  • Kill at least one other player and survive the match

Advanced Usage

Batching events together

To reduce the amount of requests for event heavy games, it is possible to batch events together, even when they have different timestamps. Our SDK have this functionality built-in but the same thing can be implemented directly with the REST API.

Note! When evaluating what events can be batched together, concider the user experience that it might affect. Events that have an immediate affect on starting or finishing challenges, should not be delayed / queued for batching, since that might cause a challenge to not start / finish when the user expects it to.

Our recommendation is the bulk events that are not time sensitive (in-game events) together in a 30 second time period, or when the number of pending events reach 100.

  • [CLIENT_ID]: Unique identifier for the client application, provided by Earn Alliance
  • [GAME_ID]: Unique identifier for the game sending the event, provided by Earn Alliance
  • [GENERATED_SIGNATURE]: A signature that verifies the integrity of the request (see Signature Generation)
  • [USER_ID_*]: The game's own internal user identifiers for each player in the match
  • [GROUP_ID]: The game's own internal identifier of the match
POST /v2/custom-events
x-client-id: "[CLIENT_ID]",
x-timestamp: "1698306156387",
x-signature: "[GENERATED_SIGNATURE]",
Content-Type: "application/json"
 
{
  "gameId": "[GAME_ID]",
  "events": [
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_1]", "event": "MATCH_START", "time": "2023-10-24T03:42:12.650Z"},
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_2]", "event": "MATCH_START", "time": "2023-10-24T03:42:12.650Z"},
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_3]", "event": "MATCH_START", "time": "2023-10-24T03:42:12.650Z"},
 
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_1]", "event": "KILL_PLAYER", "traits": {"weapon": "KNIFE", "player": "[USER_ID_2]"}, "time": "2023-10-24T03:45:00.000Z"},
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_2]", "event": "KILLED_BY_PLAYER", "traits": {"weapon": "KNIFE", "player": "[USER_ID_1]"}, "time": "2023-10-24T03:45:00.000Z"},
 
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_1]", "event": "KILL_NPC", "traits": {"weapon": "BASEBALL_BAT", "type": "ZOMBIE"}, "time": "2023-10-24T03:45:00.000Z"},
 
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_1]", "event": "KILL_PLAYER", "traits": {"weapon": "PISTOL_1", "player": "[USER_ID_3]"}, "time": "2023-10-24T03:49:00.000Z"},
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_3]", "event": "KILLED_BY_PLAYER", "traits": {"weapon": "PISTOL_1", "player": "[USER_ID_1]"}, "time": "2023-10-24T03:49:00.000Z"},
 
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_1]", "event": "MATCH_END", "traits": {"isSurvivor": true}, "time": "2023-10-24T03:49:00.000Z"},
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_2]", "event": "MATCH_END", "traits": {"isSurvivor": false}, "time": "2023-10-24T03:49:00.000Z"},
    {"groupId": "[GROUP_ID]", "userId": "[USER_ID_3]", "event": "MATCH_END", "traits": {"isSurvivor": false}, "time": "2023-10-24T03:49:00.000Z"},
  ],
}

Examples of Challenges this enables:

  • Survive a match in Amazing Game
  • Kill 5 zombies in one match
  • Kill at least one other player and survive the match
  • Kill another player using a Knife
Getting StartedGetting Started