„Teilen“-Erweiterungen für Workplace

Übersicht

Mit „Teilen“-Erweiterungen für Workplace können Personen Informationen sicher und einfach auf Workplace teilen und dabei das Quellmaterial schützen.

Indem du „Teilen“-Erweiterungen unterstützt, stellst du sicher, dass deine Content-Vorschau korrekt auf Workplace angezeigt wird. So können Personen Ordner mit ihren Workplace-Gruppen verknüpfen und deinen Content im Gruppen-Eingabefeld in Workplace einfügen. Damit kann kürzlich erstellter Inhalt ganz einfach direkt in einer Gruppe geteilt werden.

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 „Teilen“-Erweiterungen beschrieben. Dabei gibt es drei Hauptkomponenten:

• Authentifizierte Vorschau
• Identitätszuordnung
• Eingabefeld-Erweiterungen

Außerdem wird in diesem Dokument erläutert, wie du deine App für „Teilen“-Erweiterungen konfigurierst.

Konfigurieren deiner App

Um deine App für „Teilen“-Erweiterungen einzurichten, musst du die folgenden drei Felder angeben:

• Eine Domain oder eine Gruppe von Domains im Stamm jeder URL, für die deine Integration eine authentifizierte Vorschau erstellt.

  • Jede Domain (beispielsweise example.com) deckt auch alle Subdomains ab (wie acme.example.com).
• Einen regulären Ausdruck, der den relativen Pfad jeder URL zuordnet, die von deiner Integration unterstützt wird.

  • Wenn du beispielsweise entweder www.example.com/download?id=123 oder www.example.com/file/456, aber nicht www.example.com/blog zuordnen möchtest, kannst du einen regulären Ausdruck wie \/(download?|file\/).+/ verwenden.
  • Wenn die Domain oder die Gruppe aus Domains alle URLs abdeckt, kannst du dieses Feld leer lassen oder einen umfassenden regulären Ausdruck verwenden (z. B. /.*/).
• Einen Identitätszuordnungs-Endpunkt, mit dem die Identität von Workplace-Nutzern, denen eine Vorschau angezeigt werden soll, zugeordnet wird.

Deine App sollte zudem das Link-Webhook-Thema und preview abonnieren und die Berechtigung für Link-Unfurling besitzen.

Authentifizierte Vorschau

Das Hauptfeature von „Teilen“-Erweiterungen ist die korrekte Inhaltsvorschau auf Workplace. 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 Meta 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 stattdessen 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.

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.
• Die App muss über die Berechtigung für Link-Unfurling verfügen (derzeit unter der Positivliste verfügbar).
• 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*innen-ID und zeigt den Benutzer*innennamen an.

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.

Eingabefeld-Erweiterungen

Eine authentifizierte Vorschau für Links, die in Workplace geteilt werden, ist schon enorm nützlich. Du kannst das Teilen von Inhalten in deiner App direkt über Workplace aber noch einfacher machen, indem du Eingabefeld-Erweiterungen unterstützt.

Wenn deine Integration Eingabefeld-Erweiterungen unterstützt, kannst du eine Liste mit aktuellen oder relevanten Dokumenten angeben, wenn Nutzer beginnen, einen Beitrag in einer aktivierten Workplace-Gruppe zu verfassen. Workplace zeigt diese Liste dann an, damit die Nutzer Inhalt teilen können, ohne die URL kopieren und einfügen zu müssen. Das resultierende geteilte Objekt verhält sich genauso wie jedes manuell geteilte Objekt und berücksichtigt die Berechtigungen der Funktion für die authentifizierte Vorschau.

Für Eingabefeld-Erweiterungen sind Identitätszuordnungen für Nutzer erforderlich, damit du eine personalisierte Liste mit Dokumenten im Eingabefeld zurückgeben kannst.

Konfiguration

Die folgende Konfiguration ist in deiner App erforderlich, um Eingabefeld-Erweiterungen zu unterstützen:

• Webhook-Abonnement des Themas link und des Felds collection.
• Eine Kontoverknüpfungs-URL die du beim Konfigurieren deiner App angegeben hast.

Format der Webhook-Anfrage

Wenn ein*e verknüpfte*r Nutzer*in die Eingabefeld-Erweiterung deiner Integration aufruft, sendet Workplace einen Webhook im folgenden Format, um eine Liste der Dokumente abzurufen:

{
  "object": "link",
  "entry": [
    {
      "time": int,
      "changes": [
        {
          "field": "collection",
          "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": "collection",
            "value": {
                "community": {
                    "id": "138169208138649"
                },
                "user": {
                    "id": "88575656148087"
                }
            }
        }]
    }]
}
    

Antwortformat

Zur Verarbeitung dieser Anfrage muss deine Callback-URL die „X-Hub-Signature“ verifizieren und dann im folgenden Format mit Objekten antworten, die im Eingabefeld angezeigt werden sollen:

{
  "data": [
    {
      "link": string,
      "title": string,
      ?"description": string,
      ?"icon": string,
      ?"download_url": string,
      "privacy": ORGANIZATION | ACCESSIBLE,
      "type": DOCUMENT | FOLDER | TASK | LINK,
      ?"additional_data": [
        {
          "title" => string,
          "format" => 'text' | 'date' | 'datetime' | 'user',
          "value" => string | number,
        },
      ],
    }
  ],
  ?"linked_user": boolean
}

Diese Payload muss die folgenden Felder enthalten:

Beispiel:

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

{
  "data": [
    {
      "link": "https://company.third-party.com/document-A",
      "title": "Slides for Project A",
      "description": "Short summary of the slides.",
      "download_url": "https://company.provider.com/download/document-A",
      "privacy": "accessible",
      "type": "document"
    },
    {
      "link": "https://company.third-party.com/folder-B",
      "title": "Folder B",
      "privacy": "public",
      "type": "folder",
    }
  ],
  "linked_user": true
}