Build

Inicio de sesión para juegos en Facebook

The Web Games on Facebook and Facebook Gameroom platforms are no longer available for new submissions. This documentation is intended solely for developers with existing games. To learn more, read our blog post.

Cuando creas un juego para jugarlo en Facebook.com, lo que compilas es una app web, que se mostrará dentro de un contenedor iframe en Facebook.com. Facebook solo muestra juegos a jugadores conectados, lo que te garantiza que cuentas con un usuario de Facebook conectado disponible para su autenticación.

En consecuencia, es necesario que siempre admitas el inicio de sesión con Facebook en tu juego para que se te proporcione un identificador coherente, con el que puedes sincronizar y conservar el progreso del juego, y, además, para implementar las funciones sociales que los jugadores esperan encontrar en los juegos que juegan. Si tu juego se utiliza en varias plataformas, puedes usar este mismo identificador para sincronizar el estado del juego de los jugadores en los dispositivos que usan.

En este documento, se describen los distintos enfoques que se pueden usar con el inicio de sesión con Facebook y cómo puedes aprovecharlos al máximo en tu juego.

Fuentes de autenticación

Hay una serie de maneras en las que un jugador puede autenticarse por primera vez y varios enfoques para verificar la identidad después de que se realizó la primera autenticación.

Autenticación del centro de apps

Cuando los jugadores inician el juego con el botón Jugar en el centro de apps, autentican un conjunto específico de permisos de tu app que se configuraron en la pestaña "Detalles de la app" en el panel de apps.

El botón "Jugar" en el centro de apps

Dado que un alto porcentaje de jugadores llegará a tu app a través del centro de apps, funcionará como ruta de autenticación común. Para garantizar que el inicio de sesión desde el centro de apps transcurra sin contratiempos, deberás configurar el conjunto de permisos que se otorga mediante el centro de apps para que coincida con los permisos que requiere el juego en Facebook.com y en los dispositivos móviles.

Consulta la guía del centro de apps para obtener más información.

Autenticación en otra plataforma

Si tu juego se utiliza en plataformas móviles y admite el inicio de sesión con Facebook en la versión para dispositivos móviles, es posible que algunos de tus jugadores ya estén autenticados cuando jueguen tu juego en Facebook.com. Es importante asegurarte de que la versión de tu juego en Facebook.com requiera el mismo conjunto de permisos que tu juego para dispositivos móviles.

Detección del estado de inicio de sesión

Como se describió con anterioridad, los jugadores jugarán tu juego en un estado de inicio de sesión o sin inicio de sesión, en función de si autenticaron tu juego en el pasado, jugaron previamente tu juego en Facebook, lo hicieron mediante el centro de apps, o bien si realizaron la autenticación mediante una versión para dispositivos móviles de tu juego.

Puedes detectar si un jugador inició sesión previamente en tu juego de alguna de estas dos maneras:

  • Del lado del cliente, mediante el método FB.getLoginStatus() del SDK para JavaScript
  • Del lado del servidor, decodificando una signed_request

Usar el SDK de Facebook para JavaScript

Si llamas a FB.getLoginStatus() al cargar documentos, te aseguras de que un jugador inicie sesión de manera inmediata cuando carga el juego. Luego, puedes usar FB.api() para acceder al estado del juego del jugador mediante el identificador de usuario, y también para recuperar la información utilizada para la personalización, como el nombre del jugador, la foto de perfil y la lista de amigos.

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 el jugador no inició sesión, puedes llamar a FB.login(...) para mostrar una versión modal del cuadro de diálogo de inicio de sesión ubicada en la parte superior de la pantalla inicial de tu juego. La devolución de llamada de este cuadro de diálogo deberá ser el mismo método de llamada que usas al llamar a FB.getLoginStatus.

Usar una solicitud firmada

Cuando se carga tu juego en Facebook.com, se envía una solicitud HTTP POST a la URL de los juegos web de Facebook específica. Esta solicitud POST contendrá, entre otros, el parámetro signed_request, que puedes usar para fines de autorización.

De acuerdo con la especificación de OAuth 2.0, la signed_request está codificada mediante base64url y firmado con una versión HMAC de la clave secreta de la app.

Esto significa es que, cuando se publique en tu app, tendrás que analizarla y verificarla antes de que pueda usarse. Esta acción se realiza en tres pasos:

  1. Divide la solicitud firmada en dos partes delineadas por un carácter "." (p. ej., 238fsdfsd.oijdoifjsidf899)
  2. Decodifica la primera parte, la firma codificada, a partir de base64url
  3. Decodifica la segunda parte, la carga útil, a partir de base64url y, luego, decodifica el objeto JSON resultante

Es posible realizar estos pasos en cualquier lenguaje de programación moderno. A continuación, puedes ver un ejemplo 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, '-_', '+/'));
}

Esto producirá un objeto JSON similar al que se muestra a continuación:

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

Al pasar el parámetro signed_request, podrás detectar si el jugador actual autenticó tu juego. Si realizó la autenticación, la signed_request contendrá el identificador de usuario del jugador, que puedes usar para recuperar la información de personalización y el estado del juego. Puedes cambiar esta signed_request por un token de acceso y usarlo para acceder a la API Graph y obtener una personalización mayor.

Primera autenticación

La primera vez que un jugador juega tu juego, deberás invitarlo a autenticarse mediante el cuadro de diálogo de inicio de sesión. Se recomienda utilizar el proceso de inicio de sesión del cliente mediante el SDK de JavaScript para realizar la autenticación. Los desarrolladores pueden mostrar gráficos de juegos simples antes de lanzar un cuadro de diálogo de inicio de sesión y después de cancelarlo.

Happy Acres, que usa un fondo personalizado al iniciar sesión

Inicio de sesión del cliente a través del SDK de JavaScript

Únicamente en los juegos de Facebook, la versión de JavaScript del cuadro de diálogo de inicio de sesión se activará en modo async dentro del iframe. Esto significa que aparece como una ventana emergente modal por encima del resto del contenido del juego, en lugar de como ventana emergente separada en el navegador.

Esta diferencia es importante, ya que significa que el cuadro de diálogo puede invocarse directamente desde el código y no como parte de un evento de UI, sin que lo bloqueen los métodos de detección de bloqueo emergente del navegador.

En consecuencia, puedes usar FB.getLoginStatus() para comprobar si el jugador actual ya autenticó tu juego; de no ser así, se muestra inmediatamente el cuadro de diálogo de inicio de sesión en la parte superior del contenido del juego si se llama a FB.login(), sin que sea necesario mostrar el botón "Iniciar sesión".

A continuación, te mostramos otro ejemplo:

// 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'});
  }
});

Próximos pasos

Sea cual sea el método que elijas usar para iniciar sesión, tener una identidad real en el juego te ayudará a crear grandes características sociales, que contribuirán a lograr la retención en el juego y su distribución.

El inicio de sesión es el primer paso hacia muchas de estas características, que puedes crear usando los productos que figuran a continuación:

Echa un vistazo a Prácticas recomendadas para juegos en Facebook si quieres obtener más consejos sobre cómo usar el inicio de sesión con Facebook en tu juego de manera efectiva.