Vistas previas autenticadas

Información general

Con las vistas previas autenticadas, tu contenido se ve correctamente en Workplace. Para ello, tu sistema debe proporcionar metadatos de vista previa autenticada en un formato que Workplace admita, de modo que, cuando se compartan URL de tu contenido, Workplace pueda obtener esos datos y crear una vista previa. Este proceso se suele llamar despliegue de enlaces.

Si bien Facebook puede obtener metadatos para desplegar una URL pública mediante el protocolo Open Graph y el rastreador de Facebook, este proceso no es posible en el caso de las URL privadas, que se comparten más habitualmente en Workplace. Cuando una persona comparta una URL privada en Workplace, se emitirá un webhook a una URL de devolución de llamada que definas, y podrás responder con una carga útil de metadatos en la que se describa la URL para la persona que la comparte, a fin de generar una vista previa del enlace.

Este mismo proceso se repetirá para cada persona que vea la URL compartida en Workplace, lo que te permitirá controlar la visibilidad de las vistas previas por usuario.

La autenticación permite que las personas compartan información con seguridad y facilidad en Workplace, de una manera que respeta la privacidad del material original. Si admites las vistas previas autenticadas, te asegurarás de que tu contenido se vea correctamente en Workplace, de forma segura y consciente de la privacidad.

Compartir URL privadas

En Workplace, los usuarios suelen compartir enlaces a recursos corporativos internos que solo deberían ver determinadas personas. Esto es diferente de lo que ocurre en Facebook, donde las personas suelen compartir contenido público, como artículos de noticias o publicaciones de blogs.

URL públicas y privadas en Workplace

Para que Workplace pueda generar una vista previa de contenido corporativo privado, se deben proporcionar algunos metadatos. Como proveedor, puedes elegir si vas a proporcionar metadatos a la persona que está viendo el contenido en Workplace, en función de si tiene permitido verlo o no.

Contenido de este documento

En este documento, se describen los componentes de la activación de las vistas previas autenticadas:

• Vistas previas autenticadas
• Asignación de identidad

Configuración

Para activar las vistas previas autenticadas, deberás configurar tu app teniendo en cuenta lo siguiente:

• Se debe instalar en una comunidad de Workplace o en uno o más grupos.
• Debe obtener el permiso de despliegue de enlaces.
• Un dominio o un conjunto de dominios, que incluyan las URL que desplegará la integración.
• Una suscripción al tema de webhook Enlaces, para la vista previa del campo, y una URL de devolución de llamada para proporcionar metadatos.

Webhooks

Recibir webhooks

Podemos enviar una solicitud al proveedor en diferentes situaciones:

1. Si se comparte una URL nueva que nunca vimos (siempre desde el editor).
2. Si un usuario nuevo está viendo un contenido y no sabemos si tiene acceso (siempre desde el feed).
3. Cuando se vuelve a compartir un contenido preexistente o si este caducó (desde el editor o el feed).

Formato de solicitud de webhook

En cualquiera de las situaciones anteriores, se enviará un webhook como solicitud POST, en el siguiente formato:

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

Esta carga útil contiene los siguientes campos:

Ejemplo

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 de respuesta de webhook

Cuando recibas una solicitud de webhook, deberás proporcionar una carga útil de metadatos en un formato de respuesta específico:

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

Se espera que esta carga útil contenga los siguientes campos:

Ejemplo de respuesta 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
}
    

Modos de privacidad

El modo de privacidad determina la visibilidad, es decir, si exigimos autenticación de usuario a los usuarios actuales y posteriores.

1. organization: visible para el usuario; no se requiere autenticación de usuario
   Si es visible para el usuario, podemos mostrar el contenido de forma directa. Por ejemplo, se incluye el caso en que un contenido se supone que es visible para todas las personas en el dominio (empresa). No enviaremos un webhook cada vez que una persona nueva está viendo el contenido nuevo.
2. accessible: visible para el usuario actual, pero es posible que se exija asignación de identidad del usuario a otras personas.
   El proveedor sabe que este usuario en particular puede ver el contenido, pero esto no quiere decir que cualquier otra persona pueda verlo. Mostramos la vista previa, pero seguiremos enviando webhooks al resto de los usuarios.
3. inaccessible: no visible para el usuario
   El proveedor conoce al usuario y sabe que no se le permite ver el contenido. Mostramos un aviso de privacidad (no disponible, privado, etc.)

Datos adicionales

Para agregar más información sobre la vista previa de un enlace, puedes enviar hasta tres elementos de datos adicionales. Un elemento de datos está compuesto de una serie de pares clave-valor. Pero el valor puede tener diferentes formatos.

Por el momento, se admiten cuatro formatos diferentes:

