Thread-Kontext

SDK für Messenger-Erweiterungen

Diese Methode gehört zum SDK für Messenger-Erweiterungen. Informationen dazu, wie du das SDK in deine Webseite aufnimmst, findest du unter SDK für Messenger-Erweiterungen hinzufügen.

Verfügbarkeit

Diese API ist nur in Messenger v113 und höher auf Android und v114 und höher auf iOS verfügbar.

Um die Verfügbarkeit für einen bestimmten Client zu überprüfen, rufe getSupportedFeatures() auf und suche in der Antwort nach der Eigenschaft context.

Mit der getContext()-Methode werden zusätzliche Informationen zur Person und dem Thread abgerufen, über den die Webansicht geöffnet wurde. Die Methode eignet sich gut für interaktive Gruppenerfahrungen und Spiele sowie zur Einschränkung von Inhalten, die nur in einem bestimmten Thread geteilt werden sollen.

getContext() sollte anstelle von getUserID() verwendet werden, da dies inzwischen veraltet ist.

Abrufen von Thread-Kontext
Validierung der signed_request
Verwendung von Thread-IDs mit globalen Seiten

Abrufen von Thread-Kontext

Rufe diese Funktion auf, um die Nutzer-ID (seitenspezifische ID), Thread-ID und Thread-Art zu erhalten. Eine vollständige Liste der Methodenparameter findest du unter getContext() Reference.

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

Antwortformat

Als Antwort wird ein JavaScript-Objekt im folgenden Format an den Erfolgs-Callback weitergegeben:

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

Validierung der `signed_request`

In manchen Situationen möchtest du möglicherweise die aus getContext() erhaltenen Informationen in dein Backend übertragen und validieren, bevor du eine Handlung wie eine Anmeldung oder einen Kauf durchführst. Dadurch kannst du sicherstellen, dass die Informationen tatsächlich von Messenger stammen und nicht gefälscht sind.

Der signed_request-Parameter ist base64url-kodiert und mit einer HMAC-Version deines App-Geheimcodes auf Basis der OAuth 2.0-Spezifikation signiert.

Du kannst ihn mit den folgenden vier Schritten validieren:

Teile die signierte Anfrage in zwei Teile, getrennt durch das Zeichen '.' (z. B. 238fsdfsd.oijdoifjsidf899).
Dekodiere den ersten Teil – die kodierte Signatur – der base64url-Kodierung.
Dekodiere den zweiten Teil – die Payload – der base64url-Kodierung. Bei Bedarf kannst du dies serverseitig durchführen.
Hashe die ursprüngliche Payload mit HMAC SHA-256 und deinem App-Geheimcode und prüfe, ob sie mit der codierten Signatur übereinstimmt, die ursprünglich weitergegeben wurde.
Du kannst auch den issued_at-Zeitstempel der Payload validieren, um sicherzustellen, dass die Anfrage kürzlich gestellt wurde.

Dies ist in jeder modernen Programmiersprache möglich. Nachfolgend ein Beispiel 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, '-_', '+/'));
}

Wenn du die Payload dekodierst, erhältst du ein Objekt mit denselben Informationen, die ursprünglich von getContext() zurückgegeben wurden. Es enthält außerdem die Felder algorithm, issued_at und page_id:

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

Achte darauf, die Validierung auf deinem Server und nicht in clientseitigem Code durchzuführen, um deinen App-Geheimcode nicht versehentlich preiszugeben.

Verwendung von Thread-IDs mit globalen Seiten

Manche Unternehmen verwenden eine globale Seitenstruktur mit mehreren Seiten, die mit einer App-ID oder einem Bot verknüpft sind. In diesem Fall gibt getContext() in der Chat-Erweiterung unterschiedliche Thread-IDs zurück, je nachdem, in welchem Land sich der Nutzer befindet.

Mit der folgenden API kannst du die landesspezifische Thread-ID in eine globale Thread-ID auflösen und mit dieser ID den Status für Nutzer beibehalten, die über ihre jeweiligen regionalen Seiten auf die Chat-Erweiterung zugreifen.

Abrufen der globalen Thread-ID:

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

Beispielantwort:

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