GameArter Basic SDK

At the very beginning, there is need to download and import SDK into the project.

Create new game project in projects section by pressing button "create a new project".

This is way you will get your project Id for inserting to GameArter SDK. Once you will make first configuration export (see further), you will get access to the system.

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

GameArter SDK may need target-platform based SDKs for option to communicate with platform-based services like authentization, UIs and other services. Download all necessary SDKs on basis of all platforms you want to release your game on.

Path: Assets → Import Package → Custom Package [HELP]

If your project contains current SDK, update changed files (except scripts you have adjusted (=GarterCallbacks) if possible).

GameArter SDK currently support builds for WebGL and Android.

If you do not have preferred platform in build options, be sure you have it installed.

At the very beginning, there is need to download and import SDK into the project.

By export described in previous point 2/10 (save the configuration) you sent game configuration to GameArter system. The game will run under the exported configuration. If you make a change in the GameARter_Initialize object, you must to make re-export.

Export is visible in project panel.

Rows / Buttons explanation:
• Version | exported project version (filled in Garter_Initialize object inside unity)
• Version State | project mode - testnet / production
• Interpreter | interpreter under which the project version runs
• Config status | Status of data state - concept / pending (= waiting for authorization by admins) / live (= in production)
• Files upload button | Opens environment for uploading game files
• Test the game button | Opens game in a new tab
• Remove button | Removes project version

Initialization of SDK is automatical from GameArter_Initialize object.

SDK in version 1.3 and above

Once SDK is initialized, it informs about this event by calling delegate event "SdkInitialized". In addition to "SdkInitialized", Basic SDK contains "SettingsButtonPressed" event yet. Listeners for these events must be added in the same scene as "GameArter_Initialize" object is inserted.

In fact, you can replicate function and prefab inserted in "Assets/GameArter/Examples/BasicSDK_mode" or use directly the example mlements.

There is need to move them to Hiearchy of same scene as GameArter_Initialize object

Showcase of GarterBasicCallbacks.cs

copy

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class GarterBasicCallbacks : MonoBehaviour {

	void Awake(){
		// ADD LISTENERS FOR EXTERNAL EVENTS
		Garter.I.AddExternalCbListener< GarterWWW >(Garter.ExternalListener.SdkInitialized, SdkInitialized);
		Garter.I.AddExternalCbListener< string >(Garter.ExternalListener.ExternalSettingsButtonPressed, SettingsButtonPressed);
		Garter.I.AddExternalCbListener< string >(Garter.ExternalListener.PossibleGameExit, PossibleGameExit);
		Garter.I.AddExternalCbListener< string >(Garter.ExternalListener.PWAState, ProgressiveWebAppState);

		// Dont destroy on load - variables and functions will be available in every scene
		DontDestroyOnLoad(transform.gameObject);
	}

	private void SdkInitialized(GarterWWW data){
		Debug.Log ("SDK initialized - Garter calls are available.");
		// set user data (nickname etc) and load game
	}

	private void SettingsButtonPressed(string emptyString = null){
		Debug.Log ("GARTER CALLBACK - open settings");
		// Called on pressing "Settings" button inserted in "GameArter_Features" prefab
		// visibility of this button is customizable via GameArter_Initialize
	}

	private void ProgressiveWebAppState(string state){
		// Install as app button visibility (See point 3.11).
		Debug.Log ("Progressive Web App State: "+state);
		if (state == "enabled") {
			// display button "install as app"
			buttonInstallAsApp.SetActive(true);
		} else if(state == "disabled"){
			// hide button "install as app"
			buttonInstallAsApp.SetActive(false);
		}
	}
}

SDK in version lower 1.3

Once SDK is initialized and all data and features available, SDK informs about it by calling SdkInitialized() function located in the class GarterBasicCallbacks (Assets/GameArter/BasicSDK_interaction/GarterBasicCallbacks.cs).

Once SDK is initialized, you can ask for SDK data. See the example below.

copy

public class GarterBasicCallbacks : MonoBehaviour {

	public void SdkInitialized(){
		Debug.Log ("SDK Initialized - all user's data and SDk features available");
		Debug.Log ("UserNick: " + Garter.I.UserNick());
		Debug.Log ("UserLanguage: " + Garter.I.UserLang());
		//... see point 3.4 for more options
	}

}

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

