Before you start

Every GameArter SDK mode is designed for specific user-cases. Basic SDK is the most simple SDK designed for very simple games or developers who are not interested in implementing advanced GameArter features to their games.

    Continue only if you meet following points:
  • The game does not contain user profiles.
  • The game does not save any user data on server.

Estimated time of SDK implementation: 30 minutes. Please, follow the guide carefully, it will save you from many future problems.

1. Getting started

At the very beginning, there is need to set basic project configuration.

1.1. Download SDK package

Download latest version of GameArter SDK Unity package from GameArter SDK for HTML5 Package section.

1.2. Import GameArter SDK package to the game project

Importing GameArter SDK allows full work with SDK in own index.html file (editor mode) running on address file:// directly in the pc.
Importing GameArter's SDK consist of placing .css and .js file to index.html file.
After uploading final version to server, the index.html file will be automatically replaced for full GameArter's GamePlayer.

Be sure, GameArter's .css and .js file do not affect any game javascript or css (Only reserved var is "Garter"). Right import of GameArter's SDK require to keep following structure of index.html file:

copy
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <!-- Editor GamePlayer for testing (it will be automatically replaced after upload to gamearter) -->
    <link rel="stylesheet" media="(min-width:480px)" href="https://www.gamearter.com/css/style-gp.css">
    <link rel="stylesheet" media="(max-width:480px)" href="https://www.gamearter.com/css/mobile-wrapper.css">
   
    <!-- GAME STYLES SPACE START-->
    // Space for game styles
    <!-- GAME STYLES SPACE END-->

</head>
<body>
    <main role="main" id="main" class="main" style="height:100%;padding-left:0">
        <div id="ga_game" style="height:100%;;position:relative">
                
            <!------- GAME BODY SPACE START --------->
            // Space for game body
            <!--------- GAME BODY SPACE END ---------->

        </div>
    </main>
    <footer role="contentinfo" class="footer-gp no-select">
        <img src="https://data.pacogames.com/gplayer/branding/gamearter-uni.png" alt="Pacogames" width="184" height="18">
        <a href="https://developers.gamearter.com/projects">Project Panel</a>  |  
        <a href="https://developers.gamearter.com/docs/html5/sdk-overview.php">SDK Documentation</a>
    </footer>    
</body>
<script src="https://www.gamearter.com/gameplayer/html5/gamearter-gameplayer.js"></script>
<script src="https://www.gamearter.com/gameplayer/html5/gamearter-instance.js"></script>

<!-- GAME SCRIPTS SPACE START -->
// Space for game scripts
<!-- GAME SCRIPTS SPACE END -->

</html>

You can modify your own index.html file or extend following player prefabs - desktop-gameplayer.html, mobile-gameplayer.html - about your game lines.

In production, GameArter automatically run desktop or mobile gameplayer on basis of targeted device. This allow to deliver the best possible experience for these devices.

1.3. Fixing possible errors

  • Game framework does not allow implementation of GameArter SDK by this way | Let us know your game framework / engine and we will make an extension of GameArter SDk for this framework / engine, if possible.
  • Broken styling | This maight be affected either by a clash in GameArter's style with game style. There may be also different default style settings for running from localhost and server.
  • No game displayed | Be sure that canvas (or game div) is displayed in visible area of screen. Game div must be inside GameArter's div element with id "ga_game".
  • Need a help?GameArter Slack: @adm_vladimir / email - [email protected] /

2. SDK configuration

Before a possibility to connect to the SDK, there is need to make a project configuration.

2.1. Create a project

Create new html5 game project in projects section of GameArter system.

This is way you will get your project Id for communication with GameArter SDK.

2.2. Project configuration

Create a configuration for selected project version. You can have up to 5 versions of every project. (Only 1 version can be live, the other 4 serves for development purposes or AB testing).

gamearter sdk for html5 - project configuration - basic mode

  • 1

    Documentation

    A button opening knowledge base you are currently on.
  • 2

    Project ID

    Every game must have its unique project ID. Project ID is a signature of the game with which it accesses, the game has access to GameaArter features.
  • 3

    Project Ver

    Selected project version you are configurating
  • 4

    SDK mode

    The mode, under which the SDK will run. Select Basic.

Remember you projectId and Project Ver for next steps. Once done, save the basic configuration by pressing "Save configuration"

2.3. Services configuration

Services configuration is for files management, project versions management and adjusting data filled in the project configuration and for adding additinal SDK features in higher modes of GameArter SDK.

