Skip to main content

Game Events Provider (GEP)

The Overwolf Game Events Provider (GEP) is a part of the Overwolf API and provides apps with Live Game Data for supported games. Game data consists of two different kinds of data, Game events (also known as Live Game events) and Game Info (also known as Game info events).

Overwolf Electron support

GEP for Overwolf Electron is currently being rolled out on a per game basis. Contact us if you want events for a game that isn't currently in the supported games list.

important

  1. Not all games are available in the PROD environment. For a list of games in the PROD and DEV environments, see Electron Games Support.

  2. All supported games that are not in the PROD environment, are in the DEV environment and are updated regularly.

  3. Connect your app to the DEV environment using the command line argument --owepm-packages-url=https://electronapi-qa.overwolf.com/packages.

  4. You must tell your DevRel once when you are ready to go live so that the game can be moved to PROD.

  5. After the game has been moved to PROD, you need to remove the command line argument --owepm-packages-url=https://electronapi-qa.overwolf.com/packages from your app.

Game events​

Game events are real-time events that occur during game play. When a specific change of state occurs during game play an event is triggered containing specif data about that event. Game events are not stored and you will need to have a listener configured to ensure that you catch them. Each supported game has a list of specific supported events.

Example Game Event
Player was just killed
{
  "name": "player_killed",
  "data": {
    "username": "TestUser"
  }
}

Game Info Updates​

Game info updates describes persistent game data which updates during game play. These messages are sent in real time and are stored in a dictionary which can be queried at any time using the specific game events API. In addition, info updates are triggered whenever the data of a relevant Game Info item changes.

Game info includes data such as player data, match data, and more. Each supported game has a list of specific supported game info.

Resetting Game Info Updates fields​

Resetting game info fields are important because info updates are only triggered when Game Info values change. This may lead to instances where game info could be outdated and therefore unreliable for detecting game state. The following example shows how its possible that game info may not be updated.

Game info reset example​

In games that keep score, the score Game Info field is set to 0 at the beginning of every match.

...
  "score": 0
...

It is possible that the player didn't increase his score by the time the match ended. This means that the player's score is still 0. As a result, when the next match starts and the score will be reset to 0, an [infoUpdated][#game-info-updates] will not be triggered. This results from a the score field not updating.

To ensure that an infoUpdated event is triggered, the score field will be set to an illegal, consistent, meaningless value. This way when the score field is reset to 0 at the start of the next match (indicating a change from the illegal value), the infoUpdated event will be triggered.

...
  "score": null
...

When the next match starts, the score will change from null to 0, triggering an info updates update.

...
  "score": 0
...

Working with Game Data​

For each supported game, there are GEP APIs that you can use in your app. Use the following utility APIs to assist in your implementation of Live Game Data in your app.

Game Features​

Often, many separate Game Events and Game Info items may exist, even though they all relate to the same general functionality (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). This grouping helps make more sense of game events/info that are typically used together. Game features contain all the game events/info that are related.

For example, the Game Feature's match. This may have many different game data items contained within:

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

You can use these as several different Events & Info Updates items individually or as a feature. Use the individual Game events/info when there may be situations where you don't want to have dependencies between events.

Set Required Features​

By default, the Overwolf GEP does not actually listen for any changes in the game. You will need to subscribe to Game Features in order for them to actually be triggered.

Registering to GEP has benefits that include:

  • Direct feedback for the app in terms of expected data (under some circumstances, some Game Features may become temporarily unavailable).
  • Only required Game Features get triggered.
  • GEP will not run in games where no app is using it.
note

You must set the required Game Features for your app before GEP beings to work. Ideally this should be as soon as the game launches.

Run order matters!

In some games, the longer it takes between starting the game and when GEP is registered, the greater the chances of data issues (for example, missing events, unreliable data, etc) occurring. 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.

To subscribe to Game Data, add the following to your app:

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.

To subscribe to new Game Events add the following to your app:

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.

To obtain the current state of the Game Info, add the following to your app:

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.

To subscribe to new Game Info updates, add the following to your app:

app.overwolf.packages.gep.on('new-info-update', (e, gameId, ...args) => {
  // your code here
});

Event Status​

Some events may occasionally 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 discrepancies/issues found with the events' data/reliability.

GEP is complex and is influenced by outside factors that are not under Overwolf's control, so events may become temporary unavailable. In order to mitigate this, you can use "Event Status Endpoints". These are public API endpoints supplied by Overwolf that detail 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. You can:

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

For more information, see Verifying events for your app.