Anteprime autorizzate

Panoramica

Le anteprime autorizzate fanno in modo che l'anteprima dei tuoi contenuti sia visualizzata correttamente su Workplace. Ciò comporta l'assistenza per i metadati di anteprima autenticati in un formato che Workplace si aspetta, in modo che quando vengono condivisi gli URL dei tuoi contenuti, Workplace può recuperare quei metadati e creare un'anteprima. Questo processo è spesso chiamato generazione in anteprima di link.

Anche se Facebook è in grado di ottenere metadati per generare l'anteprima di un URL pubblico tramite il protocollo Open Graph e il crawler di Facebook, questo processo non è possibile per gli URL privati, che sono più comunemente condivisi su Workplace. Quando qualcuno condivide un URL privato su Workplace, verrà emesso un webhook a un URL di callback definito da te e potrai rispondere con un payload di metadati che descrive l'URL della persona che lo condivide, per visualizzare un'anteprima del link.

Questo stesso processo verrà ripetuto per ogni persona che visualizza l'URL condiviso su Workplace, consentendoti di controllare la visibilità dell'anteprima per utente.

L'autenticazione per Workplace consente alle persone di condividere informazioni in modo sicuro e facile su Workplace, nel rispetto della privacy del materiale di origine. Supportando le anteprime autorizzate, puoi assicurarti che i tuoi contenuti vengano visualizzati correttamente su Workplace, in modo sicuro e rispettoso della privacy.

Condivisione di URL privati

Su Workplace, spesso le persone condividono link alle risorse interne dell'azienda, che dovrebbero essere visibili solo da determinate persone. Questo è in contrasto con Facebook, dove le persone condividono spesso contenuti pubblici, come articoli di notizie o post di blog.

URL pubblici e privati su Workplace

Affinché Workplace possa generare un'anteprima dei contenuti privati aziendali, è necessario fornire alcuni metadati. In qualità di provider, puoi scegliere se fornire metadati per l'utente attualmente su Workplace, a seconda che gli sia consentito o meno visualizzare il contenuto.

In questo documento:

Questo documento illustra i componenti dell'abilitazione delle anteprime autorizzate, tra cui:

• anteprime autorizzate;
• mappatura dell'identità.

Configurazione

Per abilitare le anteprime autorizzate, devi configurare la tua app per i seguenti aspetti:

• l'installazione su una community Workplace oppure in uno o più gruppi;
• l'autorizzazione di generazione in anteprima di link;
• un dominio o un insieme di domini, comprendenti gli URL che saranno generati in anteprima dalla tua integrazione;
• un'iscrizione al link relativo all'argomento webhook, per l'anteprima del campo, e un URL di callback per fornire metadati.

Webhook

Ricezione di webhook

Ci sono molteplici situazioni che prevedono l'invio da parte nostra di una richiesta al provider:

1. Se viene condiviso un nuovo URL che non abbiamo visto prima (sempre dallo strumento di composizione).
2. Se un nuovo utente vede un contenuto e non sappiamo se l'utente ha accesso (sempre dal feed).
3. Un contenuto esistente viene ricondiviso o è scaduto (dallo strumento di composizione o dal feed).

Formato di richiesta webhook

In tutti gli scenari sopra indicati, verrà inviato un webhook come richiesta POST nel seguente formato:

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

Questo payload contiene i seguenti campi:

Esempio

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"
            }
        }]
    }]
}
    

Formato di risposta webhook

Quando ricevi una richiesta webhook, dovrai fornire un payload di metadati in un formato di risposta specifico:

{
  "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
}

Questo payload deve contenere i seguenti campi:

Esempio di risposta completa

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
}
    

Modalità di privacy

La modalità privacy determina la visibilità, se richiediamo l'autenticazione per gli utenti attuali e successivi.

1. organization: visibile all'utente, nessuna autenticazione richiesta
   Se è visibile all'utente, possiamo mostrare il contenuto direttamente. Questo è il caso in cui è previsto che un contenuto sia visibile a tutti nel dominio (azienda). Non invieremo un webhook ogni volta che un utente diverso visualizza i nuovi contenuti.
2. accessible: visibile all'utente corrente, ma potrebbe essere richiesta la mappatura dell'identità gli altri utenti.
   Il provider sa che questo particolare utente è autorizzato a visualizzare quel contenuto, ma questo non significa necessariamente che chiunque altro possa vederlo. Mostriamo l'anteprima ma continueremo a inviare webhook per ogni altro utente.
3. inaccessible: non visibile all'utente
   Il provider conosce l'utente e sa che non è autorizzato a visualizzare il contenuto. Mostriamo un avviso sulla privacy (non disponibile, privato ecc.).

Dati aggiuntivi

Per aggiungere maggiori informazioni su un'anteprima del link, puoi inviare fino a tre elementi di dati aggiuntivi. Una voce aggiuntiva di dati è composta da un insieme di elementi chiave del valore. Ma il valore può essere formattato in modi diversi.

