Skip to main content

Live Game Data (GEP)

The Overwolf Game Events Provider (GEP) is a part of the Overwolf API, capable of providing Apps with Live Game Data as it changes within a supported game.

This is mainly done using the following two forms of Game Data (also sometimes confusingly referred to as Game Events):

Overwolf Electron support

GEP for ow-electron are currently being rolled out over time. If you would like to use events for any specific game, please let us know and we will adjust its rollout accordingly.

Game Events​

The simpler of the two, Game Events fire when a fleeting occurance of interest happens within the game. When relevant, they may also contain specific data, further describing the event.

Example Game Event
A player was just killed, with the username "TestUser"
{
  "name": "player_killed",
  "data": {
    "username": "TestUser"
  }
}

Game Info​

Game Info describes persistent game data, which updates as the game does. This can be anything from player data, to details of the current match, and more.

Game Info is stored in a dictionary, which can be obtained at any time using the API. On top of that, whenever a relevant Game Info item changes, an infoUpdated event is fired, containing the new Game Info data.

Game Info Resetting​

infoUpdated events only fire when the Game Info value changes. This means that, in some cases, they could become unreliable for detecting the right game states, since the game's new state may not have changed compared to what it was before.

Example Game Info cancellation

Assume that we have a score Game Info. This value is set to 0 at the beginning of every match.

A match just started, score was set to "0"
...
  "score": 0
...

Now, it could be possible that a match will end with the score still being set to 0. As a result, when the next match starts, the score will be set to 0, and will not fire an infoUpdated event.

To stop this from happening, Game Info resetting exists.

More specifically - when the data is "invalidated", it will be set to an illegal, consistent, meaningless value. That way, the next time that the data changes to a legal value, it will inherently be different from the former value, and an infoUpdated event will fire.

Example Game Info reset

To stop the issue from the last example from happening, when the match ends, we set score, and any other match-specific data, to null:

First match just ended, score is set to "null"
...
  "score": null
...

Now, when the next match starts, score will change from null to 0, causing an infoUpdated event to properly fire.

Second match just started, score is set to "0"
...
  "score": 0
...

Working with Game Data​

In order to streamline utilize the aforementioned concepts, we have created a few utility APIs, which every Overwolf GEP implementation is built around.

Game Features​

Often, many separate Game Events and Game Info items may exist, even though they all relate to the same general functionality (hence Feature) in the game.

When interacting with the Overwolf GEP API, Game Features will often be used instead of the individual Game Event/Game Info item names (for example, when setting the required Game Features)

Example Game Feature

For example, one game's match may have many different game data items:

  • Match settings
  • Match score
  • Match start/end events
  • Etc.

These would often make more sense as several different Game Events & Game Info items, to make sure that, for example, the currently selected map, does not behave as "updated" every single time that the score for one of the teams does.

However, the game data itself, does make much more sense when grouped, and is often used together. As such, match would be defined as a Game Feature when communicating with the Overwolf GEP, grouping within it the different Game Data it refers to.

Set Required Features​

By default, the Overwolf GEP does not actually listen for any changes in the game. Instead, different Game Features have to be specifically subscribed to, and only then will they actually work/fire.

This has a few perks:

  • Direct feedback for the App as to what it can expect in terms of data (under some circumstances, some Game Features may become temporarily unavailable).
  • Only required Game Features get fired.
  • GEP will not even need to run in games where no App is using it.

However, it does also mean that you must set the required Game Features for your App before GEP beings to work (ideally, as soon as the game itself launches).

Run order matters!

In some games, the longer it takes between starting the game and when GEP is registered, the higher the odds of data issues (missing events, unreliable data, etc) become*.
* This is especially critical if the App was started in the middle of a game session. It is recommended that you show a relevant indication to your users in those cases.

To set the required features, you must call the relevant API method. More specifically:

In order to subscribe to Game Data on the Overwolf Platform, simply call* overwolf.games.events.setRequiredFeatures().

* Do note that - as mentioned in the method's documentation - at least currently, this call may fail, even if the game was already started, and it should be retried several times until it succeeds (or runs out of attempts).

Listen for new Game Events​

To subscribe to new Game Events, you must add a listener to the relevant API Event. More specifically:

In order to subscribe to new Game Events on the Overwolf Platform, simply add a listener to overwolf.games.events.onNewEvents.

Obtain current Game Info​

To obtain the current Game Info, you must call the relevant API method. More specifically:

In order to obtain the current state of the Game Info on the Overwolf Platform, simply add a listener to overwolf.games.events.getInfo().

Listen for new Game Info updates​

To subscribe to new Game Info updates, you must add a listener to the relevant API Event. More specifically:

In order to subscribe to new Game Info updates the Overwolf Platform, simply add a listener to overwolf.games.events.onInfoUpdates2.

Event Status​

Some events may ocassionally become unavailable. This can be caused by several things:

  • Recent game update causing issues
  • A request by the relevant game studio to disable this event
  • Potential discrepencies/issues found with the events' data/reliability
  • Etc

Because the Overwolf GEP integration works across many moving parts like that, temporary unavailabilty is not a question of "if?", but rather of "when, and for how long?".

However, we have created several different mitigations for this, one of which is the "Event Status Endpoints". These are public API endpoints supplied by Overwolf, detailing the current uptime status of individual Game Features per game.

Using these endpoints, it is possible for your app to react in real time to the status of different events, be it:

  • Toggle specific app functionality
  • Toggle certain less reliable/desirable fallback logic
  • Provide users an indication of the potential issues

For more details, see Verifying events for your app.