ezLadder

Pour utiliser ezLadder, vous devez tout d'abord créer un compte

Ajouter un jeu

Ajouter un jeu nécessite simplement d'indiquer un nom.
2 clés sont alors générées :
game_key : Clé servant à identifier votre jeu lors de chaque appel à l'API
secret_key : Clé permettant de sécuriser les appels à l'API

secret_key doit toujours rester secrète et ne doit apparaitre nulle part en clair !

Les classements

Un jeu peut avoir plusieurs classements différents. Lors de l'ajout d'un jeu un classement nommé "General" est créé.
Chaque classement est identifié par une clé nommée leaderboard_key.

API

L'API est disponible à l'adresse https://api.ezladder.net.
À noter que l'utilisation du https est obligatoire.

Dates et heures

Toutes les dates et heures envoyées à ezladder doivent utiliser le fuseau horaire UTC.

Requêtes

Chaque requête doit impérativement contenir les headers suivants :
game-key : La game_key du jeu concerné par la requête. Attention au tiret "-" au lieu de "_" (game-key et pas game_key).
timestamp : Le timestamp de la requête (UTC)
signature : Une signature HMAC générée à partir de l'URL de l'api appelée, du timestamp et de la secret_key, en utilisant l'algorythme de hash SHA256

Générer la signature

On souhaite par exemple appeler http://api.ezladder.net/players

On ajoute le timestamp à l'URL de la requête, afin d'obtenir une URL fictive qui servira de base pour générer la signature. On obtient par exemple players/1563975789
On génère ensuite la signature en calculant un HMAC à partir de l'URL fictive et de la secret_key du jeu, en utilisant SHA256.

Exemple (PHP) :

$tmpURL = "players/".gmmktime();
$signature = hash_hmac("sha256", $tmpURL, "secret_key");

Ajouter un joueurPOST /players

Envoyer un score pour un joueur nécessite que celui-ci ait été créé auparavant.
La méthode permettant cela est POST /players.
Si la création du joueur réussit, l'API retourne la player_key du joueur qui servira pour tous les appels à l'API concernant ce joueur. Elle accepte 5 paramètres :

name	obligatoire	string	Le nom/pseudo du joueur (191 caractères max)
player_key	facultatif	string (191 caractères max)	La player_key du joueur, si vous ne souhaitez pas qu'elle soit générée par ezLadder (par exemple dans le cas où votre jeu attribue dejà un login unique à chaque joueur). La player_key n'est pas modifiable.
avatar	facultatif	string	Avatar du joueur (191 caractères max)
info	facultatif	string	Une chaine de 2000 caractères maximum, libre d'utilisation (stats, avatar, objet JSON...), à l'exception que vous ne devez pas stocker d'informations personnelles concernant les joueurs (nom réel, adresse...)
email	faculatif	string (email)	Email du joueur, permettant de créer un compte afin que le joueur puisse retrouver ses scores s'il se connecte depuis un autre périphérique ou s'il réinstalle le jeu
password	obligatoire si email est présent	string (min 8 caractères)	Mot de passe du compte

Exemple (JS) :

fetch('https://api.ezladder.net/players', {
  method: 'POST',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: JSON.stringify({  
    "name":"Joueur 1"
  })
});

Modifier un joueurPATCH /players/{player_key}

Appeler la méthode PATCH /players/{player_key} pour modifier un joueur. Elle accepte 5 paramètres :

name	facultatif	string	Le nouveau nom/pseudo du joueur (191 caractères max)
avatar	facultatif	string	Le nouvel avatar du joueur (191 caractères max)
info	facultatif	string	Une chaine de 2000 caractères maximum, libre d'utilisation (stats, avatar, objet JSON...)
email	faculatif	string (email)	Email du joueur, permettant de créer un compte afin que le joueur puisse retrouver ses scores s'il se connecte depuis un autre périphérique ou s'il réinstalle le jeu. Le compte sera créé uniquement si le joueur n'en a pas, et la modification de l'email n'est pas possible.
password	obligatoire si email est présent	string (min 8 caractères)	Mot de passe du compte

