Generate a secret key and save it like shown below.
Remember your public key and secret key. You will need them later.
Add a payment method to your account. Take a look below.
Step 2 - oAuth preparations
Login with your credentials from the client.escs.io to the account.escs.io and create and oAuth app, choosing ESCS as an oAuth provider like shown below.
Step 3 - API integration flow
The API endpoints
For the integration you will need following API endpoints from the ESCS:
Let your users select a game, game mode and score type.
In general it is up to you how you present this part to your users – via the corresponding API endpoints ESCS provides you the catalog of games, game modes and scores. You can design the front-end part completely on your own or use some of the ESCS templates.
Getting a list of games.
To get the list of the available games call this endpoint.
https://api.escs.io/rpc/GetGames
Use the following parameters.
export type RpcRequest<HandleInputDTO>;
export interface HandleInputDTO {
context: AuthServiceContext;
filters?: HandleInputDTOFilters;
}
export interface HandleInputDTOFilters {
offset?: number;
limit?: number;
}
export type AuthServiceContext = {
type: AuthServiceContextTypeEnum.BY_GAME_SECRET_KEY;
gameId: ObjectIdLike; //your game id from the Step 1
secretKey: string; // your secret key from the Step 1
};
export const enum AuthServiceContextTypeEnum {
BY_GAME_SECRET_KEY = 'BY_GAME_SECRET_KEY'
}
As a response you are getting a list of games.
export type RpcResponse<HandleOutputDTO>;
export interface HandleOutputDTO {
count: number;
limit?: number;
offset: number;
rows: GameModelProperties[];
}
export interface GameModelProperties {
_id: ObjectIdLike; //Game ID
name: string; //Game name
description: string; //Description of the game
logo?: string; //Logo of the game
}
After user chooses a game you can get a list of available scores for this game via a following endpoint: https://api.escs.io/rpc/GetGameScoreTypes
For the request you really need only the gameId of the game selected by the user.
export type RpcRequest<HandleInputDTO>;
export interface HandleInputDTO {
context?: AuthServiceContext;
filters?: HandleInputDTOFilters;
}
export interface HandleInputDTOFilters {
conditions?: HandleInputDTOFiltersConditions;
}
export interface HandleInputDTOFiltersConditions {
gameId?: QueryCondition<ObjectIdLike>;//id of the game selected by the user
status?: QueryCondition<GameScoreTypeModelStatusEnum>;
}
export const enum GameScoreTypeModelStatusEnum {
ACTIVE = 'ACTIVE'
}
export type AuthServiceContext = {
type: AuthServiceContextTypeEnum.BY_GAME_SECRET_KEY;
gameId: ObjectIdLike; //your game id from the step 1
secretKey: string; // your secret key from the step 1
};
export const enum AuthServiceContextTypeEnum {
BY_GAME_SECRET_KEY = 'BY_GAME_SECRET_KEY'
}
As a response you are getting a list for the scores that are available in this game.
export type RpcResponse<HandleOutputDTO>;
export interface HandleOutputDTO {
count: number;
limit?: number;
offset: number;
rows: GameScoreTypeModelProperties[];
}
export interface GameScoreTypeModelProperties {
_id: ObjectIdLike; //score id
gameId: ObjectIdLike;
identifier: string; //unique identifier
name: string; //name of the score
description: string; //description of the score
sorting: -1 | 1; // -1 means lower values are better, 1 means higher values are better
}
To present scores to your users you just need the name and the description. When the score is selected you need the score id ("_id") to send to the ESCS later.
The scores are set up by the game developer and this makes them self explanatory to users. Let your users choose one of the available scores.
Getting game modes
The list of the available game modes for this game you are getting via a following endpoint:
https://api.escs.io/rpc/GetGameModes
To get the list of the game modes you just need a gameId of the game that the user selected.
export type RpcRequest<HandleInputDTO>;
export interface HandleInputDTO {
context?: AuthServiceContext;
filters?: HandleInputDTOFilters;
}
export interface HandleInputDTOFilters {
offset?: number;
limit?: number;
conditions?: HandleInputDTOFiltersConditions;
}
export interface HandleInputDTOFiltersConditions {
gameId?: QueryCondition<ObjectIdLike>; //id of the game selected by the user
status?: QueryCondition<GameModeModelStatusEnum>;
}
export const enum GameModeModelStatusEnum {
ACTIVE = 'ACTIVE'
}
export type AuthServiceContext = {
type: AuthServiceContextTypeEnum.BY_GAME_SECRET_KEY;
gameId: ObjectIdLike; //your game id from the step 1
secretKey: string; // your secret key from the step 1
};
export const enum AuthServiceContextTypeEnum {
BY_GAME_SECRET_KEY = 'BY_GAME_SECRET_KEY'
}
In the response you are getting a list of the game modes that the game developer set up for this game.
export type RpcResponse<HandleOutputDTO>;
export interface HandleOutputDTO {
count: number;
limit?: number;
offset: number;
rows: GameModeModelProperties[];
}
export interface GameModeModelProperties {
_id: ObjectIdLike; //id of this game mode - you need this later
gameId: ObjectIdLike;
name: string; //name of the game mode
description: string; //description of the game mode
options: GameModeModelOptions; //important options
type: GameModeModelTypeEnum;
}
export interface GameModeModelOptions {
setParameters: string; //specific parameters - you dont need these
maxSetDuration: number; //max duration of one game
minParticipantsInSet: number; //min number of players in one game
maxParticipantsInSet: number; //max number of players in one game
penaltyPoints: number; //if the user does not finish the game for any reason, user gets penalty points
}
export const enum GameModeModelTypeEnum {
SINGLE = 'SINGLE', //means in the game this is a single player game mode
MULTIPLAYER = 'MULTIPLAYER' //means in the game this is a multiplayer game mode
}
Read more on the game modes here https://docs.escs.io/tournament-series/game-mode-and-scores. The game modes are set up by the game publishers and should be recognizable by the players.
You can display just the name and the description of the game mode, or also additional parameters, like the minimal number of the participants in the game.
Let the user select one of the game modes.
The important parameter for you is:
maxParticipantsInSet - the maximum possible number of players in one game.
The maxParticipantsInSet is the maximum number of the participants in the wager.
oAuth integration
After the user selected the game, game modes and scores for the wager and entered additional parameters that are required by your system, the user presses something like a button “Create wager”. After that you need to guide the user through the following steps.
Connect user’s account in your system to the ESCS account system - the following description resembles classic oAuth flow.
Present to a user a call to action
“Please connect your [YOUR SERVICE NAME] account the ESCS account to proceed. Login or register to the ESCS on the next screen.”
Redirect user as following
https://account.demo.escs.io/oauth?app_id={{OAUTH_APP_ID}}&code={{OAUTH_SECRET_KEY}}&redirect_url={{YOUR_REDIRECT_URL}}&service_name={{YOUR_SERVICE_NAME}}&scope=CURRENT_SESSION_INFO
//OAUTH_APP_ID: you oAuth app id from the Step 2
//OAUTH_SECRET_KEY: you secret key from the Step 2
//YOUR_REDIRECT_URL: url in your system where escs account system needs to redirect the user after the login
//YOUR_SERVICE_NAME: the name of your service that will be shown to the user
Player logs in or creates an escs account.
account.escs.io redirects the user back to the YOUR_REDIRECT_URL that was sent by you with a one time code that you will use to get the user’s information from the ESCS backend.
Pass the one time code from the previous step to your backend and then get user’s ESCS id from the ESCS backend via the following 2 steps.
While the user is waiting you should show a screen with a loader and something like “Please wait…”
// Back-end to back-end request
// Exchanging one-time code for authToken
POST https://oauth.demo.escs.io/rpc/OAuthAuthorizationCodeExchange
// =======================================================
// Request
interface RpcRequest {
id: string; // //any unique string
params: HandleInputDTO;
}
interface HandleInputDTO {
code: string; //the one-time code that you received
application: {
_id: string; //your oauth application id
secretKey: string; //your secret key for your oauth app
};
}
// =======================================================
// You will get the following response
type RpcResponse = {
id: string;
error: {
code: string;
params?: {
[key: string]: any;
};
debug?: {
[key: string]: any;
};
};
} | {
id: string;
result: HandleOutputDTO;
};
interface HandleOutputDTO {
session: { //you need these tokens
authToken: string;
refreshToken: string;
};
}
// =======================================================
/*
Possible error codes:
- APPLICATION_NOT_FOUND
- CODE_NOT_FOUND
- CODE_EXPIRED
- ACCESS_DENIED
- INSUFFICIENT_PERMITS
- INTERNAL_APPLICATION_ERROR
*/
Take the auth token and send the request to receive the user ESCS id.
// Back-end to back-end request
// Get session info and user's id
POST https://oauth.demo.escs.io/rpc/GetCurrentSessionInfo
// =======================================================
// Request
interface RpcRequest {
id: string; //any unique string
params: HandleInputDTO;
}
interface HandleInputDTO {
context: AuthServiceContext;
}
interface AuthServiceContext {
type: 'USER';
authToken: string; //the token that you received
}
// =======================================================
// Response
type RpcResponse = {
id: string;
result: HandleOutputDTO;
};
interface HandleOutputDTO {
session: {
_id: string;
userId: string; //this is the id that you need
};
}
After you received user’s id (”userId” in the above) you need to save it in your system.
You will match the scores based on this id later.
After the account is connected process the payment for the user. You can process the payment also before connecting the accounts - it is up to you.
Create a wager and set the metadata
Now create the wager and set the metadata in the ESCS system - we strongly recommend to do it only after the payment for the user has been successfully processed.
First, create the wager. Use this endpoint.
https://api.escs.io/rpc/CreateWagerTournament
export type RpcRequest<HandleInputDTO>;
export interface HandleInputDTO {
context: AuthServiceContext;
wager: {
gameId: ObjectIdLike; //id of the game selected by the user
creatorEscsUserId: string; // ESCS user id that created the wager
tournament: {
name: string; //any name that you want
description?: string; //optional description
options: TournamentModelOptions; //this is a JSON - see description below
};
};
}
export type AuthServiceContext = {
type: AuthServiceContextTypeEnum.BY_GAME_SECRET_KEY;
gameId: ObjectIdLike; //your game id from the step 1
secretKey: string; // your secret key from the step 1
};
export const enum AuthServiceContextTypeEnum {
BY_GAME_SECRET_KEY = 'BY_GAME_SECRET_KEY'
}
As a parameter in the "options" above, use this JSON template.
It is a template for the simple one match wager (kind of a bracket).
Leave everything as it is and set only the following values (see also comments in the code).
"gameModeId" - you need to enter here the ID of the selected game mode
"gameScoreType" - enter the selected score id
"maxNumberOfPlayersForTournament" - this value needs to be between the minPlayersInSet and playersInSet. Where playersInSet is equal to the value maxParticipantsInSet from the selected game mode. And the minPlayersInSet is equal to the minParticipantsInSet
"winnersOfTournaments" - you can set up here how to determine the winners of the wager. topPercent = 50 means that top 50% by tournament points will be considered winners. topNumerical = 5 means that top 5 players by tournament points will be considered winners. You can let the wager creator decide this. The standard parameter for most cases would be topPercent = 50.
"maxNumberOfSetsInMatch" - enter 1, 3, or 5 depending of whether you want a best of 1, best of 3, or best of 5 match.
"matchEndCondition": - calculate this value according to this formula :(playersInSet-1)*rounddown(maxNumberOfSetsInMatch/2+1)
This gives basically the same result as if someone wins 3 sets in a best of five match. This value is in match points.
"matchPoints" - enter this value based on the formula playersInSet-1, playersInSet-2,...,0. Comma separated.
"tournamentPoints" - enter this value based on the formula playersInSet-1, playersInSet-2,...,0. Comma separated.
"maxDuration" - set this parameter equal or higher than
maxNumberOfSetsInMatch * (waitTimeForPlayer + maxSetDuration + breakBetweenSets) - breakBetweenSets
This is the maximum allowed duration of the match.
iterationQualificationConditions - here you set up a key and value that will be used for the players metadata. In general any unique string for identifier and value - need to stay the same for the whole wager and all participants.
Simple N vs N Wager Template
"name": "Wager tournament",
"description": "test",
"descriptionForPrizes": "",
"additionalPrizePool": 0,
"playersType": "singles",
"matchmakingByScore": false,
"options": {
"maxNumberOfPlayersForTournament": 10, //this value needs to be between the minPlayersInSet and playersInSet
"winnersOfTournaments": {
"type": "topPercent", // enter topPercent or topNumerical here.
"value": [
{
"type": "VALUE",
"value": 50 //the value here means that top 50% are winners. If you choose topNumerical then a value 5 would mean that top 5 players by tournament points are winners
}
]
},
"iterations": [
{
"gameModeId": "629513138202b00008dcec2c", //you need to enter here the ID of the selected game mode
"gameScoreType": "61f934970f48ad00089c3a9c", //enter the selected score id
"matchParameters": {
"defaultTemplate": "bestOfOne",// bestOfOne, bestOfThee, bestOfFive
"minPlayersInSet": 0,
"playersInSet": 0, //this value is provided by the selected game mode
"maxNumberOfSetsInMatch": 1, // Enter 1, 3, or 5 depending of whether you want a best of 1, best of 3, or best of 5 match.
"matchEndCondition": 1, //calculate this value according to this formula (playersInSet-1)*rounddown(maxNumberOfSetsInMatch/2+1), which gives basically the same result as if someone wins 3 sets in a best of five match. This value is in match points.
"matchPoints": "1,0",// enter this value based on the formula playersInSet-1,playersInSet-2,...,0.
"tournamentPoints": "1,0", //enter this value based on the formula playersInSet-1,playersInSet-2,...,0
"maxSetDuration": 300,
"setPointsAggregate": "sum",
"notifyPlayerMinsBeforeMatchStart": 5,
"waitTimeForPlayer": 180,
"penaltyPoints": 200,
"modeType": "MULTIPLAYER",
"breakBetweenSets": 10,
"ingameGlobalMetadata": ""
},
"maxDuration": 480, // set this parameter equal to maxNumberOfSetsInMatch * (waitTimeForPlayer + maxSetDuration + breakBetweenSets) - breakBetweenSets
"show": true,
"drawMode": {
"type": "ALL"
},
"breakDurationAfterIteration": 60,
"gamePrizesForMatchWinners": "",
"exitConditions": {
"type": "runThisIterationXTimes",
"value": 1
},
iterationQualificationConditions: {
"type": "PLAYER_METADATA",
"gameId": "", //your game id from the step 1
"metadataCondition": "EQ",
"values": [
{
//in general any unique string for key and value - need to stay the same for the whole wager
"value": "", //you can use just 1 as a value. Let's call it VALUE1
"condition": "EQ",
"identifier": "" //any unique string, let's call it STRING1
}
]
},
"winnersOfIterationConditions": {
"type": null,
"value": null
},
"awaitMaxIterationDuration": false,
"resetTournamentPoints": false,
"iterationMode": "BRACKETS",
"matchmakingByScore": false,
"matchmakingAlgorithm": "random",
"defaultMatchPoint": null,
"defaultTournamentPoint": null,
"groupByMetadata": false,
"metadata": [],
"metadataCondition": "eq",
"winnersOfIterationSeriesCondition": {
"type": null,
"value": null
}
}
],
"tournamentTemplate": "bestOfOne",
"distributionOfIngamePrizes": null,
"distributionOfPrizeMoney": null,
"registrationEndBeforeStart": 0,
"qualificationForTournaments": {
"type": null,
"value": null
},
"maxNumberIterationInTournament": null,
"enableSignUpPhase": false,
"signUpPhaseTime": 60,
"showAdsOnImIn": false
}
After you created the wager, you are getting the following response with a tournament id and a deep link.
You need to save both. The deep link will get users directly in to the game lobby to play their match.
Before showing the deep link to any user, add ESCS user id to the link in the following manner. deepLink + %26userAccountId%3D{escsUserAccountId}
Here is an example how it should look like:
https://someurl/?escsplayer=custom-championships%2F%3FinviteCode%3D4IAIH0NF%26userAccountId%3D{escsUserAccountId}
This will allow ESCS to offer a better user experience to the user.
After you succesfully created the wager, you need to set the metadata for the user - so that the user is able to participate in the wager.
export type RpcRequest<HandleInputDTO>;
export interface HandleInputDTO {
context: AuthServiceContext;
gameId: ObjectIdLike; //your game id from the step 1
player: {
_id: string; // ESCS user id
type: 'ESCS_ACCOUNT_USER_ID';
};
metadata: PlayerGameMetadataModelMetadata;
}
export interface PlayerGameMetadataModelMetadata {
productIds: ObjectIdLike[]; //needs to stay empty
params: { //needs to stay empty
key: string;
value: string | number;
}[];
qualification: {
//in general any unique string for key and value - need to stay the same for the whole wager
key: string; //needs to be the string STRING1 from the wager creation
value: string | number; //the VALUE1
}[];
}
export type AuthServiceContext = {
type: AuthServiceContextTypeEnum.BY_GAME_SECRET_KEY;
gameId: ObjectIdLike; //your game id from the step 1
secretKey: string; // your secret key from the step 1
};
export const enum AuthServiceContextTypeEnum {
BY_GAME_SECRET_KEY = 'BY_GAME_SECRET_KEY'
}
You get the response with data - means everything is fine.
You do not need any of the data from the response.
Getting wager results
Now subscribe to the event to receive user’s scores after they finished to play the wager. https://api.escs.io/rpc/SubscribeToEvent
export type RpcRequest<HandleInputDTO>;
export interface HandleInputDTO {
context?: AuthServiceContext;
event: PubSubEventModelEvent;
action: PubSubEventModelActionHttpRequest;
lifetime?: number; // Subscription lifetime (in seconds) - any time period that you want to wait for the results. Something big.
}
export interface PubSubEventModelEvent {
type: PubSubEventModelEventTypeEnum.TOURNAMENT_END;
tournamentId: ObjectIdLike; //tournament id that you received when you created the wager
}
export interface PubSubEventModelActionHttpRequest {
type: PubSubEventModelActionTypeEnum.HTTP_REQUEST;
url: string; //your url where ESCS will send the data
}
export type AuthServiceContext = {
type: AuthServiceContextTypeEnum.BY_GAME_SECRET_KEY;
gameId: ObjectIdLike; //your game id from the step 1
secretKey: string; // your secret key from the step 1
};
export const enum AuthServiceContextTypeEnum {
BY_GAME_SECRET_KEY = 'BY_GAME_SECRET_KEY'
}
When the wager is finished you’ll get the following response - this is not the response to the request above, this is the data you receive after the tournament end, which is what you need.
You need the EventData. Based on the escsUserId and isWinner you can match the user to the user in your system and distribute the winnings.
After the wager is created you should show to the user, that created the wager a link to invite other players to play. This link should lead to your service/website.
Joining new users to the wager
You need to guide any new user that joins the wager through the steps of connecting their account and you need to set the user’s metadata as described above.
Only after any new user paid for the wager and connected their account in your system to the ESCS account, show to the user the deep link to the wager as described above.
Sending the wager data to the escs
After the wager was successfully completed you need to call the following endpoint https://api.escs.io/rpc/CreateWagerTournamentBet
tournamentId is the id that you got when you created the wager.
betAmount is the total amount of the wager (the sum of all user payments for this wager) in US dollar cents.
Now you are done. :-)
Click on "Payment options"
Click on "Pay In"
Enter a credit card - check “Save payment method”.
Click on “Account”
Click on “Manage Apps”
Click on “+Create”
Choose a name for your app, enter some description, choose “ESCS OAuth Provider”, enter the url of your service in “Allowed hosts” and press “+”, click “Save”
