Client-side callbacks

Use client-side callbacks from our multiplayer games for analytics, or for triggering custom UI elements.

We broadcast client events on the window via postMessage and on any method you provide in cta field while generating the roomDetails object.

All the data broadcasted is in the form of stringified JSON.

Events

Match found event

Trigger

This event is broadcasted when a player is matched with , and a countdown starts for the match to start.

Broadcast payload structure

{
  "event": "match_found",
  "gameCode": "game-code",
  "matchId": "match-id",
  "players": [
    "sub-1",
    "sub-2"
    ]
}

Payload notes

  • gameCode is the unique identifier for that game (you get this on the All Games API)

  • matchId is the identifier generated by your systems via the Create Match API

  • players is an array of the sub identifiers you pass while generating the roomDetails object. IDs of all players matched together are passed.

No match found event

Trigger

This event is broadcasted when a player completes the for finding , but the could not be found.

Broadcast payload structure

{
  "event": "match_not_found",
  "gameCode": "game-code"
}

Payload notes

  • gameCode is the unique identifier for that game (you get this on the All Games API)

Match start event

Trigger

This event is broadcasted when the user starts playing the match. This happens after opponents are found, and the match countdown has finished.

Broadcast payload structure

{
  "event": "match_start",
  "gameCode": "game-code",
  "matchId": "match-id",
  "players": [
    {
      "firstName":"user-name",
      "photo":"https://www.exammple.com/photos/user-1.png",
      "gzpId":"sub-id"
    },
     {
      "firstName":"user-name",
      "photo":"https://www.exammple.com/photos/user-1.png",
      "gzpId":"sub-id"
    }
  ]
}

Payload notes

  • gameCode is the unique identifier for that game (you get this on the All Games API)

  • matchId is the identifier generated by your systems via the Create Match API

  • players consists of an array of objects, each representing one of the players of that match. Within each object, firstName represents the user.name value from the roomDetails object that you configure. Similarly, photo in the broadcast represents the photo URL you pass for that user, and the gzpId value is the sub value you pass for that user.

Match playing event

Trigger

This event is triggered each time there is a score update for any of the players in the match. Let's say Alice and Bob are in a match, and Alice's score goes from 0 to 1, then our systems will dispatch a match_playing event on both clients, and not just on Alice's client.

Broadcast payload structure

{
  "event": "match_playing",
  "gameCode": "game-code",
  "matchId": "match-id",
  "players": [
    {
      "firstName":"user-name",
      "photo":"https://www.exammple.com/photos/user-1.png",
      "gzpId":"sub-id",
      "score": 10,
      "rank: 1
    },
     {
      "firstName":"user-name",
      "photo":"https://www.exammple.com/photos/user-1.png",
      "gzpId":"sub-id",
      "score": 10,
      "rank: 1
    }
  ]
}

Payload notes

  • All notes remain same as the match_start event above. We additionally send 2 more values for each players object: score and rank. These represent the latest score of the corresponding user, and their latest rank in the match.

Match over event

Trigger

This is broadcasted when a user is done with all their , but their opponent is still playing. In case of multiplayer games, one player may finish before another. For instance, if Alice has scored 100 and runs out of attempts, whereas Bob is still at score 90, Bob can continue playing as he still has a chance to beat Alice.

The broadcast is only made for the user that has run out of attempts, and is .

Broadcast payload structure

{
  "event": "match_over",
  "gameCode": "game-code",
  "players":  [
    {
      "firstName":"user-name",
      "photo":"https://www.exammple.com/photos/user-1.png",
      "gzpId":"sub-id",
      "score": 10,
      "rank: 1
    },
     {
      "firstName":"user-name",
      "photo":"https://www.exammple.com/photos/user-1.png",
      "gzpId":"sub-id",
      "score": 10,
      "rank: 1
    }
  ]
}

Payload notes

  • All notes remain same as the match_playing event above.

Match result event

Trigger

This event is triggered when the match is over for all players and the final results are known.

Note that in some cases, match_over and match_result may come together. Let's say Alice and Bob are playing. Alice is at score 100, and Bob is at 80. Bob runs out of attempts. Since Alice is already at a higher score, she automatically wins, even though she did not exhaust her attempts. This would trigger match_over and match_result events for both players.

Also note that match_result is broadcasted to all players in the match.

Broadcast payload structure

{
  "event": "match_result",
  "gameCode": "game-code",
  "players":  [
    {
      "firstName":"user-name",
      "photo":"https://www.exammple.com/photos/user-1.png",
      "gzpId":"sub-id",
      "score": 10,
      "rank: 1
    },
     {
      "firstName":"user-name",
      "photo":"https://www.exammple.com/photos/user-1.png",
      "gzpId":"sub-id",
      "score": 10,
      "rank: 1
    }
  ]
}

Payload notes

  • All notes remain same as the match_playing event above.

Navigate home event

Trigger

This event is broadcasted when the user taps on the option to "GO HOME" from within the game UI. You can receive this event in your app and navigate the user to your app's home screen / take any other action.

Broadcast payload structure

{
  "event": "go_home",
  "gameCode": "game-code"
}

Payload notes

  • gameCode is the unique identifier for that game (you get this on the All Games API)

These events above are specific to multiplayer experiences. We also broadcast events and game states in case of single-player experiences, details for which can be found here.

Last updated