Android native

escs
Search…
escs
Introduction
Plugins
Android native
How to integrate the android native plugin.
You can use this plugin for all android games.
Connecting plugin to your project.
Add escs repository  in top level build.gradle:
1
allprojects {
2
    repositories {
3
    //...
4
    maven {
5
        url  "https://escs.bintray.com/escs-android-plugin"
6
    }
7
    //...
8
    }
9
}
Copied!
just add this line to your app module build.gradle dependencies and sync:
1
dependencies {
2
    //...
3
    implementation 'io.escs.android:escs-android-plugin:0.11'
4
    //...
5
}
Copied!
Now you are ready to use android plugin
Integrating plugin into your game.
It is very easy to integrate ESCS plugin into your game code
First you need to initialize your plugin. 
Initialization
To start using your plugin you need first initialize it:
Kotlin
Java
1
        EscsService.invokeManaged(
2
            EscsServiceConfig(
3
                public_key,        // String
4
                base_url,          // String
5
                player_base_url    // String 
6
            ), 
7
            applicationContext,    // Context,
8
            invokeCallback         // (status: String, 
9
                                   //     gameId: String, 
10
                                   //         tournamentId: String) -> Unit
11
        ) -> Unit
Copied!
1
EscsService.INSTANCE.invokeManaged(
2
    new EscsServiceConfig(
3
        public_key, //String
4
        base_url, //String
5
        player_base_url //String
6
    ), 
7
    getApplicationContext(),
8
    (status, gameId, tournamentId) -> {
9
                        //... process result
10
                        return Unit.INSTANCE;
11
                    }
12
);
Copied!
where: 
public_key- a key that you've obtained in the step 1 of the integration guide, like "fee91a27-2b87-45f8-8ca4-0b317707806q"
base_url - url for the core ESCS service. It is https://api.escs.io for production environment
player_base_url - url for the player's ESCS service. It is https://player.escs.io for production environment
invokeCallback- callback when init is completed; you can omit it. 
Callback lambda parameters are following:
status  - string "initialized" for fully initialized escs, or some error message, or empty string
gameId - gameId string of configured game or empty string
tournamentId - tournamentId string of current active tournament or empty string
Then you need to attach UI components into your activity (the button and the webview):
Kotlin
Java
1
val viewGroup =
2
    window.decorView.findViewById(android.R.id.content) as ViewGroup
3
​
4
val btn = EscsButton(layoutInflater, viewGroup, applicationContext)
5
btn.attach()
6
​
7
val wv = EscsWebView(layoutInflater, viewGroup, applicationContext)
8
wv.attach()
Copied!
1
ViewGroup viewGroup = getWindow()
2
                        .getDecorView()
3
                        .findViewById(android.R.id.content);
4
​
5
EscsWebView escsWebView = new EscsWebView(getLayoutInflater(), 
6
                        viewGroup, 
7
                        getApplicationContext());
8
            
9
escsWebView.attach();
10
​
11
EscsButton escsButton = new EscsButton(getLayoutInflater(), 
12
                        viewGroup, 
13
                        getApplicationContext());