• text: mostrará el valor tal cual es. El valor debe ser una cadena. En el caso de este formato, los datos adicionales también pueden contener una propiedad color, que debe ser uno de los siguientes valores: blue, green, yellow, orange o red. Si está presente, se mostrará el valor con el color como fondo.
• date: el valor se interpretará como una fecha en formato ISO-8601 sin hora y se mostrará sin la indicación de hora.
• datetime: el valor se interpretará como una fecha en formato ISO-8601 con hora y zona horaria, y se mostrará con la indicación de hora en la zona horaria del usuario.
• user: el valor se interpretará como un identificador de usuario y se mostrará el nombre del usuario.

Se ignora el parámetro download_url si se configuran datos adicionales.

Generar vistas previas de archivos (opcional)

Si el modo de privacidad de tu documento está marcado como organization o accessible, y se proporciona una URL de descarga, enviaremos una solicitud adicional para descargar los datos.

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

Luego, Workplace tomará este archivo y lo convertirá en fotos para crear una publicación de varias fotos.

Asignación de identidad

Como vimos anteriormente, para proporcionar vistas previas autenticadas, se necesita algún tipo de asignación de identidad. Mediante la asignación de identidad, se controla si un usuario de Workplace tiene permiso para ver el contenido de la vista previa y se garantiza que las reglas de acceso de tu contenido se respeten.

Asignación en toda la organización

La forma más simple de asignación de identidad es aplicarla en toda la organización, ya que la membresía de una comunidad de Workplace es suficiente para permitir que las vistas previas se muestren a los usuarios. Esta es una situación común cuando se generan vistas previas de enlaces a la red interna de una empresa, o a un servicio en que todos los objetos (o al menos sus metadatos) son visibles para toda la empresa.

Cuando se instala tu integración en una comunidad de Workplace, se puede verificar el identificador de esta mediante el punto de conexión /community, con el token de acceso que recuperaste durante la instalación. Puedes almacenar este identificador de la comunidad junto con el token y asignarlo a un identificador de inquilino u organización dentro de tu servicio. De esta manera, se crea una asignación entre una comunidad de Workplace y la organización en tu servicio.

Luego, cuando respondas a las solicitudes de webhooks de vistas previas autenticadas, podrás verificar si el identificador de la comunidad de la carga útil del webhook coincide con el identificador de la comunidad vinculada a la organización. Así, podrás decidir si es seguro devolver una carga útil de metadatos. Si marcas la privacidad de esa carga útil como ORGANIZATION, te aseguras de que no enviemos webhooks adicionales por cada usuario de esa comunidad de Workplace.

Asignación por usuario

Si se necesita más granularidad con respecto a los permisos, puedes implementar una asignación por usuario. Si lo haces, podrás decidir individualmente si deseas mostrar los metadatos a cada usuario en Workplace. Workplace envía un identificador de usuario en la carga útil de cada webhook para las vistas previas autenticadas. Si quieres implementar una asignación por usuario, deberás saber al registro de qué usuario de tu sistema corresponde el identificador de usuario de Workplace que se envía en la carga útil del webhook.

Si esta es la primera vez que te encuentras con un identificador de usuario de Workplace determinado, puedes responder con el campo booleano linked_user configurado como false. De esta manera, se indicará a Workplace que debe mostrar un botón Activar vista previa para solicitar que el usuario vincule su cuenta.

Cuando se presione el botón, Workplace abrirá el cuadro de diálogo de un punto de conexión de vinculación de cuentas que definas, donde podrás validar la sesión del usuario en tu servicio. Workplace abrirá esta URL a través de una solicitud POST y pasará un parámetro de solicitud firmado, que contiene el identificador de usuario actual y el identificador de la comunidad.

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
    

En la carga útil, hay un parámetro signed_request que contiene información sobre este usuario. Esta solicitud se puede decodificar de la siguiente manera:

1. Divide el contenido en dos partes delimitadas por un carácter ".".
2. Decodifica la primera parte, signature, que estará en formato base64url.
3. Decodifica la segunda parte, payload, que también estará en formato base64url, y, luego, decodifica el objeto JSON resultante.
4. Verifica que la firma coincida con el HMAC de la carga útil codificada, en función de la clave secreta de tu app.

La carga útil contiene los siguientes campos:

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

En este punto, tendrás un identificador de usuario de Workplace y un identificador de comunidad, junto con una sesión de usuario validada en tu servicio, y podrás registrar el identificador de Workplace de este usuario, además de su identificador en tu servicio. Cuando termines, debes redirigirte a la URL proporcionada en la solicitud original como parámetro de consulta 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 reconocerá que la asignación de identidad se completó e intentará solicitar otra vez los metadatos de la vista previa autenticada. Esta vez, podrás responder con linked_user configurado como true y proporcionar los metadatos solicitados.

Preguntas frecuentes