Receive data on match winners

Gamezop can post data on winners of multiplayer games on your webhook. This document details out how.

You need to build 2 APIs for this to work:

• Create Match API

• Receive Winners API

Create Match API

You will have to give us a POST API endpoint where we will send the user objects and the roomId when our servers group players into a match. Once we are able to find a match honouring the details you send in the roomDetails object, we will make a request to this endpoint, and you will have to return a matchId. Here's the difference between a roomId and a matchId. Let's say Alice and Bob are playing a Tic Tac Toe game in room ABC01. Alice wins. Now both Alice and Bob see an option to play again. They do so and now Bob wins. In this manner, players with the same roomId may play the game multiple times. While the roomId will remain same each time, the winners may differ across matches. That is why winners are scoped against a matchId and not against a roomId.

Your API endpoint

POST https://api.publisher-xyz.com/games/create-match

You must build and maintain this API. This API is receives user-objects from Gamezop, and returns a unique matchId.

Headers

Name	Type	Description
api-key	String	We can add in an API Key in the headers for added authentication if you require us to.

Request body

Name	Type	Description
roomId*	String	roomId passed by you in the encoded roomDetails object
status*	String	One of 2 options will be passed: MATCH_FOUND or
players*	String	Array of matched together.

HTTP response codes

200: OK

You must respond with a 200 when you return a "matchId"

Expected response body:

    {
       "success": true,
       "matchId": "XYZ_match_number_1" // empty in case NO_MATCH_FOUND
    }

Note for partners charging an entry fee to users

If you are charging an entry fee, then in case of the MATCH_FOUND status, check buy-in validity again for all users in the request body before generating a matchId.

If any player has not paid to join that match, then refund the entry fees charged to all other players and do not return a matchId. We will show a "No match found" screen to the user in this case.

When we post a NO_MATCH_FOUND status, refund the entry fee charged, if any, for the users in the request body.

Receive Winners API

This will be another POST API endpoint where, at the end of each match, we will send the user objects along with their ranks and scores back to your system. If you need to reward a player or take any other action on the basis of this data, you can do so upon receiving our callback on this API.

Your API endpoint

POST https://api.publisher-xyz.com/games/receive-winners

You must build and maintain this API. Gamezop posts data on match winners to your system at the end of each multiplayer match via this API.

Headers

Name	Type	Description
api-key	String	We can add in an API Key in the headers for added authentication if you require us to.

Request body

Name	Type	Description
matchId*	String	matchId generated by you uniquely identifying this match.
scores*	String	Array of JSON objects, each containing: , ,

HTTP response codes

200: OK

You must respond with a 200 when you record winners successfully. Expected response body:

{
  "success": true,
  "scores": [
    {
      "rank": 1,
      "sub": "dhruv-123",
      "score": 10,
      "prize": 100,
      "currencyIcon": "https://example.com/icon.png"
    },
    {
      "rank": 2,
      "sub": "kamal-123",
      "score": 8,
      "prize": 100,
      "currencyIcon": "https://example.com/icon.png"
    },
    {
      "rank": 3,
      "sub": "shivam-123",
      "score": 5,
      "prize": 100,
      "currencyIcon": "https://example.com/icon.png"
    }
  ]
}

At the end of each match, we show a screen where the users of that match can see the final winners. If you have a prize amount that you're crediting the winners with, you can pass that as the prize value, along with an icon for your currency in the currencyIcon value. are optional. This is what the screen looks like:

We can also dispatch client-side callbacks for key events related to multiplayer matches. More on it here.