14
escsButton.attach();
Copied!
Don't forget to clean up on destroying your activity:
Kotlin
Java
1
override fun onDestroy() {
2
    btn.detach()
3
    wv.detach()
4
    EscsService.finish()
5
    super.onDestroy()
6
}
Copied!
1
escsWebView.detach();
2
escsButton.detach();
3
EscsService.INSTANCE.finish();
Copied!
Start/End Game
After that you are all set and ready to use ESCS functionality. To start a game's round, just call startGame() method:
Kotlin
Java
1
EscsService.startGame { 
2
  // process start round callback
3
  Log.i("MyGame", it?.toString() ?: "no round received")
4
} 
5
​
Copied!
1
EscsService.INSTANCE.startGame(round -> {
2
    Log.i("MyGame", round != null ? round.toString() : "no round received");
3
    return Unit.INSTANCE;
4
});
Copied!
where 
round - class instance with following fields:
_id  - roundId of just started game round
tournamentId- tournamentId of active tournament for which the round was created for
status- round status. "active" for just created round
playerId- escs playerId
When the round of your game has ended, just call  endGame() with score parameter:
Kotlin
Java
1
EscsService.endGame( Score(147.0) ) { //Score takes double as parameter
2
    Log.i("MyGame", it?.toString() ?: "no round received")
3
}
Copied!
1
//score takes double as parameter
2
EscsService.INSTANCE.endGame(new Score(147.0), round -> { 
3
    Log.i("MyGame", round != null ? round.toString() : "no round received");
4
    return Unit.INSTANCE;
5
});
Copied!
where 
score - game score parameter of double type
round - class instance with following fields:
_id  - roundId of just ended game round
tournamentId- tournamentId of active tournament for which the round was ended 
status- round status. "ended" for just ended round
playerId- escs playerId
Optional steps
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 following methods:
Kotlin
Java
1
escsButton.setVisible(View.GONE)
2
escsButton.setVisible(View.VISIBLE)
Copied!
1
escsButton.setVisible(View.GONE);
2
escsButton.setVisible(View.VISIBLE);
Copied!
Notifications/Announcements
There are situations, when ESCS needs to show announcements or notifications - for example to promote your game's upcoming championship, or ask user to add credit card, because his/her trial is about to expire. 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 interruptive for user, please call these methods:
Kotlin
Java
1
EscsService.maybeShowNotifications()
2
EscsService.maybeShowAnnouncements()
Copied!
1
EscsService.INSTANCE.maybeShowNotifications();
2
EscsService.INSTANCE.maybeShowAnnouncements();
Copied!
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 default button position
There are situations when it is not suitable for your UI to have our ESCS button at  default top center area. Then you can change that (remember, that user actually can drag the button anywhere on the screen he wants)
setDefaultPositionAbsolute() will set button position in absolute coordinates from left upper corner of the app.
Kotlin
Java
1
btn.setDefaultPositionAbsolute(50f, //x
2
                                50f) //y
Copied!
1
escsButton.setDefaultPositionAbsolute(50f,  //x
2
                                      50f); //y
Copied!
where
x - x coordinate
y - y coordinate
setDefaultPositionRelative() 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.
Kotlin
Java
1
btn.setDefaultPositionRelative(0.5f, //xPart
2
                               0.5f) //yPart
Copied!
1
escsButton.setDefaultPositionRelative(0.5f,  //xPart
2
                                      0.5f); //yPart
Copied!
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:
Kotlin
Java
1
EscsService.getInGameRewards {
2
    Log.i("ESCS", "rewards: ${it.data.foldIndexed("") { index, acc, rewardPayload -> "${acc}\n ${index.toString()} ${rewardPayload?.rewardData}" }}");
3
}
Copied!
where argument in the lambda is object of type InGameRewards: 
count - amount of rewards player has (integer)
data - list of RewardPayload objects:
_id - id of reward (string)
rewardData - string representation of rewards (which you set in the dashboard)
tournamentId - id of tournament it was received by player (string)
1
EscsService.INSTANCE.getInGameRewards(rewards -> {
2
            Log.i("ESCS", "rewards " + (rewards != null ? rewards.toString() : " no rewards received"));
3
        });
