Optional steps

Describes additional steps that you can use to customize your integration with the escs

ESCS ready callback

When you get the callback from EscsUnityPlugin.Invoke, this means that plugin is ready to work and can show UI. But this does not mean that you can already use every ESCS feature, as some components require more time to hook up. Most of the time you don't need to worry about it, but in some cases it is not what you want (e.g. your game loads from deep link and you want to show tournament/wager inside ESCS, so you might want to disable your game UI until ESCS is able to show full info). To remedy this problem, we provide additional callback:

    EscsUnityPlugin.SetEscsReadyCallback((success) => {
        Debug.Log("Escs is ready!");
    });

Receiving this callback means that ESCS is fully ready to receive and perform any supported actions.

Hiding ESCS button

Most of the time you will not want to show the ESCS button during the actual game, to not mess with the gameplay, for example user can accidentally touch it and almost full-screen webview will show up. To hide or show button you can use the following methods:

EscsUnityPlugin.HideEscsButton();
EscsUnityPlugin.ShowEscsButton();

Opening ESCS view programmatically

Sometimes you might prefer to implement you own customized button for opening escs in style of your game and with full control of its position. For such cases you can hide escs button altogether (like shown above) and open Escs with your own button using following method:

EscsUnityPlugin.OpenEscsView();

Notifications/Announcements

There are situations, when ESCS needs to show announcements or notifications - for example to promote your game's upcoming championship. ESCS will open its full WebView automatically to show notification's content, if it's needed. To be able to show these, not interrupting your gameplay and at the times that are not disruptive for the player, please call these methods:

   EscsUnityPlugin.MaybeShowNotifications();
   EscsUnityPlugin.MaybeShowAnnouncements();

There's internal logic in the plugin to decide whether it needs to show actual notification and announcement, but you should place these calls whenever you feel that interruption with ESCS WebView window is okay for user experience.

Please note that it does not mean that user will see notification or announcement every time you call these methods. We are trying for those to be as subtle and fluent as possible for end user. Their names imply that notification/announcement just maybe will be shown.

Changing the default button position

There are situations when it is not suitable for your UI to have our ESCS button at the default top center area. Then you can change that (remember, that user actually can drag the button anywhere on the screen he wants)

SetButtonDefaultPositionAbsolute() will set button position in absolute coordinates from left upper corner of the app.

   EscsUnityPlugin.SetButtonDefaultPositionAbsolute(float x, float y);

where

  • x - x coordinate

  • y - y coordinate

SetButtonDefaultPositionRelative() will set button position in relative coordinates from center horizontally and top vertically of the app. That is, if you set 0, 0 coordinates the button will be shown in the x: (device width)/2 y: 0.

The coordinate system here is from -0.5 to 0.5 for xPart : where -0.5 means most left side of device and 0.5 - right side and 0 is dead center. For yPart it is from 0 to 1 where 0 is top of the screen and 1 is the bottom.

  EscsUnityPlugin.SetButtonDefaultPositionRelative(float xPart, float yPart);

NOTE! Both these methods are setting default button position for only the first game start. You should call them immediately after calling Invoke (not in the initialization handler).

Getting in-game rewards

To receive the list of in-game rewards that particular player has (you can set those rewards as string fields in your game dashboard - for winning matches and so on) you can use the following method:

EscsUnityPlugin.GetIngameRewards(OnGetRewards);
//...
public void OnGetRewards(EscsIngameRewards rewards) {
    Debug.Log("onGetRewards callback");

    foreach(EscsRewardPayload p in rewards.data) {
        Debug.Log(p.rewardData);
    }
}

where:

  • OnGetRewards- callback delegate when GetIngameRewards has rewards info, with following signature:

public delegate void EscsGetIngameRewardsDelegate (EscsIngameRewards rewards);

where: EscsIngameRewards is object with follwing fields:

  • int count - amount of rewards

  • EscsRewardPayload[] data - array of EscsRewardPayload objects, which contain:

    • string id - id of the reward

    • string rewardData - reward data - the string that you set in the game dashboard

    • string tournamentId - tournament id where the reward was obtained

Multiplayer

Overview

We support multiplayer games with different types of matches, matchmaking and so on. To be able to use this feature, you need to follow these steps:

  • Implement several callbacks in you game, which will be called in response to player's engagement with multiplayer tournament