Exemple (JS) :

fetch('https://api.ezladder.net/players/P34efabb9043efad4dd37', {
  method: 'PATCH',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: JSON.stringify({  
    "name":"Le faisan furax"
  })
});

Vérifier si un joueur existe (et récupérer ses informations), à partir de sa player_keyGET /players/{player_key}

Appeler la méthode GET /players/{player_key}. Elle accepte 1 paramètre :

info	facultatif	int	Si ce pamamètre est présent et à comme valeur 1, le champ info du joueur sera également retourné

Exemple (JS) :

fetch('https://api.ezladder.net/players/P34efabb9043efad4dd37?info=1', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Vérifier si un joueur existe (et récupérer ses informations), à partir de son comptePOST /players/auth

Appeler la méthode POST /players/auth permet de récupérer la player_key d'un joueur depuis son compte (email/mot de passe).
Si le joueur a un compte mais n'a jamais joué au jeu depuis lequel il se connecte, il est créé sur ce jeu avec le dernier pseudo qu'il a utilisé.
2 paramètres obligatoires :

email	obligatoire	string (email)	Email du compte
password	obligatoire	string	Mot de passe

Exemple (JS) :

fetch('https://api.ezladder.net/players/auth', {
  method: 'POST',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: {
    "email": "test@testemail.com",
    "password": "password"
  }
});

Changer le mot de passe du compte d'un joueurPOST /players/{player_key}/changePassword

Appeler la méthode POST /players/{player_key}/changePassword pour changer le mot de passe du compte d'un joueur. Ceci doit être lié à une action volontaire du joueur demandant de changer son mot de passe.
3 paramètres obligatoires :

old_password	obligatoire	string	Mot de passe actuel du compte
password	obligatoire	string	Nouveau mot de passe
password_confirmation	obligatoire	string	Nouveau mot de passe (confirmation)

Exemple (JS) :

fetch('https://api.ezladder.net/players/P34efabb9043efad4dd37/changePassword', {
  method: 'POST',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: {
    "old_password": "password",
    "password": "passwordnew",
    "password_confirmation": "passwordnew"
  }
});

Déclencher la procédure de réinitialisation du mot de passe d'un joueur (mot de passe oublié)POST /accounts/forgotPassword

Appeler la méthode POST /accounts/forgotPassword commence la procédure permettant à un joueur de réinitialiser son mot de passe s'il l'a oublié.
Si l'adresse email envoyée existe, il recevra un link qui lui permettra de définir un nouveau mot de passe. Ce lien n'est valable que 10 minutes.
Pour des raisons de sécurité, cette méthode retourne toujours un code HTTP de succès (200), à partir du moment où l'email envoyé est syntaxiquement valide, même si celui-ci n'est pas connue sur ezLadder. Cette méthode ne doit être appelée que suite à une action volontaire du joueur signifiant qu'il ne connait plus son mot de passe (bouton "Mot de passe oublié" dans la majorité des cas).

1 paramètre obligatoire :

email	obligatoire	string (email)	L'email du compte dont on souhaite réinitialiser le mot de passe

Exemple (JS) :

fetch('https://api.ezladder.net/accounts/forgotPassword', {
  method: 'POST',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: {
    "email": "email@test.com",
  }
});

Commencer une partiePOST /startGame

La méthode POST /startGame permet d'indiquer qu'un joueur a commencé une partie. Elle retourne un token qu'il faudra envoyer lors de tous les ajouts de score correspondants à cette partie.
Elle nécessite 1 paramètre :

player_key	obligatoire	string	player_key du joueur qui commence une partie

Exemple (JS) :

fetch('https://api.ezladder.net/startGame',   
  method: 'POST',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: JSON.stringify({  
    "player_key":"P34efabb9043efad4dd37"
  })
});

Commencer une partie multi-joueursPOST /startGameMulti

