Développement

Sélectionnez votre plateforme

Défis des API serveur à serveur

Notice of feature support change

En raison de l’arrêt programmé de l’application Scoreboard (Classement) le 20 décembre 2024, l’API Challenges n’est actuellement plus prise en charge. Nous vous déconseillons d’implémenter l’API Challenges dans votre application pour le moment, en attendant de futures mises à jour.

API serveur à serveur

Les API Rest serveur à serveur (S2S) fournissent un canal sécurisé pour interagir avec les services de la plateforme Meta Horizon. Par exemple, vous souhaitez qu’un défi Meta Quest ne soit plus privé mais public. Cette page fournit des détails sur les appels serveur du Meta Quest Challenge que vous pouvez effectuer.

Principes de base des messages

Vous devez vous familiariser avec certains principes de base des messages de serveur à serveur.

Exigences relatives aux API serveur à serveur

Les appels à ces API doivent satisfaire aux exigences suivantes :

Point de terminaison

Envoyez toutes les requêtes de serveur à serveur à ce point de terminaison :

https://graph.oculus.com

Token d’accès

Incluez un token d’accès dans chaque requête pour l’authentifier en tant que requête serveur valide ou pour le compte d’un utilisateur ou d’une utilisatrice spécifique. Un token d’accès peut contenir l’un des éléments suivants :

Identifiants de l’application

Token d’accès utilisateur

Identifiants de l’application

Les identifiants de l’application permettent de vérifier que le back-end de votre serveur est une ressource de confiance. Ne les partagez jamais avec une application côté client.

Un token d’accès avec des identifiants d’application contient l’ID de l’application et la clé secrète disponibles sur la page de l’API⁠ dans le Tableau de bord développeur(se) Meta Horizon. Son format est le suivant : OC|$APPID|$APPSECRET.

Si vos identifiants sont compromis ou si vous avez besoin de nouveaux identifiants d’API, générez une nouvelle clé secrète pour l’application. La modification de la clé secrète de l’application révoquera l’autorisation accordée à la clé secrète précédente. Pour accéder à la clé secrète de l’application, un compte administrateur doit être utilisé.

Token d’accès utilisateur·ice

Un token d’accès utilisateur·ice authentifie les requêtes envoyées pour le compte d’un utilisateur ou d’une utilisatrice. Utilisez ce type de token lorsque des actions relèvent d’un utilisateur ou d’une utilisatrice spécifique. Par exemple, pour mettre à jour le leaderboard, sous réserve que le client vous y autorise, avec les résultats d’un match multijoueur hébergé sur un serveur. Pour chaque utilisateur ou utilisatrice, utilisez le token d’accès utilisateur·ice pour authentifier votre serveur lors de l’envoi de requêtes pour mettre à jour son leaderboard.

Récupérez le token utilisateur grâce à la méthode ovr_User_GetAccessToken().

Vous pouvez également utiliser la fonction Blueprint suivante :

Blueprint function with User Access Tokens

Le token est renvoyé en tant que réponse et peut être transmis du client à votre serveur. Un token d’accès utilisateur·ice contient FRL ou OC et une longue chaîne alphanumérique de ce type : FRL12342GhFccWvUBxPMR4KXzM5s2ZCMp0mlWGq0ZBrOMXyjh4EmuAPvaXiMCAMV9okNm9DXdUA2EWNplrQ.

De plus, vous pouvez récupérer votre token utilisateur·ice à des fins de test dans la section « Token utilisateur » de la page d’API⁠ du Tableau de bord développeur(se) Meta Horizon, qui se trouve dans la barre de navigation de gauche.

ID d’app

Certains appels de serveur nécessitent un ID d’application, que vous pouvez trouver sur la page API⁠ du tableau de bord développeur(se) Meta Horizon.

Lancer un défi

URL : https://graph.oculus.com/{app_id}/challenges

Méthode : POST

Exemple de requête :

POST /1234757621998335/challenges/?api_name=leaderboard_api_name=hello_friends&creation_type=DEVELOPER_CREATED&visibility=PRIVATE&title=sample_challenge
Host: graph.oculus.com
Authorization: Bearer OC|1234f7a788b0c0b270f9691d0a06d5a5

Exemple de requête cURL :

curl -X POST https://graph.oculus.com/$APP_ID/challenges -d "access_token=OC|$APP_ID|$APP_SECRET" -d "leaderboard_api_name=sample_leaderboard" -d "creation_type=DEVELOPER_CREATED" -d "visibility=PRIVATE" -d "title=sample_challenge"

