Connexion pour les jeux sur Facebook

Lorsque vous concevez un jeu destiné à être utilisé sur Facebook.com, vous construisez une application web qui sera servie à l'intérieur d'un conteneur iframe sur Facebook.com. Comme Facebook ne propose des jeux qu'aux joueur·euses connecté·es, cela signifie que vous avez la garantie d'avoir un·e utilisateur·ice Facebook connecté·e disponible pour l'authentification.

En tant que tel, vous devriez toujours intégrer la prise en charge de Facebook Login dans votre jeu, afin de disposer d'un ID cohérent sur lequel synchroniser et conserver la progression du jeu, et pour mettre en œuvre les fonctionnalités sociales que les joueur·euses attendent dans les jeux auxquels ils ou elles jouent. Si votre jeu existe sur plusieurs plateformes, vous pouvez utiliser ce même ID pour synchroniser l'état du jeu pour vos joueur·euses sur les appareils qu'ils ou elles utilisent.

Ce document présente les différentes approches de l'utilisation de Facebook Login et la façon dont vous pouvez en faire le meilleur usage dans votre jeu.

Sources d'authentification

Il existe plusieurs façons pour un·e joueur·euse de s'authentifier pour la première fois, et plusieurs approches pour vérifier l'identité après la première authentification.

Authentification dans l’Espace Apps

Lorsque les joueur·euses lancent votre jeu via le bouton Jouer maintenant dans l’Espace Apps, ils ou elles accordent à votre application un ensemble spécifique d’autorisations, tel que configuré dans l'onglet Détails de l'application dans l’Espace App.

Bouton Jouer maintenant dans l'Espace Apps

Étant donné qu'un pourcentage élevé de joueur·euses arrivera à votre application via l'Espace Apps, il s'agira d'un chemin d'authentification courant. Pour garantir une connexion fluide à partir de l'Espace Apps, vous devez configurer l'ensemble des autorisations accordées via l'Espace Apps pour qu'elles correspondent aux autorisations attendues par votre jeu sur Facebook.com et sur mobile.

Consultez le guide de l'Espace Apps pour plus de détails.

Authentification sur une autre plateforme

Si votre jeu est présent sur des plateformes mobiles et prend en charge Facebook Login dans la version mobile, il est possible que certain·es de vos joueur·euses soient déjà authentifié·es lorsqu'ils ou elles viennent jouer à votre jeu sur Facebook.com. Il est important de s'assurer que la version de votre jeu sur Facebook.com attend le même ensemble d'autorisations que votre jeu mobile.

Détection du statut de connexion

Comme décrit ci-dessus, les joueur·euses arriveront à votre jeu dans un statut logged in ou not logged in, selon qu'ils ou elles ont autorisé votre jeu par le passé, soit en jouant à votre jeu sur Facebook précédemment, via Espace Apps, soit via une version mobile de votre jeu.

Vous pouvez détecter si un·e joueur·euse s'est précédemment connecté·e à votre jeu de deux manières :

• Côté client, à l'aide de la méthode FB.getLoginStatus() du SDK JS
• Côté serveur, en décodant un signed_request

Utilisation du SDK Facebook pour JavaScript

En appelant FB.getLoginStatus() au chargement du document, vous pouvez vous assurer qu'un·e joueur·euse est immédiatement connecté·e lorsqu'il ou elle charge le jeu. Vous pouvez ensuite utiliser FB.api() pour accéder au statut de jeu du ou de la joueur·euse via son ID utilisateur, et pour récupérer les informations utilisées pour la personnalisation, comme le nom du ou de la joueur·euse, sa photo de profil et sa liste d'ami·es.

FB.getLoginStatus(function(response) {
  if (response.status === 'connected') {
    // the user is logged in and has authenticated your
    // app, and response.authResponse supplies
    // the user's ID, a valid access token, a signed
    // request, and the time the access token 
    // and signed request each expire
    var uid = response.authResponse.userID;
    var accessToken = response.authResponse.accessToken;
  } else if (response.status === 'not_authorized') {
    // the user is logged in to Facebook, 
    // but has not authenticated your app
  } else {
    // the user isn't logged in to Facebook.
  }
 }); 

Si le ou la joueur·euse ne s'est pas connecté·e, vous pouvez appeler FB.login(...) pour afficher une version modale de la boîte de dialogue de connexion en haut de l'écran initial de votre jeu. Le rappel pour cette boîte de dialogue doit être le même appel de méthode que celui que vous utilisez lorsque vous appelez FB.getLoginStatus.

Utilisation d'une requête signée

Lorsque votre jeu est chargé sur Facebook.com, une demande HTTP POST est envoyée à l'URL de vos jeux web Facebook spécifiés. Cette requête POST contiendra certains paramètres, notamment le paramètre signed_request que vous pouvez utiliser pour l'autorisation.

Le paramètre signed_request est encodé avec base64url et signé avec une version HMAC de votre clé secrète, selon la spécification OAuth 2.0.