Currently we provide 4 such callbacks:

  • OnGameSetStart callback - is called when a game set is started by escs backend. We already described this one in the basic integration section.

What is a "set"?

Matches in a escs have a very flexible structure to accommodate all the possible needs. But think of them as of matches in tennis Grand Slam tournaments. So a match consists of one or more sets. And a set consists of one game between the match participants: the time between the game start or on OnGameSetStart callback and the call of the EndGame() method.

Now depending on the the game mode in your game, you might want to decide to let players actually play more then one game in a set - it is entirely your decision and you control it by deciding when to call the EndGame() method. For example, in a game of Tetris you could let players play just one game before calling the EndGame() method or you can let them play 3 games and call the EndGame() method after the 3rd game, sending to the escs the cumulated score of all 3 games. How do you let the players and tournament organizers know about these details? This is what the game mode is for. Read more about it here.

A game between players can be a multiplayer game or a single player game. It can be a real multiplayer (e.g. they, for example, race each other on track in a racing game or are participating in a deathmatch 1vs1 or 2vs2 and so on), or just a single player, meaning that they all play their own single player games (like solving puzzles and the one who solves it faster is the winner). In the OnGameSetStart callback you will receive information about players that are playing this set, teams that players are in (i.e. 2vs2 game), metadata that is supplied with the player (supplied by registerInGamePlayerId) and global metadata that is set in the game dashboard.

  • OnGameSetEnd callback - is called when each player in the set has finished their game. this might be not necessary the same moment you end your multiplayer game - it is called when the escs backend processed all game end events from each participating player and saved their corresponding scores. You will receive matchId and setId as parameters

  • OnMatchStart callback - is called when multiplayer match has started. Usually you will get this event right before getting OnGameSetStart. Each match consists of several game sets. You will receive matchId as parameter of this callback.

  • OnMatchEnd callback - is called when multiplayer match has ended. That is when all the sets in the match has been played or timeout occurred. You will receive matchId as parameter of this callback

The following diagram may be helpful for understanding about aforementioned events:

To utilize these events you should register in-game player id after the initializing escs service, as described in the basic integration. Just to have everything in one place you'll find below once again the description of registering the in-game player id and of the OnGameSetStart event callback.

Registering in-game player id and metadata:

EscsUnityPlugin.RegisterIngamePlayerId(playerId, ingameMetadata);

where:

  • playerId - your ingame player id (string). It will be passed along with OnGameSetStart callback when the game set will start

  • ingameMetadata - your ingame metadata for this player (string)

Setting player metadata to use in tournament settings:

EscsUnityPlugin.SetPlayerMeta(EscsPlayerParams[] quali, EscsPlayerParams[] generalParams, EscsSetPlayerMetaDelegate handler);

where:

  • quali - parameters for qualification

  • generalParams - general parameters for any tournament setting

  • handler - callback with results of setting the parameters; true means parameters were set successfully

Register OnGameSetStart event callback

EscsUnityPlugin.SetGameSetStartCallback(OnSetStart);
//...
public void OnSetStart(EscsSetStartPayload p) { 
    Debug.Log("set started - players: ");
    foreach(EscsTeam team in p.teams) {
        Debug.Log("team: ");
        foreach(EscsParticipant particip in team.members) {
            Debug.Log(particip.username);
        }
    }
}

where EscsSetStartPayload contains:

  • setId - setId of started set (string)

  • tournamentId - tournamentId of the set (string)

  • matchId - matchId of the set (string)

  • roundId - roundId of the set (this is in fact id of the set "results") (string)

  • globalMetadata - metadata string that can be set in the game dashboard (string)

  • setEndTimeUnix - game's set latest end time in unix time (int)

  • teams - array of EscsTeam objects. Each EscsTeam has array of EscsParticipant, which in turn contains:

    • playerId - escs player id (string)

    • ingamePlayerId - registered in-game player id via registerInGamePlayerId (string)

    • username - user's escs username (string)

    • firstName - user's escs first name (string)

    • lastName - user's escs last name (string)

    • avatar - user's escs avatar image url (string)

    • ingameMetadata - in-game metadata that was registered via RegisterInGamePlayerId (string)

    Thus, when playing, for example, 2vs2 game mode, you will have 2 EscsTeam objects in teams array, each containing 2 EscsParticipant. If playing 1vs1, then you will have 2 EscsTeam objects each holding just 1 EscsParticipant, i.e. 2 teams with 1 player only for each.