Paramètre	Type de paramètre	Description	Type
`leaderboard_api_name`	Requête	Obligatoire. Nom de l’API unique du leaderboard associé à votre défi.	chaîne
`creation_type`	Requête	Obligatoire. Doit toujours afficher « DEVELOPER_CREATED » avec cette méthode.	Énumération, valeur `DEVELOPER_CREATED`
`visibility`	Requête	Obligatoire. `PUBLIC`, `INVITE_ONLY` ou `PRIVATE`. `PUBLIC` : n’importe quel·le utilisateur·ice peut voir le défi et y participer, sans même avoir reçu d’invitation. `INVITE_ONLY` : n’importe quel·le utilisateur·ice peut voir le défi, mais seul·es ceux ou celles ayant reçu une invitation peuvent y participer. Cette option doit être utilisée, par ex. pour les défis avec des participant·es spécifiquement limité·e·s, où vous souhaitez malgré tout publier le défi pour que le public puisse le visionner. `PRIVATE` : seul·es ceux ou celles ayant reçu une invitation peuvent voir le défi ou y participer.	Énumération, valeur `PUBLIC`, `INVITE_ONLY` ou `PRIVATE`
`title`	Requête	Le titre du défi.	chaîne
`description`	Requête	Description du défi.	chaîne
`start_date`	Requête	Date de début du défi.	date
`end_date`	Requête	Date de fin du défi. Affiche trois jours plus tard, par défaut.	date
`fields`	Requête	Une liste de champs séparée par des virgules à récupérer. Valeurs possibles : `id` `title` `description` `start_date` `end_date` `leaderboard` `creation_type` `visibility` `entries` `invited_users` `participants`	Une liste de chaînes séparées par une virgule

Exemple de réponse :

{
	"id": "2643098232993236",
	"title": "hello_challenge",
	"start_date": "2020-07-14T22:58:24+0000",
	"end_date": "2020-07-17T22:58:24+0000",
	"leaderboard": {
		"id": "3123283331082599"
	}
}

Change la visibilité ou la date de début ou de fin d’un défi

URL : https://graph.oculus.com/{challenge_id}

Méthode : POST

Exemple de requête :

POST /1234757621998335?visibility=INVITE_ONLY
Host: graph.oculus.com
Authorization: Bearer OC|1234f7a788b0c0b270f9691d0a06d5a5

Exemple de requête cURL :

curl -X POST https://graph.oculus.com/$CHALLENGE_ID -d "access_token=OC|$APP_ID|$APP_SECRET" -d "visibility=INVITE_ONLY"

Paramètre	Type de paramètre	Description	Type
`visibility`	Requête	`PUBLIC`, `INVITE_ONLY` ou `PRIVATE`. `PUBLIC` : n’importe quel·le utilisateur·ice peut voir le défi et y participer, sans même avoir reçu d’invitation. `INVITE_ONLY` : n’importe quel·le utilisateur·ice peut voir le défi, mais seul·es ceux ou celles ayant reçu une invitation peuvent y participer. Cette option doit être utilisée, par ex. pour les défis avec des participant·es spécifiquement limité·e·s, où vous souhaitez malgré tout publier le défi pour que le public puisse le visionner. `PRIVATE` : seul·es ceux ou celles ayant reçu une invitation peuvent voir le défi ou y participer. En général, cette option est uniquement réservée aux défis entre ami·es créés par des utilisateur·ices et non par des développeur·ses.	Énumération, valeur « `PUBLIC` », « `INVITE_ONLY` » ou « `PRIVATE"` »
`start_date`	Requête	Date	entier qui représente un horodatage Unix
`end_date`	Requête	Date. Affiche 3 heures après la date de début, par défaut.	entier qui représente un horodatage Unix
`fields`	Requête	Une liste de champs séparée par des virgules à récupérer. Valeurs possibles : `id` `title` `description` `start_date` `end_date` `leaderboard` `creation_type` `visibility` `entries` `invited_users` `participants`	Une liste de chaînes séparées par une virgule

Exemple de valeur renvoyée :

{
	"success": true
}

Supprimer un défi

URL : https://graph.oculus.com/{challenge_id}

Méthode : DELETE (SUPPRIMER)

DELETE /12347576219983357
Authorization: Bearer OC|1234f7a788b0c0b270f9691d0a06d5a5

Exemple de requête cURL :

curl -X DELETE https://graph.oculus.com/$CHALLENGE_ID -d "access_token=OC|$APP_ID|$APP_SECRET"

