# Receive user scores

Our systems can send your users' scores to you in real-time. Our partners use scores for innovative use cases:

* Create leaderboards, and organise tournaments on your platform
* Give score targets to your users and reward them if they achieve scores

We can send user scores to you in 2 ways:

* [Via webhooks](#via-webhooks)
* [Via client-side broadcasts](#via-client-side-broadcasts)

***

### Via webhooks

You can get scores of your users in real-time providing us a POST API / webhook URL. Gamezop will push your users' scores to this API.

In order for this to work, you must also append a `sub` query parameter to the game `url` received in the All Games API.

For example: <https://3025.play.gamezop.com/g/NyM_JGWcx?sub=123-554-111>

The value of this `sub` param must be a unique user identifier for the user playing the game.  Max supported length of this value is **100 characters**. Scores are always scoped to a game and user identifier.

#### Your webhook endpoint

<mark style="color:green;">`POST`</mark> `https://api.publisher-xyz.com/games/score`

Gamezop posts user scores in real-time to your webhook

#### Headers

<table><thead><tr><th width="189.81640625">Name</th><th width="149.59375">Type</th><th>Description</th></tr></thead><tbody><tr><td>api-key</td><td>String</td><td>We can add in an API Key in the headers for added authentication if you require us to.</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK" %}
Upon receiving scores from us, you must respond with a 200 Status Code
{% endtab %}
{% endtabs %}

We will send a JSON object to your webhook when users' scores update. The data body will contain the following fields:

<table><thead><tr><th width="190.328125">Key</th><th>Description</th></tr></thead><tbody><tr><td><code>gameCode</code></td><td>Unique code assigned to each game — this is the <code>code</code> value received in the <a href="../types-of-integration/all-games-api">All Games API</a>.</td></tr><tr><td><code>sessionId</code></td><td>Unique session identifier generated by Gamezop — remains same throughout a session. A session ends when the game page is refreshed or reloaded.</td></tr><tr><td><code>gamePlayId</code></td><td>Unique game play identifier generated by Gamezop — remains same throughout a game play. There can be multiple game plays per session — each time the user loses the game, a new game play starts.</td></tr><tr><td><code>timestamp</code></td><td>Unix timestamp — denotes the exact time at which this score was made by the user.</td></tr><tr><td><code>score</code></td><td>Score made by the user.</td></tr><tr><td><code>leaderboardId</code></td><td><a data-footnote-ref href="#user-content-fn-1">The leaderboard within the game against which the score was recorded</a>.</td></tr><tr><td><code>subId</code></td><td>User identifier passed by you as <code>sub</code> parameter in the game URL.</td></tr><tr><td><code>country</code></td><td>The ISO 3166-2 country code for the country from which the user is playing the game.</td></tr><tr><td><code>duration</code></td><td>Total time spent in the game play so until the point of the webhook call (captured in milliseconds). When a new game play starts, this is reset to 0.</td></tr><tr><td><code>state</code></td><td><p>Denotes the state of game at the time the <code>score</code> was made. It can be one of the following values:<br></p><ul><li><strong>loaded</strong>: <code>score</code> is always 0 with this state - it just means that the game finished loading.</li><li><strong>start</strong>: This is fired at the start of every new game play. <code>score</code> and <code>duration</code> are 0 in this state update.</li><li><strong>playing</strong>: This state means that the game is being played by the user - as the user's score keeps changing, we keep sending them to your API</li><li><strong>over</strong>: The <code>score</code> received with this state value denotes the user's score when the game got over. Within the same session, a user can retry a game several times. This means that there may be several <code>over</code> states within the same session.</li><li><strong>levelup</strong>: In case of level-based games, this state denotes the completion of a level.</li></ul></td></tr></tbody></table>

***

### Via client-side broadcasts

Client-side callbacks can also be made for these score updates.

This is usually needed if you wish to use them to trigger custom UI elements. We could add your JS tags to games, or make broadcasts over a WebView bridge.

Please contact your Gamezop Account Manager to enable client-side broadcasts.

[^1]: **Do not confuse** this with a ranking of scores. The concept of leaderboards is explained [here](https://docs.platform.gamezop.com/publishers/gamezop/advanced/receive-scores/leaderboards-api) in detail.