Result image
    Rows / Buttons explanation:
  • Version ID | project version
  • Last modified | Last modification in the version configuration
  • Version State | project mode - testnet / production
  • Interpreter | interpreter under which the project version runs
  • Config status | Status of data state - draft / pending (= waiting for authorization by admins) / live (= approved,in production)
  • Export conf buttonn | Opens project configuration (panel 2.2)
  • More button | Opens configuraion of additional features
  • Files upload button | Opens environment for uploading game files
  • Test the game button | Opens game in a new tab
  • Remove button | Removes project version

3. Working with SDK

3.1. SDK initialization

For possibility to connect and use GameArter SDK, there is need to create a new GameArter SDK instance.

copy

var GameArterSdk = new GamearterInstance({
    projectId:0, // Insert your project id here 
    projectVersion:1, // Insert your project version here
    sdkMode:"B", // Use SDK in Basic mode
    sdkVersion:"2.0" // use SDK ver 2.0
}, function(err){ if(err) console.error(err); } );

Callback function (attribute 2) is optional parameter via which you can be informed about errors occured during SDK initialization (e.g. SDK is already initialized, different projectId than expected projectId ... ).

During initialization, by adding other parametres there is possible to adjust SDK behavior. Following table display other options:

System options

key value default value description
notifications boolean true Displayes notification related to SDK ("Loading data", "saving data", "Badge XY received" ...) in top left corner.

editor options

key value default value description
debug boolean true Prints additional informations to console
prerollAd boolean false Activates preroll ad
minAdTime num [miliseconds] 1000 Sets minimum time between ads to GameArter's ad manager. (1000 = 1s)

Example of creating SDK instance with additional options:

copy

var GameArterSdk = new GamearterInstance({
    projectId:0, // Insert your project id here 
    projectVersion:1, // Insert your project version here
    sdkMode:"B", // Use SDK in Basic mode
    sdkVersion:"2.0", // use SDK ver 2.0
    notifications: true, // enable SDK notification
    developmentMode: {
        debug: false, // do not print to console
        prerollAd: true, //  display preroll ad
        minAdTime: 60000 // set minimum time between ads at 1 minute
    }
}, function(err){ if(err) console.error(err); } );

At the example above, SDK functions are available on path GameArterSdk.I. ... . Rest of the documentation will work with GameArterSdk as the var of GameArter instance.

3.2. SDK Listeners installation

In general, listeners are processed by callback function of calls made to the SDK. This sections is related to listeners for external events like SDK initialization or rewards to player (defined on server, not in the game).

Installation of listeners
GameArterSdk.I.AddExternalCbListener(A, B, C );

    where:
  • A: Event the listener is set for
  • B: Function into which is sent information once the event occur
  • C: Callback function informing about success / fail (optional)

Available external listeners

eventKey attribute value description
SdkInitialized - It is called once GameArter SDK is fully initialized (all calls and services are available)
PossibleGameExit - It's called when SDK recognizes risk of escaping the game (e.g. closing page tab). This may be last opportunity to save game porgress.
PWAState - Progressive Web App state. It's called when progressive web app state is being changed. -> enabled = display install game as app button | -> disabled = hide install game as app button. Button install game as app must be hidden in default. See more in section 3.15 - Game as App.

Example of listeners installation for external SDK events

copy

// Listeners
GameArterSdk.I.AddExternalCbListener("SdkInitialized", _GameArterSdkInitialized, function(err,res){ console.log(err,res); });
GameArterSdk.I.AddExternalCbListener("PossibleGameExit", _PossibleGameExit, function(err,res){ console.log(err,res); });
GameArterSdk.I.AddExternalCbListener("PWAState", _PwaState, function(err,res){ console.log(err,res); });
// Listeners functions 
function _PossibleGameExit(){ console.log("_PossibleGameExit: ", state); }
function _GameArterSdkInitialized(){ console.log("--- SDK INITIALIZED !!! -→ load the game ---"); }
function _PwaState(state){ console.log("PWA:",state); }

NOTE: From security reasons, GameArterSdk must be used within a scope (e.g. in function, class, or prototype) to prevent its global accessability.

Possible start implementation:

  1. Screen / box "Loading"
  2. Wait for "SdkInitialized" event.
  3. Set game - data, UI...
  4. Remove "Loading screen (point 1) and let a user play"