La méthode POST /startGameMulti permet d'indiquer qu'un ou plusieurs joueur ont commencé une partie. Elle retourne un token qu'il faudra envoyer lors de tous les ajouts de score correspondants à cette partie.
Cette méthode retourne un code HTTP 200 dès qu'au moins un joueur a été trouvé. Elle retourne également d'autres informations, comme le nombre de joueur ajoutés à la partie et les player_key des éventuels joueurs non trouvé.
Elle nécessite 1 paramètre :

player_keys	obligatoire	array of string	player_keys des joueurs qui commencent une partie

Exemple (JS) :

fetch('https://api.ezladder.net/startGameMulti',
  method: 'POST',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: JSON.stringify({  
    "player_keys":[
      "P34efabb9043efad4dd37",
      "P764b2314eabcbcea4434",
      "Paea3456789000aabbcc3"
    ]
  })
});       

//Exemple de réponse 
{
  "nbPlayersAddedToGame": 2,
  "playersNotFound": [
      "Paea3456789000aabbcc3",
  ],
  "token": "b8f6175e9f"
}

Ajouter un ou plusieurs joueurs à une partiePOST /addPlayersToGameMulti

Dans le cas où un joueur rejoint une partie en cours, on peut vouloir l'ajouter à la liste des joueurs pouvant recevoir un score lors de cette partie.
La méthode POST /addPlayersToGameMulti permet cela.
Elle retourne les mêmes informations que la méthode POST /startGameMulti.
A noter qu'il est possible d'ajouter des joueurs à une partie qui n'était pas multi-joueurs à la base (créée via la méthode POST /startGame), cela la rendant multi-joueurs.
Il n'est pas possible de retirer des joueurs d'une partie via une méthode dédiée, mais envoyer un score égal à 0 pour le joueur, avec l'option delete_token à 1, permet cela.
Elle nécessite 2 paramètres :

player_keys	obligatoire	array of string	player_keys des joueurs qui sont ajoutés à la partie
token	obligatoire	string	token d'une partie commencée, obtenu par les méthode POST /startGameMulti ou POST /startGame

Exemple (JS) :

fetch('https://api.ezladder.net/addPlayersToGameMulti',
  method: 'POST',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: JSON.stringify({  
    "player_keys":[
      "P34efabb9043efad4dd37",
      "P764b2314eabcbcea4434",
      "Paea3456789000aabbcc3"
    ],
    "token": "b8f6175e9f"
  })
});

//Exemple de réponse 
{
  "nbPlayersAddedToGame": 2,
  "playersNotFound": [
      "Paea3456789000aabbcc3",
  ],
  "token": "b8f6175e9f"
}

Envoyer un scorePOST /score

Avant de pouvoir envoyer un score, il faut avoir récupéré un token avec la méthode POST /startGame

La méthode POST /score permet d'envoyer un score.
Elle prend en compte 5 paramètres :

player_key	obligatoire	string	player_key du joueur qui a fait le score
token	obligatoire	string	Le token de la partie obtenu avec /startGame
score	obligatoire	integer	Score
leaderboard_key	obligatoire si le jeu a plusieurs classements	string	leaderboard_key du classement pour lequel le score est envoyé. Non nécessaire si le jeu n'a qu'un seul classement
delete_token	facultatif	int	Si présent, supprime le token après l'ajout du score, l'empêchant d'être utilisé à nouveau

Exemple (JS) :

fetch('https://api.ezladder.net/score',   
  method: 'POST',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: JSON.stringify({  
    "player_key":"P34efabb9043efad4dd37",
    "token":"4eadf555",
    "score":45,
    "leaderboard_key":"L342Ebeb545454ae54aeaf4d5c",
    "delete_token":1
  })
});

Envoyer les scores d'une partie multi-joueursPOST /scoreMulti

Avant de pouvoir envoyer un score, il faut avoir récupéré un token avec la méthode POST /startGameMulti ou POST /startGame.