Cela signifie que lorsqu'il est PUBLIé à votre application, vous devrez l'analyser et le vérifier avant de pouvoir l'utiliser. Cette opération s’effectue en trois étapes :

1. Séparez la requête signée en deux parties, délimitées par un caractère « . » (par exemple, 238fsdfsd.oijdoifjsidf899).
2. Décodez la première partie (la signature encodée) avec base64url.
3. Décodez la seconde partie (la charge utile) avec base64url, puis décodez l’objet JSON obtenu.

Ces étapes sont possibles dans tout langage de programmation moderne. Vous trouverez ci-dessous un exemple en PHP :

function parse_signed_request($signed_request) {
  list($encoded_sig, $payload) = explode('.', $signed_request, 2); 

  $secret = "appsecret"; // Use your app secret here

  // decode the data
  $sig = base64_url_decode($encoded_sig);
  $data = json_decode(base64_url_decode($payload), true);

  // confirm the signature
  $expected_sig = hash_hmac('sha256', $payload, $secret, $raw = true);
  if ($sig !== $expected_sig) {
    error_log('Bad Signed JSON signature!');
    return null;
  }

  return $data;
}

function base64_url_decode($input) {
  return base64_decode(strtr($input, '-_', '+/'));
}

Cela produira un objet JSON semblable à ce qui suit :

{
   "oauth_token": "{user-access-token}",
   "algorithm": "HMAC-SHA256",
   "expires": 1291840400,
   "issued_at": 1291836800,
   "user_id": "218471"
}

En analysant le paramètre signed_request, vous serez en mesure de détecter si le ou la joueur·euse actuel·le a authentifié votre jeu. Si c'est le cas, le paramètre signed_request contiendra l'ID utilisateur du ou de la joueur·euse, que vous pourrez utiliser pour récupérer les informations de personnalisation et le statut du jeu. Vous pouvez échanger ce paramètre signed_request contre un jeton d'accès, et l'utiliser pour accéder à l'API Graph pour une personnalisation plus approfondie.

Première authentification

La première fois qu'un·e joueur·euse accède à votre jeu, vous devez l'inviter à s'authentifier en lui présentant la boîte de dialogue de connexion. La connexion côté client via le SDK Javascript est le flux de connexion recommandé pour l'authentification. Les développeur·euses peuvent montrer des graphiques de jeu simples avant de lancer une boîte de dialogue de connexion et après avoir annulé la boîte de dialogue.

Happy Acres, qui utilise un arrière-plan personnalisé pour la connexion

Connexion côté client via le SDK JS

Unique pour les jeux sur Facebook, la version JavaScript de la boîte de dialogue de connexion sera déclenchée en mode async à l'intérieur de l’élément iframe. Cela signifie qu'elle apparaît comme une fenêtre contextuelle modale au-dessus du reste du contenu du jeu, plutôt que comme une fenêtre de navigateur distincte.

C'est important, car cela signifie que la boîte de dialogue peut être invoquée directement à partir du code, et non dans le cadre d'un évènement de l'interface utilisateur, sans être bloquée par les méthodes de détection du blocage des fenêtres contextuelles d'un navigateur.

Par conséquent, vous pouvez utiliser FB.getLoginStatus() pour vérifier si le ou la joueur·euse actuel·le s'est déjà authentifié·e dans votre jeu, et si ce n'est pas le cas, afficher immédiatement la boîte de dialogue de connexion en haut du contenu de votre jeu en appelant FB.login(), sans avoir besoin d'afficher un bouton « Connexion ».

Consultez l’exemple ci-dessous :

// Place following code after FB.init call.

function onLogin(response) {
  if (response.status == 'connected') {
    FB.api('/me?fields=first_name', function(data) {
      var welcomeBlock = document.getElementById('fb-welcome');
      welcomeBlock.innerHTML = 'Hello, ' + data.first_name + '!';
    });
  }
}

FB.getLoginStatus(function(response) {
  // Check login status on load, and if the user is
  // already logged in, go directly to the welcome message.
  if (response.status == 'connected') {
    onLogin(response);
  } else {
    // Otherwise, show Login dialog first.
    FB.login(function(response) {
      onLogin(response);
    }, {scope: 'email'});
  }
});

Étapes suivantes

Quelle que soit la méthode que vous choisissez d'utiliser pour la connexion, le fait d'avoir une véritable identité dans votre jeu vous aidera à mettre en place d'excellentes fonctionnalités sociales qui favoriseront la rétention et la distribution de votre jeu.

La connexion est la première étape vers bon nombre de ces fonctionnalités, et vous pouvez les concevoir en utilisant les produits ci-dessous :

• Invitations à des jeux
• Notifications application à utilisateur

Consultez les Recommandations pour les jeux dans Facebook pour obtenir plus de conseils sur l'utilisation efficace de Facebook Login dans votre jeu.