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):
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
{
"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.
...
"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
:
...
"score": null
...
Now, when the next match starts, score will change from null
to 0
, causing an
infoUpdated
event to properly fire.
...
"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).
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:
- Overwolf Platform
- Overwolf Electron
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).
In order to subscribe to Game Data on ow-electron, simply call
app.overwolf.packages.gep.setRequiredFeatures(features);
Listen for new Game Events
To subscribe to new Game Events, you must add a listener to the relevant API Event. More specifically:
- Overwolf Platform
- Overwolf Electron
In order to subscribe to new Game Events on the Overwolf Platform,
simply add a listener to overwolf.games.events.onNewEvents
.
In order to subscribe to new Game Events on ow-electron, simply call:
app.overwolf.packages.gep.on('new-game-event', (e, gameId, ...args) => {
// your code here
});
Obtain current Game Info
To obtain the current Game Info, you must call the relevant API method. More specifically:
- Overwolf Platform
- Overwolf Electron
In order to obtain the current state of the Game Info on the Overwolf Platform,
simply add a listener to overwolf.games.events.getInfo()
.
In order to obtain the current state of the Game Info on ow-electron, simply call:
app.overwolf.packages.gep.getInfo(gameId);
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:
- Overwolf Platform
- Overwolf Electron
In order to subscribe to new Game Info updates the Overwolf Platform,
simply add a listener to overwolf.games.events.onInfoUpdates2
.
In order to subscribe to new Game Info updates on ow-electron, simply call:
app.overwolf.packages.gep.on('new-info-update', (e, gameId, ...args) => {
// your code here
});
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.