La méthode POST /scoreMulti permet d'envoyer un ou plusieurs scores, de mettre fin à la partie pour un joueur ou pour tous les joueurs.
Elle retourne un code HTTP 201 à partir du moment où au moins un des scores envoyés a pu être ajouté. De même, le paramètre delete_token ne fonctionne que si au moins un des scores a pu être ajouté.
Des informations sont retournées : le nombre de scores effectivement ajoutés, les player_keys des joueurs non-trouvés et les player_keys des joueurs trouvés mais qui n'étaient pas présents dans la partie.
Elle prend en compte 5 paramètres :

player_keys	obligatoire	array of string	Liste des scores des joueurs, associés à leurs player_keys (voir exemple ci-dessous)
token	obligatoire	string	Le token de la partie obtenu avec /startGameMulti ou /startGame
leaderboard_key	obligatoire si le jeu a plusieurs classements	string	leaderboard_key du classement pour lequel les scores sont envoyés. Non nécessaire si le jeu n'a qu'un seul classement
delete_token	facultatif	int	Si présent, supprime le token pour tous les joueurs de la partie après l'ajout des scores, l'empêchant d'être utilisé à nouveau

Exemple (JS) :

fetch('https://api.ezladder.net/scoreMulti',   
  method: 'POST',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: JSON.stringify({  
    "player_scores": [
        {
            "player_key": "P34efabb9043efad4dd37",
            "score": 15
        },
        {
            "player_key": "P764b2314eabcbcea4434",
            "score": 22,
            "delete_token": 1 //La partie est terminée pour ce joueur, il ne pourra pas recevoir d'autres scores pour cette partie.
        },
        {
            "player_key": "P32909a07ca4f4db3a1d5",
            "score": 2
        }
    ],
    "token":"4eadf555",
    "leaderboard_key":"L342Ebeb545454ae54aeaf4d5c",
    "delete_token": 1 //Partie terminée pour tous les joueurs, ils ne pourront pas recevoir d'autres scores pour cette partie.
  })
}); 

// Exemple de réponse 
{
  "nbScoresAdded": 2,
  "playersNotFound": [
      "P32909a07ca4f4db3a1d5"
  ],
  "playersNotInGame": []
}

Récupérer le classement d'un jeuGET /leaderboards/{leaderboard_key}

Appeler la méthode GET /leaderboards/{leaderboard_key} pour récupérer un classement pour un jeu.
Les paramètres suivants peuvent être ajoutés à l'url :

start_date	facultatif	date au format YYYY-MM-DD	Date de début du classement
end_date	facultatif	date au format YYYY-MM-DD	Date de fin du classement
paginate	facultatif	integer	Nombre de joueurs retournés par page
page	facultatif	integer	N° de page
progress_since	facultatif	date au format YYYY-MM-DD	Si ce paramètre est passé, des informations sur la progression des joueurs depuis cette date seront retournées avec le classement (ancienne position, nombre de places gagnées/perdues, score gagné/perdu)
type	facultatif	string	best_score : Le classement sera effectué avec le meilleur score obtenu par chaque joueur Si ce paramètre n'est pas présent ou qu'une autre valeur est passée, le type classement sera celui que vous avez configuré dans Leaderboards > Manage
sort	facultatif	string	asc : Les scores seront triés du plus petit au plus grand Si ce paramètre n'est pas présent ou qu'une autre valeur est passée, les scores seront triés tel que vous l'avez configuré pour ce classement, dans Leaderboards > Manage
info	facultatif	int	Si ce paramètre est présent et a la valeur 1, les champs info liés aux joueurs seront également retournés
ignore_negative	facultatif	int	Si ce paramètre est présent et a la valeur 1, les joueurs ayant un score inférieur à 0 seront ignorés

Exemples (JS) :

