Authentifizierte Vorschau

Übersicht

Über die authentifizierte Vorschau werden deine Inhalte korrekt auf Workplace angezeigt. Dazu gehört der Support für Metadaten für die authentifizierte Vorschau in einem von Workplace erwarteten Format, sodass Workplace beim Teilen von URLs zu deinem Content diese Metadaten abrufen und eine Vorschau erstellen kann. Dieser Vorgang wird oft als Link-Unfurling bezeichnet.

Während Facebook Metadaten zum Unfurling einer öffentlichen URL über das Open Graph-Protokoll und den Facebook Crawler abrufen kann, steht dieser Prozess nicht für private URLs zur Verfügung. Allerdings werden diese häufiger in Workplace geteilt. Wenn jemand eine private URL in Workplace teilt, wird ein Webhook an eine von dir definierte Callback-URL ausgegeben. Du kannst dann mit einer Metadaten-Payload antworten, die die URL für die teilende Person beschreibt, um eine Linkvorschau darzustellen.

Dieser Prozess wird für jede Person wiederholt, die die geteilte URL auf Workplace anzeigt. So kannst du die Sichtbarkeit der Vorschau für jede*n Nutzer*in steuern.

Mit der authentifizierten Vorschau für Workplace können Personen Informationen sicher und einfach auf Workplace teilen und dabei das Quellmaterial schützen. Indem du die authentifizierte Vorschau unterstützt, stellst du sicher, dass die Vorschau deiner Inhalte korrekt auf Workplace angezeigt wird – auf sichere Weise und unter Einhaltung des Datenschutzes.

Teilen privater URLs

Workplace-Nutzer teilen oft Links zu internen Unternehmensressourcen, die nur für bestimmte Personen einsehbar sein sollen. Auf Facebook teilen die Menschen dagegen meist öffentliche Inhalte wie Zeitungsartikel oder Blog-Posts.

Öffentliche und private URLs in Workplace

Damit Workplace eine Vorschau von firmeneigenen Inhalten generieren kann, müssen einige Metadaten angegeben werden. Du kannst als Anbieter festlegen, ob du Metadaten für aktuelle Betrachter auf Workplace bereitstellst, je nachdem, ob diese zur Anzeige des Contents berechtigt sind oder nicht.

Inhalt dieses Dokuments

In diesem Dokument werden die Komponenten für die authentifizierte Vorschau beschrieben, darunter:

• Authentifizierte Vorschau
• Identitätszuordnung

Konfiguration

Um die authentifizierte Vorschau zu aktivieren, musst du Folgendes in deiner App konfigurieren:

• Die App muss in einer Workplace-Community oder in mindestens einer Gruppe installiert sein.
• Sie benötigt die Berechtigung Link-Unfurling.
• Konfiguriere eine Domain oder eine Gruppe aus Domains für die URLs, die von deiner Integration angezeigt werden.
• Richte ein Abonnement des Webhook-Themas „Link“ sowie für das Feld „preview“ und eine Callback-URL zum Angeben von Metadaten ein.

Webhooks

Empfangen von Webhooks

In mehreren Situationen senden wir eine Anfrage an den Provider:

1. Wenn eine neue URL geteilt wird, die noch nicht vorgekommen ist (immer über das Eingabefeld).
2. Wenn neue Nutzer Content sehen und wir nicht wissen, ob sie Zugriff darauf haben (immer über den Feed).
3. Wenn vorhandener Content erneut geteilt wird oder abgelaufen ist (über das Eingabefeld oder den Feed).

Format der Webhook-Anfrage

In allen der oben genannten Szenarien wird ein Webhook im folgenden Format als POST-Anfrage gesendet:

{
  "object": "link",
  "entry": [
    {
      "time": int,
      "changes": [
        {
          "field": "preview",
          "value": {
            "community": {
              "id": string,
            },
            "user": {
              "id": string,
            },
            "link": string,
          }
        }
      ]
    }
  ]
}
    

Diese Payload enthält die folgenden Felder:

Beispiel

