Gamedistribution.com HTML5 API
This is the documentation of the "Gamedistribution.com HTML5 API" project.
Gamedistribution.com is the biggest broker of high quality, cross-platform games. We connect the best game developers to the biggest publishers.
Running into any issues? Check out the F.A.Q. within the Wiki of the github repository before mailing to support@gamedistribution.com
Implementation within games
The API should be integrated within HTML5 games by simple import as npm package OR loading it through our CDN. Specific information of the API features and usages can be found at the wiki.
ES5 Import
Import the npm package from https://www.npmjs.com/package/@gamedistribution.com/html5-sdk.
import GameDistribution from '@gamedistribution.com/html5-sdk';
CDN
Or add this script to your document.
<script src="//html5.api.gamedistribution.com/main.js"></script>
Legacy - Don't use this, only available for old implementations.
The index.html of this project contains a legacy integration example of the old HTML5 API.
<script src="//html5.api.gamedistribution.com/libs/gd/api.js"></script>
Debugging
Games, which include the API, can be easily debugged by calling the following from a browser developer console:
gdApi.openConsole();
The gdApi namespace is set when creating the api instance. We can't change the name of this namespace as it is still used within games using the old API implementation.
Repository
The API is maintained on a public github repository. https://github.com/GameDistribution/GD-HTML5
Deployment
Deployment of the API to production environments and npmjs.com is done through TeamCity. The npm package is published as ES5 for backward compatibility support using a prepublish Babel task defined within package.json, even though our repository uses ES6.
Installation for development
Install the following programs:
Pull in the rest of the requirements using npm:
npm install
Setup a local node server, watch changes and update your browser view automatically:
grunt
Make a production build for the CDN solution. The npmjs version uses a "prepublish"-task defined within package.json, which does a simple babel task, similar to this task:
grunt build
Events
API EVENTS
The API events should be used by developers to start or pause their game or handling critical errors. Unless the errors are ad related, then they could hook into the AD_ERROR event, however; the API should gracefully fail, so this should not be needed.
| Event | Description |
|---|---|
| API_READY | When the API is ready. |
| API_ERROR | When the API has hit a critical error. |
| API_GAME_DATA_READY | When game data is returned. |
| API_GAME_START | When the game should start. |
| API_GAME_PAUSE | When the game should pause. |
IMA SDK EVENTS
The SDK events are custom ads for handling any thing related to the IMA SDK itself.
| Event | Description |
|---|---|
| AD_SDK_LOADER_READY | When the adsLoader instance is ready to create an adsManager instance |
| AD_SDK_MANAGER_READY | When the adsManager instance is ready with ads. |
| AD_SDK_REQUEST_ADS | When new ads are requested. |
| AD_SDK_ERROR | When the SDK hits a critical error. |
| AD_SDK_FINISHED | When the SDK is finished running the ad. |
| AD_CANCELED | When the ad is cancelled or stopped because its done running an ad. |
| AD_SAFETY_TIMER | When the safety timer is cleared. We run this timer to make sure the SDK and ads do not stop us from starting the game after, whenever there is a weird error. |
AD EVENTS
The Gamedistribution.com API uses the IMA SDK for loading ads. All events of this SDK are also available to the developer. https://developers.google.com/interactive-media-ads/docs/sdks/html5/
| Event | Description |
|---|---|
| AD_ERROR | When the ad it self has an error. |
| AD_BREAK_READY | Fired when an ad rule or a VMAP ad break would have played if autoPlayAdBreaks is false. |
| AD_METADATA | Fired when an ads list is loaded. |
| ALL_ADS_COMPLETED | Fired when the ads manager is done playing all the ads. |
| CLICK | Fired when the ad is clicked. |
| COMPLETE | Fired when the ad completes playing. |
| CONTENT_PAUSE_REQUESTED | Fired when content should be paused. This usually happens right before an ad is about to cover the content. |
| CONTENT_RESUME_REQUESTED | Fired when content should be resumed. This usually happens when an ad finishes or collapses. |
| DURATION_CHANGE | Fired when the ad's duration changes. |
| FIRST_QUARTILE | Fired when the ad playhead crosses first quartile. |
| IMPRESSION | Fired when the impression URL has been pinged. |
| INTERACTION | Fired when an ad triggers the interaction callback. Ad interactions contain an interaction ID string in the ad data. |
| LINEAR_CHANGED | Fired when the displayed ad changes from linear to nonlinear, or vice versa. |
| LOADED | Fired when ad data is available. |
| LOG | Fired when a non-fatal error is encountered. The user need not take any action since the SDK will continue with the same or next ad playback depending on the error situation. |
| MIDPOINT | Fired when the ad playhead crosses midpoint. |
| PAUSED | Fired when the ad is paused. |
| RESUMED | Fired when the ad is resumed. |
| SKIPPABLE_STATE_CHANGED | Fired when the displayed ads skippable state is changed. |
| SKIPPED | Fired when the ad is skipped by the user. |
| STARTED | Fired when the ad starts playing. |
| THIRD_QUARTILE | Fired when the ad playhead crosses third quartile. |
| USER_CLOSE | Fired when the ad is closed by the user. |
| VOLUME_CHANGED | Fired when the ad volume has changed. |
| VOLUME_MUTED | Fired when the ad volume has been muted. |