3.3. Accessing SDK data

  • 1

    Individual Game Mode

    There's a possibility you require to run the game in individual game mode on certain website or e.g. for testing. By using individual game mode features, you can set individual mode the game will run in for every website the game is published on. SDK will return you after its initialization number of mode which you will assign to a certain website. Then, you can simply set data with which the game should run according the mode number.

    Get mode number under which the game should run:
    var individualGameModeNumber = GameArterSdk.I.IndividualGameMode();

  • 2

    Browser name

    WebGL games have often different performance in various browsers. With knowledge of a browser a game is running in, there is a possibility for optimization of disabling features for certain browsers. E.g. car destructions for Chrome.
    var browserName = GameArterSdk.I.GetBrowserName();

3.4. Getting user info

On SDK initialized state, you can start any interaction with SDK.

GameArter has implemented auto-login and auto-authentication system. There is always returned a user identity even when a game does not use login system.

copy

var userNick = GameArterSdk.I.UserNick(); // user's nickname or Guest#randomNumber
var userLang = GameArterSdk.I.UserLang(); // default language a user has set on pacogames // ar, cs, de, en, es, fr, pl, pt, ru, tr
var userCountry = GameArterSdk.I.UserCountry(); // country shortcut the user is connected from
var loggedUser = GameArterSdk.I.IsLoggedUser(); // returns true, if user is logged in
var userImageUrl = GameArterSdk.I.UserImage (); // returns user's profile img as a texture () [1]);
var userRankName = GameArterSdk.I.UserRankName(); // returns profile rank of a user

3.5. Ads

Available ad types
  • Fullscreen midroll ads (= Interstitial ads)
  • Rewarded ads (= Fullscreen ads with a reward for watching)

Ad types can be combined in a game (One game can use both types of ads)

Fullscreen ad

Ad rules
  • Call ads only in suitable places. Ads cannot affect best user experience (UX) from playing games
  • Call ads in any suitable place for ad
  • Game sounds MUST be muted during an ad
  • Any exhortation or rewards for interacting with ads is prohibited

What is happening after an ad call:
  1. ad request is received in GameArter Ads manager.
  2. GameArter Ads manager checks availability of ads and processes ad-frequency-check.
  3. Ad state is returned by callback function.

Ad request
copy
GameArterSdk.I.CallAd("midroll",function(adState){
	switch(adState){
		case "loaded":
			// mute game
		break;
		case "completed":
			// unmute game
		break;
		default:
			// all other ad statuses provided by ad provider (e.g. "started")
			// these statuses have informatic character only.
	}
});

Ads in loop
Automatical ads in loop were removed from the system. There may be further managed manually by creating own interval for displaying ads. Minimum ad time between ads (for setting to the interval) is available at request GameArterSdk.I.GetAdMinMeantime().

Best practices:
  • First ad call from the start of the game. An ad at the beginning of the game does most of the income (the highest number of views). GameArter ad manager works with 2 types of preroll ads. In a case, that a website does not have own preroll, GameArter ad manager displayes an preroll ad on a load of gameplayer. In such case, first ad call from game is ignored. If no preroll on load of gameplayer is displayed (because it is not possible or is disabled), an ad on first ad call is displayed (= replacement of the preroll ad). From that reason, insert first ad call always at the beginning of the game.

Ad configuration for individual websites where the game is published is visible in Reports section after release of the game. There you can find out preroll ad type, frequency of ads, maximum length of ads, ad providers and so on. GameArter uses a mix of ad providers including own ads due to cover all websites restrictions (mainly policies for displaying Google Ads and ads.txt standard) and for achieving the best possible CPM. If you would like to make a change in default settings for a certain website or your game, contact GameArter support.

Rewarded ad

Availability of a rewarded ad is individual based on user's behaviour. Display button / option to launch rewarded ad only if the rewarded ad is available.

Callback states

  • ignored = ad request has been ignored. Probably due to no ad (be sure you check ad availability before requests!)
  • loaded = Rewarded ad has been loaded. Game sounts must be muted
  • completed = An ad has been succesfully completed. Release reward + unmute sounds
  • failed = something went wrong - user canceled the ad unmute sounds without reward

Implementation

copy

if(GameArterSdk.I.RewardedAdAvailability()){
	// display button / UI for requesting rewarded ad
}

// On rewarded ad request from user (e.g. pressing rewarded ad button)
GameArterSdk.I.CallAd("rewarded",function(adState){
	switch(adState){
		case "loaded":
			// mute game
		break;
		case "completed":
			// release reward
			// unmute game
		break;
		case "failed":
			// unmute game
		break;
		default:
			// all other ad statuses provided by ad provider (e.g. "started")
			// these statuses have informatic character only.
	}
});