Richieste dei giochi

Le richieste dei giochi consentono ai giocatori di invitare gli amici a giocare una partita. Tali richieste vengono inviate da un giocatore a uno o più amici e contengono sempre una call to action per il gioco. I destinatari possono essere giocatori nuovi o già esistenti.

Le richieste dei giochi sono utilizzabili per invitare nuovi giocatori o stimolare nuove interazioni da parte di quelli già esistenti. L'invio delle richieste è consentito in due scenari:

1. Il destinatario è un amico del mittente e non ha effettuato l'autenticazione del gioco. Questo è un ottimo scenario per gli inviti.
2. Il destinatario è un amico del mittente e ha già effettuato l'autenticazione del gioco. Questo scenario è ideale per le notifiche relative ai turni e le richieste di aiuto.

Le richieste vengono inviate mentre il mittente sta giocando e visualizzate dai destinatari in vari punti di Facebook. Le richieste sono sempre private e sono visualizzabili esclusivamente dal destinatario. Sebbene sia possibile inviare una richiesta a più destinatari contemporaneamente, chi la riceve visualizza solo le informazioni sul mittente e in nessun caso può accedere a quelle sugli altri destinatari.

Un esempio di richiesta dei giochi visualizzata su Facebook per computer.

Le richieste dei giochi sono disponibili per Giochi su Facebook e giochi mobili su iOS e Android. Sul sito di Facebook per computer, le richieste vengono visualizzate in una finestra pop-up con segnale acustico in basso a sinistra sullo schermo e nell'icona delle notifiche, se non sono filtrate. Sulle piattaforme mobili, le richieste vengono visualizzate nell'elenco delle notifiche dell'app Facebook, se non sono filtrate. I dati delle richieste sono disponibili tramite l'API Game Request, con la possibilità di creare interfacce utente personalizzate per una maggiore integrazione all'interno dei giochi mobili. Per questo motivo, l'implementazione delle tue richieste deve essere indipendente dalla piattaforma e offrire un'esperienza utente coerente in ogni caso. Tuttavia, gli inviti inviati dal giocatore saranno visualizzati su tutte le piattaforme supportate dal gioco.

Avvio della finestra di dialogo delle richieste

La finestra di dialogo per la richiesta dei giochi viene generata tramite JavaScript, iOS, Android e l'SDK per Unity. In questi esempi si presuppone che il mittente abbia già effettuato l'autenticazione dell'app. Se non vengono specificati destinatari, puoi filtrare la lista di amici fino a un massimo di 50 nominativi e suddividerla per giocatori registrati o amici che non hanno ancora eseguito la registrazione. In questo modo, puoi creare due flussi separati per invitare nuovi giocatori o stimolare nuove interazioni da parte di quelli esistenti.

JavaScript

Invio di richieste tramite lo strumento di multi-selezione amici fornito dalla finestra di dialogo per la richiesta dei giochi:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE'
}, function(response){
  console.log(response);
});

Alla chiusura della finestra, l'oggetto response contiene i risultati dell'invio, compreso un ID request e un array di destinatari to. Ad esempio:

{
  "request":"1428237347457728",
  "to":["10150002163885335"]
}

Per impostazione predefinita, il mittente ha a disposizione uno strumento di multi-selezione amici con un massimo di 50 destinatari selezionabili.

Invio di richieste a un destinatario specifico:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID'
}, function(response){
  console.log(response);
});

Se viene specificato il campo to, il mittente non può selezionare ulteriori destinatari.

Invio di richieste a più destinatari specifici:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID, USER_ID, USER_ID'
}, function(response){
  console.log(response);
});

È possibile specificare più destinatari con un elenco separato da virgole contenente gli ID utente.

Invio di richieste a liste di amici specifiche:

FB.ui({method: 'apprequests',
  message: 'Friend Smash Request!',
  filters: [{name:'GROUP_1_NAME', user_ids:['USER_ID','USER_ID','USER_ID']},{name:'GROUP_2_NAME', user_ids: ['USER_ID','USER_ID','USER_ID']}]
}, function(response){
  console.log(response);
}});

Invio di oggetti tramite richieste, attraverso la dichiarazione esplicita di un action_type e un object_id:

FB.ui({method: 'apprequests',
  message: 'Take this bomb to blast your way to victory!',
  to: {user-ids},
  action_type:'send',
  object_id: 'YOUR_OBJECT_ID'  // e.g. '191181717736427'
}, function(response){
  console.log(response);
});

Per le richieste relative ai turni, non specificare un object_id.

