Build

Accesso per i giochi su 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.

Quando crei un gioco per Facebook.com, realizzi un'app Web app che verrà caricata all'interno di un contenitore iframe su Facebook.com. Poiché Facebook consente di giocare soltanto a chi ha effettuato l'accesso, un utente Facebook avrà sicuramente eseguito l'accesso e sarà disponibile per l'autenticazione.

Pertanto, devi integrare sempre il supporto di Facebook Login nei tuoi giochi per ottenere un ID coerente in base al quale sincronizzare e salvare i progressi di gioco, oltre che per implementare le funzionalità social che i giocatori si aspettano nei giochi. Se il gioco è disponibile su più piattaforme, puoi usare questo stesso ID per sincronizzare lo stato di gioco sui vari dispositivi usati dai giocatori.

Questo documento illustra i vari approcci all'uso di Facebook Login e le modalità per sfruttarli al meglio nei giochi.

Fonti di autenticazione

Esistono vari modi in cui un giocatore può autenticarsi per la prima volta e diversi metodi per verificare l'identità dopo l'autenticazione iniziale.

Autenticazione tramite App Center

Quando i giocatori avviano il gioco tramite il pulsante Gioca subito in App Center, concedono all'app un determinato insieme di autorizzazioni, secondo quanto specificato nella tab Dettagli dell'app della Dashboard gestione app.

Il pulsante Gioca subito in App Center

Considerando l'elevata percentuale di giocatori che accederà alla tua app tramite App Center, questo sarà un percorso di autenticazione comune. Per garantire un accesso ottimale da App Center, devi configurare l'insieme delle autorizzazioni concesse tramite App Center in modo che corrispondano a quelle richieste su Facebook.com e su mobile.

Per maggiori dettagli, consulta la guida di App Center.

Autenticazione su un'altra piattaforma

Se il gioco è disponibile per le piattaforme mobili e supporta Facebook Login in tali versioni, è possibile che alcuni giocatori risultino già autenticati quando accedono al gioco su Facebook.com. È importante assicurarsi che il gioco su Facebook.com richieda lo stesso insieme di autorizzazioni della versione mobile.

Rilevamento dello stato di accesso

Come descritto sopra, i giocatori accedono al gioco con lo stato Accesso effettuato o Accesso non effettuato, a seconda che abbiano autorizzato o meno il gioco in precedenza, giocando su Facebook, tramite App Center o a una versione mobile.

Puoi rilevare se un giocatore ha già effettuato l'accesso al gioco in due modi:

  • Lato client, tramite il metodo FB. Metodo getLoginStatus() dell'SDK JS
  • Lato server, decodificando una signed_request

Uso dell'SDK di Facebook per JavaScript

Con il richiamo di FB.getLoginStatus() quando si carica il documento, puoi assicurarti che i giocatori effettuino immediatamente l'accesso al caricamento del gioco. Quindi, puoi usare FB.api() per accedere allo stato di gioco del giocatore tramite il suo ID utente e per recuperare le informazioni usate per la personalizzazione, come il nome, l'immagine del profilo e la lista degli amici del giocatore.

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.
  }
 });

Se il giocatore non ha effettuato l'accesso, puoi richiamare FB.login(...) per visualizzare una versione modale della finestra di dialogo Accedi in alto nella schermata iniziale del gioco. La callback della finestra di dialogo deve corrispondere alla chiamata al metodo usata per FB.getLoginStatus.

Uso di una richiesta firmata

Una volta caricato il gioco su Facebook.com, viene effettuata una richiesta HTTP POST all'URL specificato dei giochi Web di Facebook. Questa richiesta POST conterrà alcuni parametri, tra cui il parametro signed_request, utilizzabile per l'autorizzazione.

La signed_request presenta la codifica base64url, con firma creata mediante una versione HMAC della tua chiave segreta, in base alla specifica OAuth 2.0.

Di conseguenza, quando viene pubblicata nell'app, dovrai analizzarla e verificarla prima dell'uso. Questa operazione viene eseguita in tre passaggi:

  1. Suddivisione della richiesta firmata in due parti delimitate da un carattere "." (ad es. 238fsdfsd.oijdoifjsidf899)
  2. Decodifica della prima parte, la firma codificata tramite base64url
  3. Decodifica della seconda parte, il payload, da base64url e successiva decodifica dell'oggetto JSON risultante

Questi passaggi possono essere effettuati in qualsiasi linguaggio di programmazione moderno. Segue un esempio in 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, '-_', '+/'));
}

In questo modo, viene prodotto un oggetto JSON simile al seguente:

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

Analizzando il parametro signed_request, potrai rilevare se il giocatore attuale ha effettuato o meno l'autenticazione del gioco. Se ha effettuato l'autenticazione, la signed_request conterrà l'ID utente del giocatore, che potrai usare per ottenere informazioni per la personalizzazione e lo stato del gioco. Puoi scambiare questa signed_request con un token d'accesso da usare per accedere all'API Graph per una personalizzazione avanzata.

Prima autenticazione

La prima volta che un giocatore accede al gioco, dovresti invitarlo ad autenticarsi visualizzando la finestra di dialogo Accedi. L'accesso lato client tramite l'SDK Javascript è il flusso di accesso consigliato per l'autenticazione. Gli sviluppatori possono presentare semplici elementi grafici del gioco prima dell'apertura di una finestra di dialogo Accedi e dopo la sua chiusura.

Happy Acres, che usa uno sfondo personalizzato all'accesso

Accesso lato client tramite l'SDK JS

La versione per JavaScript della finestra di dialogo Accedi è unica per i giochi su Facebook ed è attivabile in modalità async all'interno del iframe. Di conseguenza, viene visualizzata come finestra pop-up modale sui contenuti del gioco anziché come finestra del browser separata.

Si tratta di un fattore importante, poiché la finestra di dialogo è richiamabile direttamente dal codice e non nell'ambito di un evento dell'interfaccia utente, pertanto non viene bloccata dai sistemi di rilevamento e blocco pop-up dei browser.

Pertanto, puoi usare FB.getLoginStatus() per verificare che il giocatore corrente abbia effettuato l'autenticazione del gioco in precedenza e, in caso negativo, visualizzare immediatamente la finestra di dialogo Accedi al di sopra dei contenuti di gioco chiamando FB.login(), senza dover mostrare un pulsante "Accedi".

Per un esempio, vedi sotto:

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

Passaggi successivi

Indipendentemente dal metodo scelto per l'accesso, disporre di identità reali nel gioco ti aiuta a creare ottime funzionalità social che incentivano la fidelizzazione e la distribuzione del gioco.

L'accesso è il primo passo verso molte altre funzionalità che puoi sviluppare mediante i prodotti seguenti:

Per altri suggerimenti sull'uso efficace di Facebook Login nel tuo gioco, consulta le best practice per i giochi su Facebook.