Al momento sono supportati quattro diversi formati:

• text: visualizza il valore così com'è, il valore deve essere una stringa. Per questo formato i dati aggiuntivi possono contenere anche una proprietà color che deve corrispondere a uno tra i valori blue, green, yellow, orange e red. Se presente, questo parametro renderà il valore con il colore come sfondo.
• date: analizza il valore come formato data ISO-8601 senza orario e lo visualizza senza indicazione temporale.
• datetime: analizza il valore come formato data ISO-8601 con orario e fuso orario e lo visualizza con indicazione temporale nel fuso orario dell'utente.
• user: analizza il valore come ID utente e visualizza il nome dell'utente.

Il parametro download_url viene ignorato se sono impostati dati aggiuntivi.

Visualizzazione delle anteprime dei file (facoltativo)

Se la modalità privacy per il tuo documento è contrassegnata come organization o accessible e viene fornito un URL di download, invieremo una richiesta aggiuntiva per scaricare i dati.

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

Workplace convertirà il file in foto per farne un post con più foto.

Mappatura dell'identità

Come visto sopra, fornire anteprime autorizzate richiede una sorta di mappatura dell'identità. La mappatura dell'identità controlla se un utente di Workplace dispone dell'autorizzazione per visualizzare i contenuti in anteprima e assicura che le regole di accesso dei tuoi contenuti siano rispettate su Workplace.

Mappatura livello organizzazione

La forma più semplice di mappatura dell'identità è la mappatura a livello di organizzazione, dove l'iscrizione a una community di Workplace è sufficiente per consentire di mostrare anteprime agli utenti su Workplace. Questo scenario è comune quando si visualizzano in anteprima i link a un'intranet aziendale o qualsiasi servizio in cui tutti gli oggetti (o almeno i loro metadati) sono visibili all'intera azienda.

Quando la tua integrazione è installata su una community di Workplace, l'ID della community può essere controllato tramite l'endpoint /community, usando il token d'accesso che hai recuperato dopo l'installazione. Puoi memorizzare questo ID della community insieme al token e mapparlo a un identificatore di un tenant o un'organizzazione all'interno del tuo servizio. Questo crea una mappatura tra una community di Workplace e l'organizzazione nel tuo servizio.

Quindi, quando rispondi alle richieste autorizzate del webhook di anteprima, puoi controllare che l'ID community del payload del webhook corrisponda all'ID community collegato all'organizzazione, quindi decidere se restituire un payload di metadati è sicuro. Contrassegnando la privacy del payload come ORGANIZZAZIONE, non avremo bisogno di inviare webhook aggiuntivi per ogni singolo utente nella community di Workplace.

Mappatura livello utente

Se è necessaria una maggiore granularità delle autorizzazioni, puoi supportare una mappatura a livello di utente, in modo tale da assicurarti di poter scegliere se mostrare i metadati a ogni utente su Workplace singolarmente. Workplace invia un ID utente in ogni payload webhook per le anteprime autorizzate. Per supportare la mappatura livello utente, devi sapere quale record utente nel tuo sistema mappa all'ID utente di Workplace inviato nel payload webhook.

Se questo è il tuo primo incontro per un determinato ID utente di Workplace, puoi rispondere con il campo booleano linked_user impostato su false. In questo modo, Workplace potrà mostrare un pulsante Abilita anteprima, invitando l'utente a collegare il proprio account.

Quando il pulsante viene premuto, Workplace apre una finestra di dialogo su un endpoint di collegamento dell'account da te definito, dove puoi convalidare la sessione utente nel tuo servizio. Workplace aprirà questo URL tramite una richiesta POST e passerà un parametro di richiesta firmata, che contiene l'ID utente attuale e l'ID community.

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
    

Nel payload è presente un parametro signed_request che contiene informazioni su questo utente. Questa richiesta può essere decodificata come segue:

1. Suddividi il contenuto in due parti delimitate da un carattere "." (punto).
2. Decodifica la prima, ovvero la firma, da base64url.
3. Decodifica la seconda parte, ovvero il payload, da base64url e poi decodifica l'oggetto JSON risultante.
4. Verifica che la firma corrisponda all'HMAC del payload codificato in base alla tua chiave segreta.

Il payload contiene i seguenti campi:

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

A questo punto, avrai un ID utente di Workplace e un ID community, oltre a una sessione utente convalidata nel tuo servizio, e potrai registrare l'ID Workplace di questo utente accanto al suo ID nel tuo servizio. Al completamento, devi eseguire il reindirizzamento all'URL fornito nella richiesta originale come parametro di query redirect_uri.

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 riconoscerà che la mappatura dell'identità è completa e cercherà di richiedere nuovamente i metadati di anteprima autorizzati. Questa volta, potrai rispondere con linked_user impostato su true e fornire i metadati richiesti.

FAQ