npm package: @game8.io/sdk
Description: Game8.io HTML5 SDK
Author: Game8
Latest version: 1.1.1

[![npm](https://img.shields.io/npm/v/npm.svg)](https://nodejs.org/)
[![GitHub version](https://img.shields.io/badge/version-1.3.0-green.svg)](https://github.com/game8sdk/game8-html5/)
[![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/game8sdk/game8-html5/blob/master/LICENSE)

# Game8.io HTML5 SDK
This is the documentation of the "Game8.io HTML5 SDK" project.

Game8.io is the biggest collections of high quality, cross-platform games. We provide great games for your website within minutes!

Running into any issues? Check out the F.A.Q. within the Wiki of the github repository before mailing to <a href="support@game8.io" target="_blank">support@game8.io</a>

## Implementation
Implement the following snippet within your game or within the `<head>` section of your index.html. The `G8_OPTIONS` object is safe to obfuscate if needed. 

_Make sure that the SDK is loaded before your game starts or while your game is loaded for the best user experience. Not after, and especially not by clicking a button within the game, as then it will take too long for an advertisement to load; making the user wait. **Only load the SDK once!**_

```javascript
window["G8_OPTIONS"] = {
    "gameId": "[YOUR GAME ID HERE]",
    "onEvent": function(event) {
        switch (event.name) {
            case "SDK_READY":
                // When the SDK is ready.
                break;
            case "SDK_ERROR":
                // When the SDK has hit a critical error.
                break;
            case "SDK_GAME_START":
                // advertisement done, resume game logic and unmute audio
                break;
            case "SDK_GAME_PAUSE":
                // pause game logic / mute audio
                break;
            case "SDK_REWARDED_WATCH_COMPLETE":
                // this event is triggered when your user completely watched rewarded ad
                break;
        }
    },
};
(function(d, s, id) {
    var js, fjs = d.getElementsByTagName(s)[0];
    if (d.getElementById(id)) return;
    js = d.createElement(s);
    js.id = id;
    js.src = 'https://unpkg.com/@game8.io/sdk';
    fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'g8sdk'));
```

### Mandatory settings:
1. Make sure to add your game hash (`gameId`), which you can retrieve from your GAME8.io control panel.
2. Invoke a method to pause AND mute your game within the `SDK_GAME_PAUSE` event. Will be called every time a video advertisement is ready to play. It is important that the game is muted, as background audio through video advertisements is forbidden.
3. Invoke a method to resume your game within the `SDK_GAME_START` event. Will be called every time a video advertisement is done playing.

### Invoke an advertisement

Correct ad-placement is key for a higher revenue potential of your game. Before you submit, make sure that your game includes a **pre-roll** and **mid-rolls**:

**Pre-roll: an ad shown before the user starts playing the game.**<br/> 
What you basically want to do is display the pre-roll as fast as possible to the user, so they don’t have the time to change their minds and close the game.<br/>
_Best practice: placing the pre-roll on buttons in the loading/splash screen (Start, Play, Continue)._<br/>

**Mid-roll: an ad shown in between game sessions.**<br/>
Ideally placed on all non-gameplay buttons, to spread the chance that users will see ads.<br/>
_Best practice: placing the mid-rolls on each button in the Game Over/Win screen (Replay, Next, Menu)._<br/>

To get the most out of your game revenue and to maintain a user friendly experience, we ask you to keep these requirements in mind when deciding on the placement of the ads: 
* Ads only display upon user input, e.g. when clicking a button
* Ads display outside of the gameplay only, to not disrupt the game experience
* Game audio is muted when the ad is displayed
* The game pauses when the ad is displayed

Don’t worry about spamming users with ads by placing ad-calls on too many buttons: we regulate the ad-interval through the SDK, so users will only see an ad when the set time-frame has passed.  

Now, everything should be set up for you. All you need to do now in order monetize your game is to call `g8sdk.showAd()` at the appropriate time in your game. This showAd() call **should be behind a touchUp/mouseUp event** in order to work correctly on mobile and adhere by the ad rules. 

**Note**: Make sure to check if the `g8sdk` instance exists and the `showAd` method exists as well. In case the SDK script goes offline or when adblocker stops it for whatever reason. Its just good practice when it comes to using third-party solutions.

```javascript
nextButton.addEventListener('mouseUp', function () {
    if (typeof g8sdk !== 'undefined' && g8sdk.showAd !== 'undefined') {
         g8sdk.showAd();
    }
});
```
A lot of developers miss out on a lot of revenue by not calling so-called mid-roll advertisements. Do know that you can call the `g8sdk.showAd();` method as often as you want. We make sure its not possible to call too many ads after another in order to uphold a proper user experience and advertisement guidelines. 

### Rewarded Ads
Users can watch an in-game video and receive rewards (like in-game currency, premium content, extra lives and credits, etc) in return.

### Debugging
Games, which include the SDK, can be easily debugged by calling the following from a browser developer console:
```
g8sdk.openConsole();
```
This will open a tiny toolbar, which allows you to call fake advertisements, making the implementation much easier and reliable. Clear your localStorage to disable debugging.

## Options
The `G8_OPTIONS` object allows the following properties:

| Property | Description |
| --- | --- |
| gameId | our gameId which is unique for each one of your games; can be found at your GAME8.io account. |
| onEvent | The callback function can handle events from within the SDK. |

## Events
### SDK EVENTS
The SDK 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 SDK should gracefully fail, so this should not be needed.

| Event | Description |
| --- | --- |
| SDK_READY | When the SDK is ready. |
| SDK_ERROR | When the SDK has hit a critical error. |
| SDK_GAME_START | When the game should start. |
| SDK_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 EVENTS
The GAME8.io SDK 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. | 
| IMPRESSION | Fired when the impression URL has been pinged. |

## Running a game from a local server

To make development and testing easier, you can run your game from a local server.

To do this:

- Add the game draft using the Yandex Games Console.
- Configure the localhost server to serve content via SSL.
- Open the game draft by adding the `?game_url=https://localhost:8080` parameter.

> [!NOTE]
> For security reasons, only the `localhost` domain is supported in the `game_url` parameter.

### Setting up a local server

There are several ways to set up a local server. One of them is described below:

1. Install `npm` following the instructions on the [Node.JS](https://nodejs.org/en/) website. Using `npm`, install the `http-server` package:
	```
	> $ npm install -g http-server
	```
2. Navigate to the game directory and create a certificate and private key via `openssl`:
	```
	> $ cd path/to/game/
	> $ openssl genrsa 2048 > key.pem
	> $ openssl req -x509 -days 365 -new -key key.pem -out cert.pem
	# fill in the required information
	```
3. Run the game:
	```
	> $ http-server --ssl -c-1 -p 8080 -a 127.0.0.1
	Starting up http-server, serving ./ through https
	...
	Available on:
	https://127.0.0.1:8080
	Hit CTRL-C to stop the server
	```
4. Open the [https://localhost:8080](https://localhost:8080) page in your browser. When a security warning appears, click the confirmation button.

### Running the game

Open the game draft page in the browser and add a `?game_url=` parameter with the game address on the local server. For example, for a game with the `id`, the link will look like this:
```
https://ga8.io/game/test/{id}?game_url=https://localhost:8080
```

After the game launches on the local server, you can use all the SDK features from it.

# How to publish this package to npmjs?

For production environment, To release new version path: (Eg: from `v1.0.70` to `v1.0.71`)
```bash
npm version patch -m "Release %s"
git push origin main --follow-tags
```

For staging environment, using prerelease (Eg: from `v1.0.70` to `v1.0.71-0`)
```bash
npm version prerelease --preid=stag -m "Prerelease %s"
git push origin stag --follow-tags
```