Register OnGameSetEnd event callback

EscsUnityPlugin.SetGameSetEndCallback(OnSetEnd);
// ...
public void OnSetEnd(string setId, string matchId) { 
    Dedug.Log("set ended: " + setId + "\n of match: " + matchId);
}

where:

  • setId - setId of finished set (string)

  • matchId - matchId of the set (string)

Register OnMatchStart event callback

EscsUnityPlugin.SetMatchStartCallback (OnMatchStart);
// ...
public void OnMatchStart(string matchId) { 
    Dedug.Log("match started: " + matchId);
}

where:

  • where matchId - is matchId of the match that started (string)

Register OnMatchEnd event callback

EscsUnityPlugin.SetMatchEndCallback (OnMatchEnd);
// ...
public void OnMatchEnd(string matchId) { 
    Dedug.Log("match ended: " + matchId);
}

where:

  • where matchId - is matchId of the match that has ended (string)

OAuth integration for fast user registration

  1. Create the oAuth app as described here: Using escs OAuth for sign in

  2. Implement the callback to send the access token to escs as described below.

Supporting user login using the game account (oAuth-like)

You can use our option for user game profile integration and allow your users to log in to our system without requiring them to manually create an escs account. Then the user will see an additional button "log in using %game_name% account" on the main escs screen. In order to support this, first, you need to follow the required steps in the client dashboard and set up the necessary fields as described in the corresponding docs section: Using escs OAuth for sign in. Note that you will also need to create an additional endpoint in your game's backend for the account system for verifying tokens. After this you will only need to implement one callback in your game: 

EscsUnityPlugin.SetGameUserProfilePermissionsCallback((permissions, respond) => {
    Debug.Log("Unity got permissions request with following options:");
    foreach( var x in permissions) Debug.Log( x.ToString());
    //...
    respond(testToken1, acceptedPermissionList);
});

where

  • permissions - list of requested profile permissions (string), for example ["email", "id"]

  • respond - a function that is used to respond to this profile permissions request; you may want to ask the user to accept the requested permissions list in a dialog, or allow them to select only some of them; such dialog, if any, you should create and present to the user by yourself; when the user responded to it, you can use respond function to send user's choices to escs:

    • testToken1 - user access token, which will be used by escs backend to obtain profile information from your game's backend (string)

    • acceptedPermissionList - here you supply permissions that the user accepted, if any (list of strings), i.e.: var acceptedPermissionList = new string[] {"grantedPermission1", "grantedPermission2"} the permission strings should correspond to those that you have received in the permissions list

Deeplink integration

Deeplink integration allows you to process ESCS-related deeplinks in your app. Other websites and apps can connect to the ESCS and drive users directly into your game via a deeplink. For the integration and seamless user experience this step is required and is highly recommended.

ESCS will generate deep links using provided url scheme and domain, i.e.: gamescheme://some/path/?escsplayer=%escs-specific-urlencoded-part%. This also could be your android app link/ios universal link. So when creating a link for tournaments/wagers inside your game, ESCS will just append the "?escsplayer=" parameter to the url you have entered in escs dev console in your app settings.

In the field you should enter something like gamescheme://some/path for simple deeplink or https://yourgame.com/some/path for app/universal link - where the some/path is any path inside your application that you can process. After this setup, you can use 

EscsUnityPlugin.FollowDeepLink(param)

method to pass the value of url parameter called "escsplayer" (%escs-specific-urlencoded-part% in the example above). You can provide it in urlencoded format, i.e. raw string that is passed in escsplayer param, escs will decode it correctly. How you extract the parameter value from the url is left to your game's implementation detail, but that should be fairly easy. You can get an example code of extracting the parameter in the SampleScenes/EscsDemoDeeplink.cs in our Unity plugin.

Note that you have to manually perform deeplink integration according to Unity platform that you chose as a target. Please refer to Unity docs: https://docs.unity3d.com/2022.3/Documentation/Manual/deep-linking.html

This will trigger escs service to process that deeplink and automatically show relevant info in our overlay. If the user decides to take action with shown info, your game will receive the data about the match it needs to create using our standard APIs described in previous sections (i.e. OnGameSetStart and other relevant callbacks) and no additional implementation is required

PreviousUnityNextJS

Last updated