FB.ui({method: 'apprequests',
  message: 'Just smashed you 78 times! It\'s your turn.',
  to: {user-ids},
  action_type:'turn'
}, function(response){
  console.log(response);
});

In alternativa, i destinatari sono suddivisibili in liste denominate che consentono ai giocatori di selezionare gli amici da gruppi organizzati secondo una certa logica e secondo lo stato all'interno del gioco.

Per maggiori informazioni, consulta la documentazione di riferimento di FB.ui per l'SDK di Facebook per JavaScript.

SDK iOS

Avvio della finestra di dialogo delle richieste tramite lo strumento di multi-selezione amici fornito dall'SDK per iOS:

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
// Look at FBSDKGameRequestContent for futher optional properties
gameRequestContent.message = @"YOUR_MESSAGE_HERE";
gameRequestContent.title = @"OPTIONAL TITLE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

Invio di richieste con dichiarazione esplicita di un action_type e un object_id a un destinatario specifico mediante l'SDK per iOS:

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
gameRequestContent.message = @"Take this bomb to blast your way to victory!";
gameRequestContent.to = @[@"RECIPIENT_USER_ID"];
gameRequestContent.objectID = @"YOUR_OBJECT_ID";
gameRequestContent.actionType = @"ACTION_TYPE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

Android SDK

Invio di una richiesta tramite lo strumento di selezione amici della finestra di dialogo delle richieste mediante l'Android SDK:

GameRequestDialog requestDialog;
CallbackManager callbackManager;

public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  FacebookSdk.sdkInitialize(this.getApplicationContext());
  callbackManager = CallbackManager.Factory.create();
  requestDialog = new GameRequestDialog(this);
  requestDialog.registerCallback(callbackManager,
    new FacebookCallback<GameRequestDialog.Result>() {
    public void onSuccess(GameRequestDialog.Result result) {
      String id = result.getId();
    }
    public void onCancel() {}
      public void onError(FacebookException error) {}
    }
  );
}

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .build();
  requestDialog.show(content);
}

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  callbackManager.onActivityResult(requestCode, resultCode, data);
}

Invio di una richiesta con dichiarazione esplicita di un'azione e di un oggetto mediante l'Android SDK:

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .setTo("USER_ID")
    .setActionType(ActionType.SEND)
    .setObjectId("YOUR_OBJECT_ID")
    .build();
  requestDialog.show(content);
}

SDK Unity

Ecco come si eseguono le richieste nell'SDK per Unity. Per maggiori informazioni, consulta la documentazione di FB.AppRequest.

FB.AppRequest(
  message: "I Just got " + GameStateManager.Score.ToString() + " points! Can you beat it?",
  to: recipients,
  data: "{\"challenge_score\":" + GameStateManager.Score.ToString() + "}"
  title: "Friend Smash Challenge!",
  callback:appRequestCallback
);

Parametri della finestra di dialogo

La creazione della finestra di dialogo per la richiesta dei giochi può includere alcuni parametri aggiuntivi che ne determinano il funzionamento. Questi parametri sono descritti di seguito.

Dati di risposta

Quando viene inviata una richiesta mediante la finestra di dialogo per la richiesta dei giochi, la callback riceve una risposta con le informazioni seguenti:

Gestione delle richieste all'interno del gioco

Accettazione delle richieste

Quando un destinatario accetta una richiesta sul sito di Facebook per computer, viene indirizzato all'URL del gioco che ha inviato tale richiesta. Questo URL contiene un parametro GET aggiuntivo request_ids, ovvero un elenco separato da virgole relativo agli ID delle richieste accettate dall'utente:

http://apps.facebook.com/[app_name]/?request_ids=[REQUEST_IDs]

Le richieste accettate dal destinatario non vengono eliminate automaticamente. Questa operazione deve essere eseguita dal gioco. Un approccio comune prevede che, al suo avvio, un gioco ottenga dall'API Graph la lista delle richieste in sospeso per l'utente e che le elimini dopo l'elaborazione.

Quando un destinatario accetta una richiesta su una piattaforma mobile, questa attiva un deep link verso l'app. Un altro parametro presente al caricamento dell'app è l'ID della richiesta. La procedura di accettazione ed eliminazione delle richieste è valida anche per il mobile. Ti consigliamo di controllare ed eliminare le richieste all'avvio del gioco.

Lettura delle richieste

Le richieste inviate presentano un ID oggetto della richiesta unico. Tale ID rappresenta l'oggetto della richiesta. Puoi creare un'istanza della richiesta specifica concatenando l'ID oggetto della richiesta con l'ID utente di un destinatario. In questo modo si crea un'istanza della richiesta, inviata a un destinatario specifico.