Exemple de valeur renvoyée :

{
	"success": true
}

Obtenir une liste de défis dans votre application

Utilisez cette méthode pour renvoyer une liste de défis dans votre application jointe à un leaderboard donné.

URL : https://graph.oculus.com/{app_id}/challenges

Méthode : GET (OBTENIR)

Exemple de requête :

GET /1234757621998335/challenges
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Exemple de requête cURL :

curl -G https://graph.oculus.com/$APP_ID/challenges -d "access_token=OC|$APP_ID|$APP_SECRET"

Paramètre	Type de paramètre	Description	Type
`leaderboard_api_name`	Requête	Affichera par défaut des défis pour tous les leaderboards. Utilisez `leaderboard_api_name` pour renvoyer des défis à un seul leaderboard.	Chaîne
`include_active_challenges`	Requête	Par défaut : True (Vrai). Si False (Faux), alors les défis précédents ne seront pas renvoyés à votre application.	Booléen
`include_past_challenges`	Requête	Par défaut : False. Si True, renvoie les défis dont les dates de fin sont échues.	Booléen
`include_future_challenges`	Requête	Par défaut : False. Si True, renvoie des défis dont les dates de fin sont ultérieures.	Booléen
`fields`	Requête	Une liste de champs séparée par des virgules à récupérer. Valeurs possibles : `id` `title` `description` `start_date` `end_date` `leaderboard` `creation_type` `visibility` `entries` `invited_users` `participants`	Une liste de chaînes séparées par une virgule

Récupérer des données relatives à un défi

Utilisez cette méthode pour renvoyer des informations concernant un défi dans votre application.

URL : https://graph.oculus.com/{challenge_id}

Méthode : GET

Exemple de requête :

GET /1234757621998335?fields=id,title,description,start_date,end_date,leaderboard
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Exemple de requête cURL :

curl -G https://graph.oculus.com/$CHALLENGE_ID -d "access_token=OC|$APP_ID|$APP_SECRET" -d "fields=id,title,description,start_date,end_date,leaderboard"

Paramètre	Type de paramètre	Description	Type
`fields`	Requête	Une liste de champs séparée par des virgules à récupérer. Valeurs possibles : `id` `title` `description` `start_date` `end_date` `leaderboard` `creation_type` `visibility` `entries` `invited_users` `participants`	Une liste de chaînes séparées par une virgule

Exemple de réponse :

{
	"title": "sample_challenge",
	"description": "Let's see who can climb the highest!",
	"id" : "2643098232993236",
  "leaderboard": {
        "id": "7410520479067243"
    }
}

Obtenir les entrées de score de Challenge

Utilisez cette méthode pour renvoyer les entrées de score d’un défi.

Méthode : GET

URL : https://graph.oculus.com/{challenge_id}/entries

Exemple de requête :

GET /1234757621998335/entries
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Exemple de requête cURL :

curl -G https://graph.oculus.com/$CHALLENGE_ID/entries -d "access_token=OC|$APP_ID|$APP_SECRET"

Paramètre	Type de paramètre	Description	Type
`filter`	Requête	Réduit l’étendue des entrées de score renvoyées.	Énumération, valeur `NONE` (par défaut), `FRIENDS` ou `USER_IDS` `NONE` : aucun filtre activé sur le leaderboard. `FRIENDS` : filtre le leaderboard afin d’inclure uniquement les ami·es de l’utilisateur·ice actuel·le. `USER_IDS` : filtre le leaderboard afin d’inclure les ID d’utilisateur·ices spécifiques. Utilisez ce filtre pour obtenir les classements des utilisateur·ices qui sont en compétition les un·es avec les autres
`start_at`	Requête	Définit l’ordre de renvoi des entrées.	Énumération, valeur `TOP` (par défaut), `VIEWER`, `VIEWER_OR_TOP` ou `OFFSET`
`offset`	Requête	Obligatoire lorsque la valeur start-at est décalée et indique la valeur de décalage à utiliser.	Entier
`limit`	Requête	Réduit le nombre d’entrées renvoyées au nombre défini.	Entier
`user_ids`	Requête	Renvoie les entrées pour un ensemble d’utilisateur·ices donné.	Liste d’entiers représentant les identifiants utilisateur·ice.
`fields`	Requête	Une liste de champs séparée par des virgules à récupérer. Valeurs possibles : `id` `challenge` `user` `rank` `score` `timestamp` `extra_data`	Une liste de chaînes séparées par une virgule