• 1

  User data

  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

  
  
  string userNick = Garter.I.UserNick(); // user's nickname
  string userLang = Garter.I.UserLang(); // default language a user has set on pacogames // ar, cs, de, en, es, fr, pl, pt, ru, tr
  string userCountry = Garter.I.UserCountry(); // country shortcut the user is connected from
  bool loggedUser = Garter.I.IsLoggedUser(); // returns true, if user is logged in
  Texture2d userImage = Garter.I.UserImage (); // returns user's profile img as a texture
  
  

  • List of languages
  • List of countries
• 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.
  string browserName = Garter.I.GetBrowserName();

  • List of Browsers

Ad types

• Interstitial ads = fullscreen ads (Available on Web, Android)
• Rewarded ads = interstitial ads with a reward for watching (Available on Web, Android)
• Banner ads = ad banner unit in certain place on the screen (Available on Android)

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

public class AdCallExample : MonoBehaviour {			
	Garter.I.RequestAd (adUnitId); // request an ad.			
}

// ServicesAdjustments.cs file
public void AdOpened(){
	CacheCurrentSettings (); // cache current state - game will be returned to this state after clossing an ad (=mute game)
	// mute the game sound
	AudioListener.volume = 0f;
	//set minimum timescale to improve ad performance
	float minimumTimeScale = Garter.I.GetMinimumTimeScale ();
	Time.timeScale = minimumTimeScale;
	if (minimumTimeScale == 0) {
		AudioListener.pause = true;
	}
	// display mouse pointer (unlock cursor)
	if (Cursor.lockState != CursorLockMode.None) {
		Cursor.lockState = CursorLockMode.None;
	}
	if (!Cursor.visible) {
		Cursor.visible = true;
	}
}

public class AdCallExample : MonoBehaviour {
	Garter.I.RequestAd (adUnitId, (state) => {
		if(state == "loaded"){
			// MUTE GAME
		} else if(state == "completed" || state == "failed"){
			// UNMUTE GAME
		} else {
			// ... do nothing
		}
	});
}

public class AdCallExample : MonoBehaviour {
	Garter.I.GetAdConf ((conf) => {
		SdkDebugger("Garter.I.GetAdConf ((conf) => {})", ("Next ad in "+conf.nextAdM.ToString()+"s. Minimum time between ads "+conf.meantimeM.ToString()+"s."), "returns ads configuration.");
			});
}

public class AdCallExample : MonoBehaviour {
			
	if(Garter.I.RewardedAdAvailability()){
		// display button / UI for requesting rewarded ad
	}

	// On rewarded ad request from user (e.g. pressing rewarded ad button)
	Garter.I.RequestAd(adUnitId, (state) =>
   {
	    if(state == "loaded"){
			// MUTE GAME
		} else if(state == "completed"){
			// UNMUTE GAME, RELEASE REWARD
			// HIDE BUTTON FOR REWARDED AD
		} else if(state == "failed"){
			// UNMUTE GAME
			// HIDE BUTTON FOR REWARDED AD
		} else {
			// ... do nothing
		}
	});
}

You can use any tool for tracking you want. Do not you know any? Here's example of few of them.

By default, GameArter has implemented and supports Google Analytics for websites with a bridge of caching game-side data events. All you need to do to activate it, is to insert your own Google Analytics tracking id to "Basic settings" tab of your project. This analytics tracks all gameplayer-based data as players, source of visits, time of playing and so on. These data can be extended by data in a form of events sent from a game, see Google analytics guide page. Some basic events as scene change and so on can be send to analytics automatically on basis of analytics configuration made in point "Game side SDK configuration".

Garter.I.AnalyticsEvent(string action, string category, string label, int value);

/*
where:
category, label, value are optional parameters
See more at: https://developers.google.com/analytics/devguides/collection/analyticsjs/events
*/

There's a possibility you require to run the game in individual game modes on certain websites 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 modes 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:
byte individualGameModeNumber = Garter.I.IndividualGameMode();

Because of other services around a game, fullscreen mode must be called over GameArterSDK. Attach following call to fullscreen button in your game (if your game has such button). If a game is already in fullscreen mode, fullscreen is cancelled by the call.
Garter.I.Fullcreen();
Fullscreen must be initialized on Pointer down event.(Event trigger).

