Contesto della conversazione

SDK per le estensioni di Messenger

Questo metodo rientra nell'SDK per le estensioni di Messenger. Per informazioni su come includere l'SDK sul tuo sito, consulta Aggiunta dell'SDK per le estensioni di Messenger.

Disponibilità

Questa API è disponibile solo a partire dalla versione 113 di Messenger per Android e dalla versione 114 per iOS.

Per verificarne la disponibilità in un determinato client, chiama getSupportedFeatures() e controlla la proprietà context nella risposta.

Il metodo getContext() recupera informazioni aggiuntive sull'utente e sulla conversazione che ha aperto la visualizzazione web. È utile per la creazione di esperienze di gruppo interattive e dei giochi, nonché per limitare la presentazione dei contenuti che devono essere condivisi solo in una determinata conversazione.

Usa getContext() anziché getUserID(), poiché è diventato obsoleto.

Recupero del contesto della conversazione
Convalida dell'elemento signed_request
Uso degli ID conversazione con le Pagine globali

Recupero del contesto della conversazione

Chiama questa funzione per ottenere il PSID dell'utente, l'ID conversazione e il tipo di conversazione. Per una lista completa dei parametri del metodo, consulta il riferimento per getContext().

MessengerExtensions.getContext('YOUR_APP_ID', 
  function success(thread_context){
    // success
  },
  function error(err){
    // error
  }
);

Formato della risposta

La risposta passata alla callback dell'azione eseguita correttamente è un oggetto JavaScript nel formato seguente:

{
  "thread_type": "GROUP",
  "tid": "1411911565550430",
  "psid": "1293479104029354",
  "signed_request": "5f8i9XXH2hEaykXHKFvu-E5Nr6QRqN002JO7yl-w_9o.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwNDA0NjM4MCwicGFnZV9pZCI6NjgyNDk4MTcxOTQzMTY1LCJwc2lkIjoiMTI1NDQ1OTE1NDY4MjkxOSIsInRocmVhZF90eXBlIjoiVVNFUl9UT19QQUdFIiwidGlkIjoiMTI1NDQ1OTE1NDY4MjkxOSJ9"
}

Convalida dell'elemento `signed_request`

In alcuni casi, potresti aver bisogno di trasmettere le informazioni ottenute da getContext() al tuo sistema di back-end e convalidarle prima di eseguire alcune azioni, ad es. l'accesso o un acquisto. In questo modo, puoi verificare che le informazioni provengano effettivamente da Messenger e che non abbiano subito manomissioni.

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.

Puoi effettuare la convalida con i 4 passaggi seguenti:

Suddivisione della richiesta firmata in due parti delimitate da un carattere '.' (ad es 238fsdfsd.oijdoifjsidf899).
Decodifica della prima parte, la firma codificata tramite codifica base64url.
Decodifica della seconda parte, il payload, tramite la codifica base64url. Se necessario, puoi farne uso sul lato server.
Hashing del payload originale tramite HMAC SHA-256 e della chiave segreta, confermandone la corrispondenza con la firma codificata passata in origine.
Convalida facoltativa di data e ora di issued_at nel payload, per garantire che la richiesta sia recente.

Questa procedura è realizzabile con qualsiasi linguaggio di programmazione moderno. Ecco 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, '-_', '+/'));
}

La decodifica del payload produrrà un oggetto contenente le stesse informazioni di quello restituito da getContext() in origine, con l'aggiunta dei campi algorithm, issued_at e page_id:

{
  "psid": "1293479104029354", 
  "algorithm": "HMAC-SHA256", 
  "thread_type": "GROUP", 
  "tid": "1411911565550430", 
  "issued_at": 1491351619, 
  "page_id": 167938560376726
}

Tieni presente che, per evitare di divulgare la tua chiave segreta per errore, questa convalida deve avvenire nel codice sul lato del tuo server, mai sul lato client.

Uso degli ID conversazione con le Pagine globali

Alcune aziende usano una struttura di tipo Pagina globale, con più Pagine associate a un unico ID app o bot. In questo caso, gli ID conversazione restituiti da getContext() nell'estensione della chat variano in base al Paese in cui si trovano gli utenti.

Usa l'API seguente per risolvere l'ID conversazione specifico della Pagina in base al Paese in un ID conversazione globale e usa quest'ultimo per mantenere lo stato per i vari utenti che accedono all'estensione della chat dalle rispettive Pagine locali.

Recupera l'ID conversazione globale:

curl -X GET "https://graph.facebook.com/v2.6/{thread-id}?access_token=<PAGE_ACCESS_TOKEN>"

Esempio di risposta:

    {"tid":1577059318985661,"global_tid":1577059318985661}