Copied!
where argument in the lambda is object of type InGameRewards:
getCount() - amount of rewards player has (integer)
getData() - list of RewardPayload objects:
get_id() - id of reward (string)
getRewardData() - string representation of rewards (which you set in the dashboard)
getTournamentId() - id of tournament it was received by player (string)
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: 
Create multiplayer tournament in the game dashboard
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. This is moment when you should start your game or create lobby and await for players to join it. What is a "set"? It's just one multiplayer game that several players are playing simultaneously. It can be 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 even "singleplayer", meaning that they all play their own singleplayer game (like solving puzzles and the one who solves it faster is the winner). In this 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 can call methods described below.
Registering in-game player id and metadata:
Kotlin
Java
1
EscsService.registerInGamePlayerId(playerId, playerMetadata)
Copied!
1
EscsService.INSTANCE.registerInGamePlayerId(playerId, ingameMetadata);
Copied!
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)
Minimal multiplayer setup
In order to create minimal trivial multiplayer setup, you will just need to register OnGameSetStart event. Starting a game in response to this event and it's parameters is enough to use multiplayer features of escs.
Register OnGameSetStart event callback
Kotlin
Java
1
EscsService.registerGameSetStartCallback { data ->
2
    Log.i("ESCS", "Set started: ${data.setId}, round: ${data.roundId}, players: ${data.participants[0][0].username} ${data.participants[1][0].username}")
3
}
Copied!
where data is GameSetStartData object:
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)
pariticipants - list of lists of Participant. Each sub-list is considered a "team". So if the game is 2vs2, then you will get list of 2 lists, each having 2 objects inside. Those 2 lists are 2 lists with 2 players each. In case of 1vs1 game, you will receive a list of 2 lists, each having 1 object inside - thus the team contains only one player. Participant object consists of:
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)
1
EscsService.INSTANCE.registerGameSetStartCallback(gameSetStartData -> {
2
    Log.i("ESCS", "gameSetStartData " + (gameSetStartData != null ? gameSetStartData.toString() : " no gameSetStartData received"));
3
    return Unit.INSTANCE;
4
});
Copied!
where data is GameSetStartData object:
getSetId() - setId of started set (string)
getTournamentId() - tournamentId of the set (string)
getMatchId() - matchId of the set (string)
getRoundId() - roundId of the set (this is in fact id of the set "results") (string)
getGlobalMetadata() - metadata string that can be set in the game dashboard (string)
getPariticipants() - list of lists of Participant. Each sub-list is considered a "team". So if the game is 2vs2, then you will get list of 2 lists, each having 2 objects inside. Those 2 lists are 2 lists with 2 players each. In case of 1vs1 game, you will receive a list of 2 lists, each having 1 object inside - thus the team contains only one player. Participant object consists of:
getPlayerId() - escs player id (string)
getIngamePlayerId() - registered in-game player id via registerInGamePlayerId (string)
getUsername() - user's escs username (string)
getFirstName() - user's escs first name (string)
getLastName() - user's escs last name (string)
getAvatar() - user's escs avatar image url (string)
getIngameMetadata() - in-game metadata that was registered via registerInGamePlayerId (string)
Register OnGameSetEnd event callback
Kotlin
Java
1
EscsService.registerGameSetEndCallback {
2
    Log.i("ESCS", "Set ended: ${it.setId} of match ${it.matchId}" )
3
}
Copied!
where argument of lambda is GameSetEndData object: 
setId - setId of finished set (string)
matchId - matchId of the set (string)
1
EscsService.INSTANCE.registerGameSetEndCallback(gameSetEndData -> {
2
  Log.i("ESCS", "gameSetEndData " + (gameSetEndData != null ? gameSetEndData.toString() : " no gameSetEndData received"));
3
  return Unit.INSTANCE;
4
});
Copied!
where argument of lambda is GameSetEndData object: 
getSetId() - setId of finished set (string)
getMatchId() - matchId of the set (string)
Register OnMatchStart event callback
Kotlin
Java
1
EscsService.registerMatchStartCallback {
2
    Log.i("ESCS", "Match started: ${it.matchId}" )
3
}
Copied!
where argument of lambda is GameMatchStartData object:
matchId - is matchId of the match that started (string)
1
EscsService.INSTANCE.registerMatchStartCallback(matchStartData -> {
2
    Log.i("ESCS", "matchStartData " + (matchStartData != null ? matchStartData.toString() : " no matchStartData received"));
3
    return Unit.INSTANCE;
4
});
Copied!
where argument of lambda is GameMatchStartData object:
getMatchId() - is matchId of the match that started (string)
Register OnMatchEnd event callback
Kotlin
Java
1
EscsService.registerMatchEndCallback {
2
    Log.i("ESCS", "Match ended: ${it.matchId}" )
3
}
Copied!
where argument of lambda is GameMatchStartData object:
matchId - is matchId of the match that just ended(string)
1
EscsService.INSTANCE.registerMatchEndCallback(matchEndData -> {
2
    Log.i("ESCS", "matchEndData " + (matchEndData != null ? matchEndData.toString() : " no matchEndData received"));
3
    return Unit.INSTANCE;
4
});
Copied!
where argument of lambda is GameMatchStartData object:
getMatchId() - is matchId of the match that just ended(string)
​