SDK contains a solution for working with brands and making redirects (opening new tabs / windows). Branding and redirects must be made via SDK for two reasons:

• Displaying right brand

  SDK contains a multi-brand solution. In short, this feature allows to display all in-game logos on basis of a website the game is displayed on. Changes of outgoing links are also included. This feature is active for websites which promote games from GameArter system. With gameater promotion, there should be more gameplayes and higher incomes. Logos are downloaded at the beginning of the game.

• Opening pages from a game

  A browser pop-up blocker blocks all requests which are not initialized in a certain time from user's action. This applies for all JavaScript requests called from games. SDK contains a solution, which reduces the time between clicks and opens new tabs without hit of the pop-up blocker.

• Tracking redirects

  With our solution you will know about every made redirect. - From what logo, on what website, and how oftenly is being used.

2 Ways of implementation:

• Implementation via prefab

  Prefab Individual_logo in Prefabs folder (Assets/GameArter/Prefabs) - A solution for placing own logos containing redirect links into your game. Option Individual requires placing own 2d texture as a button image and a link the logo will redirect. All redirects are opened as a new tab. 1) this does not destroy user's experience and 2) sites like app store or google play do not support opening in iframes.

  If you want to have more individual logos in the scene, simply duplicate the object and change logos and links.



• Implementation via code: Use function Garter.I.OpenWebPage (string targetURL);
  
  This callmust be initialized on POINTER DOWN event. You can listen for this event via EVENT TRIGGER or via following code:
  copy

  
  
  	// where gameObject is your target object for listening
  	EventTrigger et = gameObject.AddComponent< EventTrigger > ();
  	EventTrigger.Entry entry = new EventTrigger.Entry ();
  	entry.eventID = EventTriggerType.PointerDown;
  	entry.callback.AddListener((data) => { OnPointerDownDelegate((PointerEventData)data); });
  	et.triggers.Add(entry);
  
  

SDK contains pre-created loading screen asset in GamePlayer design. Its purpose is to save time, if your game does not contain such screen yet. This screen can be used e.g. during loading maps and other assets.

• 1) Creating loading screen |
  Garter.I.CreateLoadingScreen (string assetName, texture assetImg, bool activeProgressBar);

  set activeProgressBar to false, if you do not want to send current time of progress to the loading screen. The bar will be hidden.

• 2) Updating loading screen | Garter.I.UpdateLoadingScreen (float progress);

  If you set activeProgressBar to "true" during creating the loading screen, this is a way you can send update to the progress bar by current state of progress. 0 = 0%, 100 = 100%

• 3) Removing loading screen | Garter.I.RemoveLoadingScreen ();

  Once the asset is loaded, remove loading screen by this call.

// insert this script to an object placed in scene Hiearchy
public class LoadingScreenExample : MonoBehaviour { 
	public Texture mapTexture = null; // public var for attaching texture
	int updateLimit = 1001; // for test
	
	public void LoadAssetScreen(){
		Garter.I.CreateLoadingScreen ("Loading map: Office", mapTexture, true); // create loading screen
		updateLimit = 0; // set progress of loading screen to 0
	}
	
	void Update(){
		updateLimit ++;
		if (updateLimit < 1000) {
			Garter.I.UpdateLoadingScreen (updateLimit / 10); // set current progress of loading
		} else if (updateLimit == 1000){
			Garter.I.RemoveLoadingScreen (); // asset loaded - remove loading screen
		}
	}
}

Every game contains many data-weight cutscenes, stories and animations which are displayed calmly only one time for the whole game. GSDK helps to reduce game filesizes by providing a story module — an option for downloading these stories from external storage only in a time when it’s required. Dynamic loading of game stories might be done via asset bundles or this SDK feature when the story is displayed in gameplayer above the game (like an ad).

• 1) Calling browser stories | Garter.I.RunStoryAnimation (int animationNumber);

  By calling this, the game is automatically muted (via ServicesAdjustment.cs) and the animation (story) launched. Be sure that animation of such number is available for your game.