//Un classement du jeu
fetch('http://api.ezladder.net/leaderboards/L432043503945034534503453405439', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

//Les 10 premiers d'un classement du jeu, en ne prenant en compte que les scores du 05/04/2019 au 06/08/2019
fetch('http://api.ezladder.net/leaderboards/L432043503945034534503453405439?start_date=2019-04-05&end_date=2019-08-06&paginate=10&page=1', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

//Le classement du plus grand score obtenu
fetch('http://api.ezladder.net/leaderboards/L432043503945034534503453405439?type=best_score', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Les périodes de classement prédéfinies suivantes existent : today, yesterday, thisweek, lastweek, thismonth, lastmonth, thisyear, lastyear. Celles-ci sont combinables avec les autres paramètres, exceptés start_date et end_date.
Exemple (JS) :

//Les 3 joueurs ayant eu le moins bon classement hier 
fetch('http://api.ezladder.net/leaderboards/L432043503945034534503453405439/yesterday?paginate=3&page=1&sort=asc', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Récupérer la position et le score d'un joueur dans un classementGET /leaderboards/{leaderboard_key}/players/{player_key}

La méthode GET /leaderboards/{leaderboard_key}/players/{player_key} permet de récupérer les infos du joueurs player_key dans le classement leaderboard_key. Tous les paramètres de la méthode GET /leaderboards/{leaderboard_key} sont utilisables. Les périodes de classement prédéfinies ainsi que les saisons sont également utilisables.
2 paramètres supplémentaires existent pour récupérer la page du classement dans laquel le joueur se situe.

leaderboard_page	facultatif	integer	Si égal à 1, la page du classement dans laquelle le joueur se situe est également retournée. Le paramètre "paginate" est dans ce cas obligatoire.
paginate	obligatoire si leaderboard_page = 1	integer	Nombre de joueurs par page de classement

Exemple (JS) :

fetch('https://api.ezladder.net/leaderboards/L432043503945034534503453405439/players/0000000001',   
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

fetch('https://api.ezladder.net/leaderboards/L432043503945034534503453405439/players/0000000002/thisMonth',   
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
}); 

//Récupération de la page de classement dans laquelle se situe le joueur, 3 joueurs par page
fetch('https://api.ezladder.net/leaderboards/L432043503945034534503453405439/players/0000000002?leaderboard_page=1&paginate=3',   
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Récupérer certaines informations d'un classementGET /leaderboards/{leaderboard_key}/info

Récupère le nom d'un classement et le nombre de joueurs dans celui-ci. Vous pouvez indiquer des dates de début et/ou de fin afin de n'avoir que le nombre de joueurs ayant des scores sur cette période.
Les périodes de classement prédéfinies sont utilisables (today, thisWeek, ...) ainsi que les saisons (season1, season2, ...)

start_date	facultatif	date au format YYYY-MM-DD	Date de début du classement
end_date	facultatif	date au format YYYY-MM-DD	Date de fin du classement
ignore_negative	facultatif	int	Si ce paramètre est présent et a la valeur 1, les joueurs ayant un score inférieur à 0 seront ignorés

Exemple (JS) :

fetch('https://api.ezladder.net/leaderboards/L432043503945034534503453405439/info',   
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Récupérer les réussites d'un jeuGET /achievements

Cette méthode retourne toutes les réussites (achievements) existantes pour un jeu. Aucun paramètre n'est nécessaire.
Exemple (JS) :

fetch('https://api.ezladder.net/achievements',   
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Définir la progression d'un joueur pour une réussitePOST /players/{player_key}/achievements/{achievement_key}

Cette méthode augmente la progression du joueur pour la réussite avec la clé achievement_key.
Un paramètre est requis :

progress	obligatoire	int (min:0, max:100)	Progression

Exemple (JS) :

fetch('https://api.ezladder.net/players/PL00101/achievements/A4de1f25517fc0d7cc53700d2232c055c66bc2e5c2e97b589a3ec64544a8afd10',   
  method: 'POST',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: {
    progress: 30
  }
});

Récupérer les réussites d'un joueurGET /players/{player_key}/achievements

Récupère toutes les réussites avec les progressions du joueur.
Exemple (JS) :

fetch('https://api.ezladder.net/players/PL00101/achievements',   
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Récupérer un réussite d'un joueurGET /players/{player_key}/achievements/{achievement_key}

Récupère pour un joueur une réussite avec sa progression.
Exemple (JS) :

fetch('https://api.ezladder.net/players/PL00101/achievements/Ae94939493fece3430aa',   
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Récupérer les évènements d'un jeuGET /events

Cette méthode retourne tous les évènements d'un jeu. 2 paramètres existent pour les filtrer

type	facultatif	string	Filtrer par type d'évènement
status	facultatif	string	Filtrer par état : active (actif), inactive (inactif), future (future) ou past (passé)

Exemple (JS) :

// Récupérer tous les évènements actifs de type 'news'
fetch('https://api.ezladder.net/events?type=news&status=active',   
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Récupérer un évènement à partir de son event_keyGET /events/{event_key}

Cette méthode retourne les informations d'un évènement.
Exemple (JS) :

fetch('https://api.ezladder.net/events/E4de1f25517fc0d7cc53700d2232c055c66bc2e5c2e97b589a3ec64544a8afd10',   
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Sauvegarder les données de jeu d'un joueurPOST /players/{player_key}/gameData

Cette méthode permet de sauvegarder les données de jeu d'un joueur (progression, etc...). Le format de la sauvegarde est libre (JSON, XML, ...) tant que celle-ci ne dépasse pas 16 ko.
Attention : Le joueur doit avoir un compte ezLadder pour que sa progression puisse être sauvegardée.
1 paramètre obligatoire :

data	obligatoire	string (16 ko max)	Les données de jeu à sauvegarder

Exemple (JS) :

fetch('https://api.ezladder.net//players/Pe34eacb76393be00101/gameData', {
  method: 'POST',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: {
    "save": "{\"level\":5, \"gold\":302}",
  }
});

Récupérer les données de jeu d'un joueurGET /players/{player_key}/gameData

Cette méthode permet de récupérer les données de jeu d'un joueur préalablement sauvegardée avec la méthode POST /players/{player_key}/gameData.
Exemple (JS) :

fetch('https://api.ezladder.net/players/Pe34eacb76393be00101/gameData', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Récupérer les saisons d'un classementGET /leaderboards/{leaderboard_key}/seasons

ezLadder permet de créer des saisons. Une saison est définie par une date de début, une date de fin, un nom et un numéro.
Si aucun nom n'est définit, le nom sera simplement "Season N", où N est le numéro de la saison.
Les numéros de saison sont générés automatiquement et sont toujours consécutifs.
Les saisons sont liées à un classement. Deux classements sur le même jeu peuvent avoir des saisons différentes.

Activer les saisons pour un classement permet ensuite d'avoir les palmarès des joueurs (voir plus bas)

Cette méthode permet de récupérer les saisons d'un classement. La réponse reçue contient la liste des saisons par ordre chronologiue, ainsi que son état : "over (terminée)", "current (en cours)", "future (à venir)".
Exemple (JS) :

fetch('https://api.ezladder.net/leaderboards/Lc30b817a1257c415b349eae453f386b0d9d2034d/seasons', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Récupérer le classement d'une saisonGET /leaderboards/{leaderboard_key}/seasonN

Cette méthode permet de récupérer le classement de la saison N (ainsi que quelques autres info, voir exemple de réponse).
Tous les paramètres de la méthode GET /leaderboards/{leaderboard_key} sont utilisables, à l'exception de start_date et end_date.
Exemple (JS) :

// Récupérer les infos, le classement et le palmarès de la saison 4
fetch('https://api.ezladder.net/leaderboards/Lc30b817a1257c415b349eae453f386b0d9d2034d/season4', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
}); 

// Exemple de réponse
{
  "season": {
    "start_date": "2020-05-06",
    "end_date": "2020-07-20",
    "number": 3,
    "name": "TEST C",
    "status": "current"
  },
  "major_results": [],
  "leaderboard": [
    {
      "name": "ExplosiveFig",
      "avatar": "",
      "score": 14,
      "pos": 1
    },
    {
        "name": "PutridCookie",
        "avatar": "",
        "score": 5,
        "pos": 2
    }
  ]
}

Récupérer le palmarès d'un classementGET /leaderboards/{leaderboard_key}/major-results

Cette méthode permet de récupérer tout le palmarès d'un classement, saison par saison.
Exemple (JS) :

fetch('https://api.ezladder.net/leaderboards/Lc30b817a1257c415b349eae453f386b0d9d2034d/major-results', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
}); 

// Exemple de réponse
[
    {
        "start_date": "2019-12-02",
        "end_date": "2020-05-22",
        "number": 1,
        "name": "Season 1",
        "status": "over",
        "major_results": [
            {
                "pos": 1,
                "player": {
                    "name": "UltraPlanet3091",
                    "player_key": "P2340429305439053045394503495e1231232112",
                    "avatar": "",
                    "has_account": false
                }
            },
            {
                "pos": 2,
                "player": {
                    "name": "MollusqueIncontrolable",
                    "player_key": "P034eabc43cb3045394503495e3045394503495e",
                    "avatar": "",
                    "has_account": true
                }
            }
        ]
    },
    {
        "start_date": "2020-03-04",
        "end_date": "2020-07-14",
        "number": 2,
        "name": "Tamagotchi season",
        "status": "over",
        "major_results": [
            {
                "pos": 1,
                "player": {
                    "name": "MollusqueIncontrolable",
                    "player_key": "P034eabc43cb3045394503495e3045394503495e",
                    "avatar": "",
                    "has_account": true
                }
            },
            {
                "pos": 2,
                "player": {
                    "name": "kozika",
                    "player_key": "P234edce4444e8b48ba0d28f10afeaf53b1b3dfac",
                    "avatar": "",
                    "has_account": true
                }
            }
        ]
    }
]

Récupérer le palmarès d'un joueurGET /players/{player_key}/major-results

Cette méthode permet de récupérer tout le palmarès d'un joueur, pour tous les classements du jeu, saison par saison.
Exemple (JS) :

fetch('https://api.ezladder.net/players/Pc30b817a1257c415b349eae453f386b0d9d2034d/major-results', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
}); 

// Exemple de réponse 
[
    {
        "leaderboard_name": "Leaderboard",
        "major_results": [
            {
                "season_number": 1,
                "season_name": "Season 1",
                "pos": 2
            },
            {
                "season_number": 2,
                "season_name": "Tamagotchi season",
                "pos": 1
            },
            {
                "season_number": 3,
                "season_name": "TEST C",
                "pos": 1
            }
        ]
    },
    {
        "leaderboard_name": "Blabla",
        "major_results": [
            {
                "season_number": 1,
                "season_name": "Azerty",
                "pos": 1
            }
        ]
    }
]

Récupérer le palmarès d'un joueur pour un classement précisGET /leaderboards/{leaderboard_key}/players/{player_key}/major-results

Cette méthode permet de récupérer le palmarès d'un joueur pour un classement, saison par saison.
Exemple (JS) :

fetch('https://api.ezladder.net/leaderboards/Lc30b817a1257c415b349eae453f386b0d9d2034d/players/Pc30b817a1257c415b349eae453f386b0d9d2034d/major-results', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
}); 

// Exemple de réponse 
[
    {
        "season_number": 1,
        "season_name": "Season 1",
        "pos": 2
    },
    {
        "season_number": 2,
        "season_name": "Tamagotchi season",
        "pos": 1
    },
    {
        "season_number": 5,
        "season_name": "TEST C",
        "pos": 1
    }
]

Quêtes

ezLadder permet de gérer des quêtes journalières pour vos joueurs.
Une quête est composée de :
- Un nom
- Une description
- Une icone
- Un score à atteindre
- Une clef, générée automatiquement par ezLadder

Le nombre de quêtes actives maximum pour un joueur peut-être défini librement (par défaut 3, min 0, max 10)
Lorsque les quêtes actives d'un joueur sont récupérées pour la première fois du jour, s'il n'en a pas le maximum possible, il en obtient une nouvelle.
Une joueur ne peut pas avoir 2 quêtes actives identiques.

Récupérer les quêtes d'un joueurGET /players/{player_key}/quests

Cette méthode permet de récupérer les quêtes d'un joueur.
Si une quête est nouvelle, elle aura l'attribut "new" à 1. Au prochain appel de cette méthode, cet attribut sera passé à 0.
Si une quête vient juste d'être terminée, elle aura l'attribut "new_completed" à 1. Au prochain appel de cette méthode, cette quête sera toujours visible, à moins que le paramètre reward_given ait été utilisé, ou que la méthode POST /players/{player_key}/quests/{quest_key}/rewardGiven ait été appelée.
Un paramètre existe :

reward_given	faculatif	int	Si reward_given = 1, alors les quêtes nouvellement complétées (new_completed = 1) présentes dans la réponse ne seront plus retournées ensuite.

Exemple (JS) :

fetch('https://api.ezladder.net/players/Pc30b817a1257c415b349eae453f386b0d9d2034d/quests', {
  method: 'GET',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json', 
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
}); 

// Exemple de réponse 
[
    {
        "name": "The end of the start",
        "quest_key": "Q8313ecac4a8ba14867b4e2a52756e4e0c7ca97e422bf6bf47588a42cff09069b",
        "description": "",
        "steps_required": 100,
        "progress": 50,
        "progress_at": "2020-09-28 11:42:45",
        "progress_percent": 50,
        "new": 0,
        "new_completed": 0,
        "iconURL": "url"
    },
    {
        "name": "Too strong",
        "quest_key": "Q5b52e272b3056d9e0a176d2860550557efdcf80830775b610c5bcb146626b8b8",
        "description": "",
        "steps_required": 100,
        "progress": 0,
        "progress_at": "2020-09-28 12:18:05",
        "progress_percent": 0,
        "new": 1,
        "new_completed": 0,
        "iconURL": "url"
    }
]

Définir la progression d'un joueur pour une quêtePATCH /players/{player_key}/quest/{quest_key}

Cette méthode augmente la progression du joueur pour la quête avec la clé quest_key.
Un paramètre est requis :

progress	obligatoire	int	Progression

Exemple (JS) :

fetch('https://api.ezladder.net/players/Pc30b817a1257c415b349eae453f386b0d9d2034d/quests/Q5b52e272b3056d9e0a176d2860550557efdcf80830775b610c5bcb146626b8b8',   
  method: 'PATCH',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  },
  body: {
    progress: 30
  }
});

Remplacer une quêtePATCH /players/{player_key}/quest/{quest_key}/replace

Cette méthode permet au joueur d'obtenir une nouvelle quête à la place de la quête ayant la clé quest_key. La nouvelle quête sera forcément différente de celle replacée. Si la quête remplacée était la seule disponible, aucune quête ne sera obtenue à la place.

Exemple (JS) :

fetch('https://api.ezladder.net/players/Pc30b817a1257c415b349eae453f386b0d9d2034d/quests/Q5b52e272b3056d9e0a176d2860550557efdcf80830775b610c5bcb146626b8b8/replace',   
  method: 'PATCH',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});

Masquer une quête terminée (récompense donnée)PATCH /players/{player_key}/quest/{quest_key}/rewardGiven

Cette méthode permet d'indiquer qu'une récompense a été donnée au joueur pour avoir terminée la quête. Ainsi cette quête ne sera plus retournée lors des futurs appels à GET /players/{player_key}/quests.

Exemple (JS) :

fetch('https://api.ezladder.net/players/Pc30b817a1257c415b349eae453f386b0d9d2034d/quests/Q5b52e272b3056d9e0a176d2860550557efdcf80830775b610c5bcb146626b8b8/rewardGiven',   
  method: 'PATCH',  
  headers: {
    'Accept': 'application/json',  
    'Content-Type': 'application/json',  
    "game-key":"eae87e4f74b9f4f716a2faf45325e2473d4484923d91779b0dcf6feaf5e78003",  
    "timestamp":152525254,
    "signature":"2faf45325e2473d44849232faf45325e2473d4484923"
  }
});