Ad esempio, all'invio di una richiesta, la risposta proveniente dalla finestra di dialogo delle richieste dei giochi avrà un aspetto simile al seguente:

{
  request: 'REQUEST_OBJECT_ID'
  to:[array of USER_IDs]
}

Se cerchi l'ID oggetto della richiesta mediante l'API Graph, la risposta ottenuta sarà leggermente diversa a seconda del contesto di visualizzazione della ricerca stessa, tuttavia la risposta rappresenterà sempre l'intero oggetto della richiesta.

Ad esempio, nel caso di una query a http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKEN eseguita con il token d'accesso dell'utente del destinatario, visualizzerai la risposta seguente:

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

Tieni presente che vengono restituiti entrambi i campi to e from. Tuttavia, se la chiamata allo stesso endpoint viene eseguita mediante il token d'accesso del mittente o dell'app, Facebook restituisce quanto segue:

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

Per ottenere l'intera richiesta, comprensiva del destinatario, tramite il token d'accesso dell'app, devi aggiungere l'ID utente del destinatario, seguito da un trattino basso "_". Ad esempio, una chiamata a https://graph.facebook.com/{REQUEST_OBJECT_ID}_{USER_ID}?access_token={APP_ACCESS_TOKEN} restituisce:

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

Lettura di tutte le richieste

Per leggere tutte le richieste di un destinatario, puoi eseguire una query in Graph come illustrato di seguito, tramite lo USER ACCESS TOKEN del destinatario. In questo modo ottieni una lista di ID delle richieste di tale utente nell'app.

GET https://graph.facebook.com/me/apprequests?access_token=[USER ACCESS TOKEN]

Eliminazione delle richieste

Le richieste dei giochi non vengono eliminate automaticamente dopo l'accettazione da parte del destinatario. Spetta allo sviluppatore eliminare la richiesta dopo l'accettazione. Devi eliminare le richieste per conto dei giocatori dopo che questi le hanno accettate.

Per eliminare le richieste, hai a disposizione i metodi seguenti:

API Graph

Esegui una richiesta HTTP DELETE al request_id concatenato:

DELETE https://graph.facebook.com/[{REQUEST_OBJECT_ID}_{USER_ID}]?
      access_token=[USER or APP ACCESS TOKEN]

JavaScript

function deleteRequest(requestId) {
  FB.api(requestId, 'delete', function(response) {
    console.log(response);
  });
}

Monitoraggio delle richieste per raccomandazioni e premi

Puoi premiare chi invia le richieste dei giochi in base a determinate azioni eseguite dal destinatario in risposta a esse. Ad esempio, non puoi premiare i giocatori solo per aver inviato richieste, ma se il destinatario installa il gioco e raggiunge un determinato livello dopo aver accettato la richiesta, puoi assegnare un premio al mittente.

Per premiare un mittente, devi conoscerne l'identità. Hai a disposizione due modi per farlo:

1. Durante l'invio della richiesta, memorizza il request_id restituito nella risposta proveniente dalla finestra di dialogo delle richieste dei giochi e, alla ricezione, associala al mittente per premiarlo.
2. Leggi tutte le richieste relative a un giocatore all'avvio del gioco e premia il mittente in base all'id nel campo from delle richieste. Se più di un amico ha inviato un giocatore, puoi decidere di premiare solo il primo o tutti i mittenti.

API Invitable Friends

Localizzazione

Per aiutarti a garantire la migliore esperienza possibile per gli utenti di tutto il mondo, Facebook supporta la localizzazione delle requests. Prima di tradurre le richieste, è importante che tu conosca i vari tipi in cui si suddividono e come vengono visualizzate. Le richieste sono visualizzabili come messaggio standard "Anita sent you a request" o, se hai specificato una coppia azione/oggetto, "Anita asked you for a Life" o "Anita sent you a Bomb". Inoltre, è disponibile una richiesta relativa ai turni per informare i giocatori che è giunto il loro turno nelle partite contro gli amici. Tutti questi esempi vengono visualizzati dai giocatori che hanno autorizzato il gioco. Se il destinatario non ha ancora installato il gioco, visualizzerà la richiesta sotto forma di invito. Ad esempio "Anita invited you to play Friend Smash!". Vediamo come vengono tradotte queste richieste.

Traduzione degli inviti

Il testo degli inviti viene tradotto automaticamente da Facebook e non è controllabile da parte degli sviluppatori. La traduzione viene eseguita nella lingua del destinatario.

Notifica dell'invito in lingua inglese

Notifica dell'invito in lingua thailandese