• 2) Callback in the end of animation

  Once animation ends, there is a callback to ServicesAdjustment.cs file. By default, the game is unmuted via the class. You can find more about this class and its features in point 4 - Advanced features. If you customize behavior during opened modules from default behavior, be sure that sounds are muted for during story module (moduleName == "storywindow").

• 3) Setting / switching of stories

  Is being made in "More" section of configuration of the project

  

Requires GameArter_Features prefab. Settings alert allows to display and hide alert icon for settings button at the prefb.

Feature available since SDK version 2.2

GameArter SDK allows to installation of web games as Web Apps to user's device. Installation is possible to PC as well as mobile device.

Implementation

• NOTE: this feature is functional after submiting requests for publishing in GameArter.
• Icon of web app (displayed at user's screen of desktop / mobile) must be in .png format and in 2 dimensions - 192x192 & 512x512px. Name them "favicon-192.png" and "favicon-512.png" and attach to folder "_pwa". Upload this folder with other project files in "Files upload" section at GameArter panel.
• 1) External callback listener | Garter.I.AddExternalCbListener("PWAState", targetFunction);

  The listener is used for setting visibility of button "installing game as app". Design of the button is up to developer.

  copy

  
  Garter.I.AddExternalCbListener< string >(Garter.ExternalListener.PWAState, InstallAsAppButton);
  function InstallAsAppButton(state){
  	switch(state){
  		case "enabled":
  			// Display button
  		break;
  		case "disabled":
  			// hide button
  		break;
  	}
  }
  

  Button must be hidden in default.

• Next option, e.g. when a user comes to menu and there is not known state in the game →
  Get current state value | Garter.I.GetStatePWA()
  Returns "enabled" / "disabled". See point 1.
• 2) Request for instalation

  Request for adding game as app to user device is made by user's click at button "installing game as app". Returned state identifies about current state of installation. These states maz be sent to e.g. analytics for tracking click ratio.

  copy

  
  buttonAddAsApp.onclick = InstallGameAsApp;
  function InstallGameAsApp(){
  	Garter.I.InstallAsPWA< string > ((state) => {
  		switch(state){
  			case "rejected":
  				// request is rejected. Be sure the request is posted only if Garter.I.GetStatePWA() === "enabled".
  			break;
  			case "dismissed":
  				// user cancelled the request
  			break;
  			case "accepted":
  				// user accepted the request
  			break;
  			case "installed":
  				// game was succesfully installed as app
  			break;
  		}
  	});
  }
  

  Visibility change of button during these states is driven via listener for "PWAState", see point 1.

Via ServicesAdjustment.cs file there is possible to adjust running of a game in the time when the game is not active (There is active an ad or a browser module). By default, a game has same behaviour in both cases. If you are not interested to make a special action during thies events for your game, skip this section.

During active ad, a game must be muted. This is made automatically by following way. If you think, you can improve it, you can adjust inside ServicesAdjustment.cs file.

public void AdOpened(){
	CacheCurrentSettings (); // cache current state - game will be returned to this state after clossing an ad (=mute game)
	// by this way, the game is muted
	AudioListener.volume = 0f;
	float minimumTimeScale = Garter.I.GetMinimumTimeScale ();
	Time.timeScale = minimumTimeScale;
	if (minimumTimeScale == 0) {
		AudioListener.pause = true;
	}
	// mouse pointer
	if (Cursor.lockState != CursorLockMode.None) {
		Cursor.lockState = CursorLockMode.None;
	}
	if (!Cursor.visible) {
		Cursor.visible = true;
	}
}

You can customize game behaviour for every opened browser module - video / discussion / shop and so on. Set e.g. some background ambiente music. By default, during opened module, tha game has the same behaviour as during ad - all sounds are muted and minimum timeframe is set. You should keep minimum timeframe always. Music will not affected by it.

You can adjust the settings via ModuleWindowOpened(string moduleName) and ModuleWindowClosed(string name) functions. The function will be called everytime there will be a change. NOTE, it will be called everytime, that means, e.g. during switching between modules without closing the dock. From that reason, you cannot use the created function "CacheCurrentSettings()" everytime, but only for first time. Do not work with this, if you do not understand it.

Start your game. During ad calls, your game should be paused, without mouse. During opened modules, the game should be in the settings you set. (Paused and muted by default). Calls to analytics are visible in the console. If everything is right, you can build the project and go to the next section.