POST /callback HTTP/1.1
Host: third-party.com
Accept: application/json
Content-Type: application/json
User-Agent: Webhooks/1.0 (https://fb.me/webhooks)
X-Hub-Signature: sha1=bf3102e52efd0fd4bd26277030aa180d7b5cf587
...

{
    "object": "link",
    "entry": [{
        "time": 1501515097793,
        "changes": [{
            "field": "preview",
            "value": {
                "community": {
                    "id": "138169208138649"
                },
                "user": {
                    "id": "88575656148087"
                }
                "link": "https://company.third-party.com/document-about-this"
            }
        }]
    }]
}
    

Format der Webhook-Antwort

Wenn du eine Webhook-Anfrage erhältst, musst du eine Metadaten-Payload in einem bestimmten Antwortformat angeben:

{
  "data": [
    {
      "link": string,
      ?"canonical_link": string,
      ?"title": string,
      ?"description": string,
      ?"icon": string,
      ?"download_url": string,
      "privacy": 'organization' | 'accessible' | 'inaccessible',
      ?"type": 'document' | 'folder' | 'task' | 'link',
      ?"additional_data": [
        {
          "title" => string,
          "format" => 'text' | 'date' | 'datetime' | 'user',
          "value" => string | number,
          ?"color" => 'blue' | 'green' | 'yellow' | 'orange' | 'red',
        },
      ],
    }
  ],
  ?"linked_user": boolean
}

Diese Payload muss die folgenden Felder enthalten:

Vollständiges Antwortbeispiel

HTTP/1.1 200 OK
Content-Type: application/json
X-Hub-Signature: sha1=b5a6f32f084100ae5b355174b9bb8398f5fbe983
...

{
  "data": [
    {
      "link": "https://taaskly.herokuapp.com/task/4",
      "title": "Launch Workplace Integration for F8",
      "privacy": "organization",
      "type": "task",
      "additional_data": [
        {
          "title": "Owner",
          "format": "user",
          "value": "319922278498384"
        },
        {
          "title": "Created",
          "format": "datetime",
          "value": "2018-02-28T03:35:40.827Z"
        },
        {
          "title": "Priority",
          "format": "text",
          "value": "high",
          "color": "red"
        }
      ]
    }
  ],
  "linked_user": true
}
    

Datenschutzmodi

Der Datenschutzmodus bestimmt die Sichtbarkeit und legt fest, ob eine Nutzerauthentifizierung für aktuelle und nachfolgende Nutzer erforderlich ist.

1. organization: Für Nutzer sichtbar, keine Authentifizierung erforderlich
   Wenn das Element für Nutzer sichtbar ist, können wir den Inhalt direkt anzeigen. In diesem Fall soll ein Inhaltselement für alle Nutzer in der Domain (im Unternehmen) sichtbar sein. Dann senden wir nicht jedes Mal, wenn neue Personen den neuen Content ansehen, einen Webhook.
2. accessible: Für aktuellen Nutzer sichtbar, für andere Personen ist aber möglicherweise eine Identitätszuordnung erforderlich
   Der Provider weiß, dass dieser Nutzer dieses Inhaltselement sehen darf. Das bedeutet aber nicht unbedingt, dass jede andere Person es auch einsehen kann. Wir zeigen die Vorschau an, senden aber weiterhin Webhooks für andere Nutzer.
3. inaccessible: Nicht für Nutzer sichtbar
   Der Provider kennt die Person und weiß, dass diese den Inhalt nicht ansehen darf. In diesem Fall zeigen wir einen Datenschutzhinweis an (nicht verfügbar, privat usw.).

Zusätzliche Daten

Um einer Linkvorschau weitere Informationen hinzuzufügen, kannst du bis zu drei Elemente mit zusätzlichen Daten senden. Ein zusätzliches Datenelement besteht aus einem Satz aus Schlüssel/Wert-Elementen. Der Wert kann aber auf unterschiedliche Arten formatiert werden.

Derzeit werden vier verschiedene Formate unterstützt:

• text: Zeigt den Wert im vorliegenden Zustand („as is“) an. Der Wert muss ein String sein. Bei diesem Format können zusätzliche Daten auch die Eigenschaft color mit einem der folgenden Werte enthalten: blue, green, yelloworange oder red. Dann wird der Wert mit der jeweiligen Farbe als Hintergrund gerendert.
• date: Parst den Wert als ISO-8601-Datumsformat ohne Uhrzeit und zeigt ihn ohne Uhrzeitangabe an.
• datetime: Parst den Wert als ISO-8601-Datumsformat mit Uhrzeit und Zeitzone und rendert ihn mit Uhrzeitangabe in der Zeitzone der Nutzer.
• user: Parst den Wert als Nutzer-ID und zeigt den Benutzernamen an.

Der Parameter download_url wird ignoriert, wenn du zusätzliche Daten festlegst.

Rendering von Dateivorschau (optional)

Wenn als Datenschutzmodus für deine Dokumente organization oder accessible angegeben ist und eine Download-URL angegeben wurde, senden wir eine zusätzliche Anfrage zum Herunterladen der Daten.

GET /download/super-fancy-document HTTP/1.1
Host: provider.com
Accept: <some mime types>
User-Agent: Webhooks/1.0 (https://fb.me/webhooks)
X-Hub-Signature: sha1=bf3102e52efd0fd4bd26277030aa180d7b5cf587

Anschließen konvertiert Workplace diese Datei in Fotos, um einen Beitrag mit mehreren Fotos daraus zu machen.

Identitätszuordnung

Für die authentifizierte Vorschau ist wie oben angegeben eine Art der Identitätszuordnung erforderlich. Die Identitätszuordnung steuert, ob ein Workplace-Nutzer zur Anzeige des Vorschau-Contents berechtigt ist, und stellt sicher, dass die Zugriffsregeln deines Inhalts auf Workplace eingehalten werden.

Organisationsweite Zuordnung

Die einfachste Art der Identitätszuordnung ist die organisationsweite Zuordnung. Dabei reicht es aus, zu einer Workplace-Community zu gehören, damit die Vorschau für Nutzer auf Workplace angezeigt wird. Dieses Szenario gilt häufig für die Vorschau von Links in einem unternehmensweiten Intranet oder Services, bei denen alle Objekte (oder zumindest deren Metadaten) für das ganze Unternehmen sichtbar sind.

Wenn deine Integration in einer Workplace-Community installiert ist, kannst du die Community-ID über den /community-Endpunkt prüfen. Dazu nutzt du den Zugriffstoken, den du bei der Installation abgerufen hast. Diese Community-ID kannst du zusammen mit dem Token speichern und einer Mandanten- oder Organisations-ID in deinem Service zuordnen. Dadurch wird eine Zuordnung zwischen einer Workplace-Community und der Organisation in deinem Service erstellt.

Beim Antworten auf Webhook-Anfragen zur authentifizierten Vorschau kannst du dann prüfen, ob die Community-ID der Webhook-Payload mit der Community-ID übereinstimmt, die mit der Organisation verknüpft ist, und bestimmen, ob eine Metadaten-Payload zurückgegeben werden soll. Wenn du den Datenschutz dieser Payload als ORGANIZATION angibst, müssen wir keine zusätzlichen Webhooks für jeden Nutzer in dieser Workplace-Community senden.

Zuordnung einzelner Nutzer

Wenn du genauere Berechtigungen erteilen möchtest, kannst du die Zuordnung einzelner Nutzer unterstützen. Damit kannst du für jeden Betrachter auf Workplace einzeln festlegen, ob Metadaten gerendert werden. Workplace sendet eine Nutzer-ID in jeder Webhook-Payload für die authentifizierte Vorschau. Für die Zuordnung einzelner Nutzer musst du wissen, welcher Nutzerdatensatz in deinem System der in der Webhook-Payload gesendeten Workplace-Nutzer-ID zugeordnet ist.

Wenn eine Workplace-Nutzer-ID zum ersten Mal vorkommt, kannst du das boolesche Feld linked_user auf false setzen. Dadurch zeigt Workplace den Button Vorschau aktivieren an, sodass Nutzer aufgefordert werden, ihr Konto zu verknüpfen.

Beim Klicken auf den Button öffnet Workplace einen Dialog zu einem von dir definierten Kontoverknüpfungs-Endpunkt, an dem du die Nutzersitzung in deinem Service validieren kannst. Workplace öffnet diese URL über eine POST-Anfrage und übergibt einen signierten Anfrageparameter, der die aktuelle Nutzer-ID und Community-ID enthält.

POST https://www.example.com/account_linking?redirect_uri=https%3A%2F%2Ffoxfabrics.facebook.com%2Flink_complete HTTP/1.1
Host: foxfabrics.third-party.com
Origin: http://www.facebook.com
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/5.0 Gecko/20100101 Firefox/57.0
...

signed_request=238fsdfsd.oijdoifjsidf899
    

Die Payload enthält den Parameter signed_request, der Informationen zu diesem Nutzer enthält. Diese Anfrage kann wie folgt decodiert werden:

1. Teile den Inhalt in zwei Teile, die durch das Zeichen „.“ getrennt sind.
2. Decodiere den ersten Teil, die Signatur, aus base64url.
3. Decodiere den zweiten Teil, die Payload, aus base64url und decodiere dann das resultierende JSON-Objekt.
4. Stelle sicher, dass die Signatur dem HMAC der codierten Payload basierend auf deinem App-Geheimcode entspricht.

Die Payload enthält die folgenden Felder:

{
  "algorithm": "HMAC-SHA256",
  "user_id": "88575656148087",
  "community_id": "138169208138649"
}
    

Jetzt verfügst du über eine Workplace-Nutzer-ID und -Community-ID zusammen mit einer validierten Nutzersitzung in deinem Service und kannst die Workplace-ID für diesen Nutzer neben der jeweiligen ID in deinem Service aufzeichnen. Nach dem Abschluss solltest du zu der in der ursprünglichen Anfrage als redirect_uri angegebenen URL umgeleitet werden.

GET {$redirect_uri} HTTP/1.1
Host: foxfabrics.facebook.com
User-Agent: Mozilla/5.0 Gecko/20100101 Firefox/57.0
Referer: https://www.example.com/account_linking
...
    

Workplace erkennt dann, dass die Identitätszuordnung abgeschlossen ist, und versucht erneut, Metadaten für die authentifizierte Vorschau anzufragen. Jetzt kannst du linked_user in der Antwort auf true setzen und die erforderlichen Metadaten angeben.

FAQs