Tieni presente che negli esempi precedenti, il testo "invited you to play" viene tradotto automaticamente in un'altra lingua, in questo caso in thailandese. Il nome e la descrizione dell'app vengono tradotti nella sezione Localizzazione delle impostazioni dell'app, come ad esempio Nome visualizzato e Descrizione, nelle caselle gialle illustrate di seguito.

Traduzione del nome visualizzato e della descrizione dell'app

Le richieste sono visualizzabili anche nell'App Center. Nell'App Center viene visualizzato il messaggio della richiesta. Tale messaggio può essere tradotto dallo sviluppatore. Nell'esempio seguente, il messaggio è "Can I have a life to help me through the next level?" in inglese e "ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า" in thailandese. Al momento, il testo principale della richiesta, ossia "Anita sent you a request", non viene visualizzato nell'App Center.

Richiesta nell'App Center in inglese

Richiesta nell'App Center in thailandese

Traduzione del messaggio

Poiché il messaggio viene passato come parametro al momento della chiamata della finestra di dialogo della richiesta, puoi tradurlo personalmente prima di tale chiamata e inserire la stringa tradotta come messaggio. Per modificare la traduzione in modo dinamico, devi eseguire l'operazione prima di chiamare la finestra di dialogo. Sei tu a decidere la lingua da visualizzare, poiché si tratta dello stesso testo visto dal mittente nell'anteprima della richiesta e dal destinatario al momento della ricezione.

Diversi sviluppatori rilevano la lingua del mittente per stabilire quale lingua usare nel messaggio. Il presupposto è che nella maggior parte dei casi il mittente e il destinatario parlano la stessa lingua. Nell'esempio precedente, avresti potuto rilevare la lingua del mittente, in questo caso il thailandese, e inviare il messaggio direttamente in tale lingua in questo modo:

FB.ui({method: 'apprequests',
  message: 'ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า'
}, requestCallback);

Best practice

Aggiunta di dati a una richiesta

Come già indicato nella sezione Parametri della finestra di dialogo sopra, puoi aggiungere ulteriori dati da inviare con la richiesta, con un limite massimo di 255 caratteri. In questo modo, puoi trasmettere ulteriori informazioni sulla richiesta o aggiungere un identificatore, utile per ricercare in un secondo momento le informazioni pertinenti memorizzate nel server.

Ad esempio, nel progetto del gioco di esempio di Facebook Friend Smash, i giocatori si sfidano a turno per "distruggere" il maggior numero di amici possibile. Quando un giocatore invia una sfida tramite una richiesta, il parametro dei dati viene usato per memorizzare il punteggio più recente dello sfidante. A questo punto, il gioco estrae tale valore per il giocatore sfidato e lo imposta come punteggio da raggiungere per la partita successiva.

Filtri per gli inviti

Durante la creazione di uno strumento di multi-selezione amici o comunque durante la selezione dei destinatari delle richieste, potresti mettere a disposizione alcuni filtri per aiutare i giocatori a selezionare i destinatari.

Un filtro comune usato durante l'implementazione degli inviti tramite la finestra di dialogo per la richiesta dei giochi è app_non_users. Questo filtro impedisce alla finestra di dialogo di visualizzare chi ha già provato il gioco. Puoi prendere in considerazione altri filtri, come ad esempio i giocatori con cui si è interagito di recente o utenti di giochi simili sotto il tuo controllo. Per un elenco completo dei filtri disponibili, consulta la documentazione di riferimento sui parametri della finestra di dialogo delle richieste dei giochi.

Creazione di meccanismi coinvolgenti

Crea meccanismi in grado di coinvolgere i giocatori quando visitano gli amici nel gioco o interagiscono direttamente con loro. Ad esempio, se nel gioco è previsto il concetto di vicinato, offri energia gratuita ai giocatori che visitano gli ambienti dei vicini. Se la base di un giocatore è sotto attacco, consenti agli amici di ripararla. In generale, i giocatori apprezzano la possibilità di aiutare gli amici a progredire nel gioco, pertanto consentire loro di farlo genera un'eccellente esperienza social che incoraggia altri giocatori a partecipare.

Oggetti preziosi per i giocatori

Offri al giocatore oggetti utili e di valore che possano potenziare il gioco o migliorare l'esperienza social.

Segmentazione dei giocatori e richieste contestuali

Valuta i giocatori e suddividili in vari gruppi pertinenti per il tuo gioco (ad es. nuovi giocatori, creatori di oggetti, giocatori con molti amici, utenti che interagiscono molto e così via). Pensa a cosa potrebbe essere utile ai giocatori in base al loro livello e offri oggetti specifici per i vari segmenti.