Conjuntos de sitios web relacionados: guía para desarrolladores

Los Conjuntos de sitios web relacionados (RWS) son un mecanismo de plataforma web que ayuda a los navegadores a comprender las relaciones entre una colección de dominios. Esto permite que los navegadores tomen decisiones clave para habilitar ciertas funciones del sitio (como si se permite el acceso a las cookies de sitios cruzados) y presentar esta información a los usuarios.

Muchos sitios dependen de varios dominios para ofrecer una sola experiencia del usuario. Es posible que las organizaciones deseen mantener diferentes dominios de nivel superior para varios casos de uso, como dominios específicos de cada país o dominios de servicio para alojar imágenes o videos. Los Conjuntos de sitios web relacionados permiten que los sitios compartan datos entre dominios, con controles específicos.

¿Qué es un Conjunto de sitios web relacionados?

En términos generales, un conjunto de sitios web relacionados es una colección de dominios para los que hay un solo "conjunto principal" y, potencialmente, varios "conjuntos miembros".

En el siguiente ejemplo, primary enumera el dominio principal y associatedSites enumera los dominios que cumplen con los requisitos del subconjunto asociado.

{
  "primary": "https://primary.com",
  "associatedSites": ["https://associate1.com", "https://associate2.com", "https://associate3.com"]
}

Los conjuntos de sitios web relacionados se enumeran en un archivo JSON público alojado en GitHub. Esta es la fuente canónica de todos los conjuntos aprobados. Los navegadores consumen este archivo para determinar si los sitios pertenecen o no al mismo Conjunto de sitios web relacionados.

Solo las personas con control administrativo sobre un dominio pueden crear un conjunto con ese dominio. Los usuarios que envían contenido deben declarar la relación entre cada "miembro del conjunto" y su "elemento principal del conjunto". Los miembros del conjunto pueden incluir un rango de diferentes tipos de dominios y deben formar parte de un subconjunto basado en un caso de uso.

Si tu aplicación depende del acceso a cookies de sitios cruzados (también llamadas cookies de terceros) en sitios dentro del mismo conjunto de sitios web relacionados, puedes usar la API de Storage Access (SAA) y la API de requestStorageAccessFor para solicitar acceso a esas cookies. Según el subconjunto del que forma parte cada sitio, el navegador puede controlar la solicitud de manera diferente.

Para obtener más información sobre el proceso y los requisitos para enviar conjuntos, consulta los lineamientos para el envío. Los conjuntos enviados se someterán a varias verificaciones técnicas para validar los envíos.

Casos de uso de los Conjuntos de sitios web relacionados

Los conjuntos de sitios web relacionados son una buena opción para los casos en los que una organización necesita una forma de identidad compartida en diferentes sitios de nivel superior.

Estos son algunos de los casos de uso de los Conjuntos de sitios web relacionados:

• Personalización por país Aprovechar los sitios localizados y, al mismo tiempo, depender de la infraestructura compartida (por ejemplo, example.co.uk puede depender de un servicio alojado en example.ca).
• Integración del dominio de servicio. Aprovechar los dominios de servicio con los que los usuarios nunca interactúan directamente, pero que proporcionan servicios en los sitios de la misma organización (ejemplo-cdn.com).
• Separación del contenido del usuario. Acceder a datos en diferentes dominios que separan el contenido subido por los usuarios del resto del contenido del sitio por motivos de seguridad, a la vez que se permite que el dominio en zona de pruebas acceda a las cookies de autenticación (y otras). Si publicas contenido inactivo subido por los usuarios, también puedes alojarlo de forma segura en el mismo dominio siguiendo las prácticas recomendadas.
  • Contenido autenticado incorporado. Admite contenido incorporado de todas las propiedades afiliadas (videos, documentos o recursos restringidos al usuario que accedió al sitio de nivel superior).
• Accede. Se admite el acceso en propiedades afiliadas. La API de FedCM también puede ser adecuada para algunos casos de uso.
• Analytics Implementar análisis y mediciones de los recorridos de los usuarios en las propiedades afiliadas para mejorar la calidad de los servicios

Detalles de la integración de los Conjuntos de sitios web relacionados

API de Storage Access

La API de Storage Access (SAA) proporciona una forma para que el contenido incorporado de origen cruzado acceda al almacenamiento al que normalmente solo tendría acceso en un contexto de origen propio.

Los recursos incorporados pueden usar métodos de SAA para verificar si tienen acceso al almacenamiento y para solicitar acceso al agente de usuario.

Cuando se bloquean las cookies de terceros, pero se habilitan los Conjuntos de sitios web relacionados (RWS), Chrome otorgará automáticamente el permiso en contextos intra-RWS y mostrará un mensaje al usuario en otros casos. (Un "contexto intra-RWS" es un contexto, como un iframe, cuyo sitio incorporado y sitio de nivel superior se encuentran en el mismo RWS).

Cómo verificar y solicitar acceso al almacenamiento

Para verificar si actualmente tienen acceso al almacenamiento, los sitios incorporados pueden usar el método Document.hasStorageAccess().

El método devuelve una promesa que se resuelve con un valor booleano que indica si el documento ya tiene acceso a sus cookies o no. La promesa también devuelve verdadero si el iframe tiene el mismo origen que el marco superior.

Para solicitar acceso a las cookies en un contexto de varios sitios, los sitios incorporados pueden usar Document.requestStorageAccess() (rSA).

La API de requestStorageAccess() está diseñada para llamarse desde un iframe. Ese iframe debe haber recibido interacción del usuario recientemente (un gesto del usuario, que es obligatorio en todos los navegadores), pero Chrome también requiere que, en algún momento de los últimos 30 días, el usuario haya visitado el sitio propietario de ese iframe y haya interactuado con ese sitio específicamente, como un documento de nivel superior, no en un iframe.

requestStorageAccess() devuelve una promesa que se resuelve si se otorgó el acceso al almacenamiento. La promesa se rechaza, citando el motivo, si se denegó el acceso por algún motivo.

requestStorageAccessFor en Chrome

La API de Storage Access solo permite que los sitios incorporados soliciten acceso al almacenamiento desde elementos <iframe> que hayan recibido interacción del usuario.

Esto plantea desafíos para adoptar la API de Storage Access en sitios de nivel superior que usan imágenes o etiquetas de secuencia de comandos entre sitios que requieren cookies.

Para abordar este problema, Chrome implementó una forma para que los sitios de nivel superior soliciten acceso al almacenamiento en nombre de orígenes específicos con Document.requestStorageAccessFor() (rSAFor).

 document.requestStorageAccessFor('https://target.site')

La API de requestStorageAccessFor() está diseñada para que la llame un documento de nivel superior. Ese documento también debe haber recibido interacción del usuario recientemente. Sin embargo, a diferencia de requestStorageAccess(), Chrome no verifica si hubo interacción en un documento de nivel superior en los últimos 30 días, ya que el usuario ya está en la página.

Verifica los permisos de acceso al almacenamiento

El acceso a algunas funciones del navegador, como la cámara o la ubicación geográfica, se basa en los permisos que otorga el usuario. La API de Permissions proporciona una forma de verificar el estado del permiso para acceder a una API, ya sea que se haya otorgado, rechazado o que requiera alguna forma de interacción del usuario, como hacer clic en un mensaje o interactuar con la página.

Puedes consultar el estado del permiso con navigator.permissions.query().

Para verificar el permiso de acceso al almacenamiento en el contexto actual, debes pasar la cadena 'storage-access':

navigator.permissions.query({name: 'storage-access'})

Para verificar el permiso de acceso al almacenamiento de un origen específico, debes pasar la cadena 'top-level-storage-access':

navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'})

Ten en cuenta que, para proteger la integridad del origen incorporado, esta verificación solo incluye los permisos que otorga el documento de nivel superior con document.requestStorageAccessFor.

Devolverá prompt o granted según si el permiso se puede otorgar automáticamente o si requiere un gesto del usuario.

Modelo por fotograma

Los permisos de rSA se aplican por frame. Los permisos de rSA y rSAFor se tratan como permisos independientes.

Cada nuevo frame deberá solicitar acceso al almacenamiento de forma individual, y se le otorgará acceso automáticamente. Solo la primera solicitud requiere un gesto del usuario. Las solicitudes posteriores que inicie el iframe, como la navegación o los subrecursos, no deberán esperar un gesto del usuario, ya que se otorgará para la sesión de navegación con la solicitud inicial.

Si actualizas, vuelves a cargar o recreas el iframe de alguna otra manera, deberás volver a solicitar acceso.

Requisitos de cookies

Las cookies deben especificar los atributos SameSite=None y Secure como rSA, ya que solo proporciona acceso a las cookies que ya están marcadas para su uso en contextos de sitios cruzados.

Las cookies con SameSite=Lax, SameSite=Strict o sin un atributo SameSite son solo para uso de origen y nunca se compartirán en un contexto entre sitios, independientemente de la rSA.

Seguridad

En el caso de rSAFor, las solicitudes de subrecursos requieren encabezados de uso compartido de recursos entre dominios (CORS) o el atributo crossorigin en los recursos, lo que garantiza la habilitación explícita.

Ejemplos de implementación

Solicita acceso al almacenamiento desde un iframe de origen cruzado incorporado

Cómo verificar si tienes acceso al almacenamiento

Para verificar si ya tienes acceso al almacenamiento, usa document.hasStorageAccess().

Si la promesa se resuelve como verdadera, puedes acceder al almacenamiento en el contexto de sitios cruzados. Si se resuelve como falso, debes solicitar acceso al almacenamiento.

document.hasStorageAccess().then((hasAccess) => {
    if (hasAccess) {
      // You can access storage in this context
    } else {
      // You have to request storage access
    }
});

Solicita acceso al almacenamiento

Si necesitas solicitar acceso al almacenamiento, primero verifica el permiso de acceso al almacenamiento navigator.permissions.query({name: 'storage-access'}) para ver si requiere un gesto del usuario o si se puede otorgar automáticamente.

Si el permiso es granted, puedes llamar a document.requestStorageAccess() y debería funcionar sin un gesto del usuario.

Si el estado del permiso es prompt, debes iniciar la llamada a document.requestStorageAccess() después de un gesto del usuario, como un clic en un botón.

Ejemplo:

navigator.permissions.query({name: 'storage-access'}).then(res => {
  if (res.state === 'granted') {
    // Permission has already been granted
    // You can request storage access without any user gesture
    rSA();
  } else if (res.state === 'prompt') {
    // Requesting storage access requires user gesture
    // For example, clicking a button
    const btn = document.createElement("button");
    btn.textContent = "Grant access";
    btn.addEventListener('click', () => {
      // Request storage access
      rSA();
    });
    document.body.appendChild(btn);
  }
});

function rSA() {
  if ('requestStorageAccess' in document) {
    document.requestStorageAccess().then(
      (res) => {
        // Use storage access
      },
      (err) => {
        // Handle errors
      }
    );
  }
}

Las solicitudes posteriores desde el iframe, las navegaciones o los recursos secundarios tendrán automáticamente permiso para acceder a las cookies entre sitios. hasStorageAccess() devuelve verdadero, y las cookies entre sitios del mismo conjunto de sitios web relacionados se enviarán en esas solicitudes sin ninguna llamada adicional de JavaScript.

Sitios de nivel superior que solicitan acceso a las cookies en nombre de sitios de origen cruzado

Los sitios de nivel superior pueden usar requestStorageAccessFor() para solicitar acceso al almacenamiento en nombre de orígenes específicos.

hasStorageAccess() solo verifica si el sitio que lo llama tiene acceso al almacenamiento, por lo que un sitio de nivel superior puede verificar los permisos de otro origen.

Para descubrir si se le pedirá al usuario que otorgue acceso al almacenamiento o si ya se le otorgó acceso al almacenamiento al origen especificado, llama a navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'}).

Si el permiso es granted, puedes llamar a document.requestStorageAccessFor('https://target.site'). Debe tener éxito sin un gesto del usuario.

Si el permiso es prompt, deberás conectar la llamada document.requestStorageAccessFor('https://target.site') detrás del gesto del usuario, como un clic en un botón.

Ejemplo:

navigator.permissions.query({name:'top-level-storage-access',requestedOrigin: 'https://target.site'}).then(res => {
  if (res.state === 'granted') {
    // Permission has already been granted
    // You can request storage access without any user gesture
    rSAFor();
  } else if (res.state === 'prompt') {
    // Requesting storage access requires user gesture
    // For example, clicking a button
    const btn = document.createElement("button");
    btn.textContent = "Grant access";
    btn.addEventListener('click', () => {
      // Request storage access
      rSAFor();
    });
    document.body.appendChild(btn);
  }
});

function rSAFor() {
  if ('requestStorageAccessFor' in document) {
    document.requestStorageAccessFor().then(
      (res) => {
        // Use storage access
      },
      (err) => {
        // Handle errors
      }
    );
  }
}

Después de una llamada requestStorageAccessFor() exitosa, las solicitudes de sitios cruzados incluirán cookies si incluyen CORS o el atributo crossorigin, por lo que es posible que los sitios quieran esperar antes de activar una solicitud.

Las solicitudes deben usar la opción credentials: 'include' y los recursos deben incluir el atributo crossorigin="use-credentials".

function checkCookie() {
    fetch('https://related-website-sets.glitch.me/getcookies.json', {
        method: 'GET',
        credentials: 'include'
      })
      .then((response) => response.json())
      .then((json) => {
      // Do something
      });
  }

Cómo realizar pruebas locales

Requisitos previos

Para probar los conjuntos de sitios web relacionados de forma local, usa Chrome 119 o una versión posterior iniciada desde la línea de comandos y habilita la test-third-party-cookie-phaseout marca de Chrome.

Habilita la función experimental de Chrome

Para habilitar la marca de Chrome necesaria, ve a chrome://flags#test-third-party-cookie-phaseout desde la barra de direcciones y cambia la marca a Enabled. Asegúrate de reiniciar el navegador después de cambiar las marcas.

Inicia Chrome con un conjunto de sitios web relacionados local

Para iniciar Chrome con un conjunto de sitios web relacionados declarado de forma local, crea un objeto JSON que contenga las URLs que son miembros de un conjunto y pásalo a --use-related-website-set.

Obtén más información para ejecutar Chromium con marcas.

--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/

Ejemplo

Para habilitar los conjuntos de sitios web relacionados de forma local, debes habilitar test-third-party-cookie-phaseout en chrome://flags y ejecutar Chrome desde la línea de comandos con la marca --use-related-website-set y el objeto JSON que contiene las URLs que son miembros de un conjunto.

--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/

Verifica que tienes acceso a las cookies de sitios cruzados

Llama a las APIs (rSA o rSAFor) desde los sitios que se están probando y valida el acceso a las cookies de sitios cruzados.

Proceso de envío de Conjuntos de sitios web relacionados

Sigue estos pasos para declarar la relación entre los dominios y especificar a qué subconjunto pertenecen.

1. Identifica tu RWS

Identifica los dominios pertinentes, incluidos el conjunto principal y los miembros del conjunto que formarán parte del Conjunto de sitios web relacionados. También identifica a qué tipo de subconjunto pertenece cada miembro del conjunto.

2. Crea tu envío de RWS

Crea una copia local (clonación o bifurcación) del repositorio de GitHub. En una rama nueva, realiza los cambios en el archivo related_website_sets.JSON para que refleje tu conjunto. Para asegurarte de que tu conjunto tenga el formato y la estructura JSON correctos, puedes usar la herramienta JSON Generator.

3. Asegúrate de que tu RWS cumpla con los requisitos técnicos

Asegúrate de que se cumplan los requisitos de formación del conjunto y los requisitos de validación del conjunto.

4. Prueba tu RWS de forma local

Antes de crear una solicitud de extracción (PR) para enviar tu conjunto, prueba tu envío de forma local para asegurarte de que pase todas las verificaciones requeridas.

5. Envía tu RWS

Envía el conjunto de sitios web relacionados creando una PR para el archivo related_website_sets.JSON en el que Chrome aloja la lista canónica de conjuntos de sitios web relacionados. (Se requiere una cuenta de GitHub para crear PR, y deberás firmar un Contrato de Licencia para Colaboradores (CLA) antes de poder colaborar con la lista).

Una vez que se crea la solicitud de extracción, se completa una serie de verificaciones para garantizar que se cumplan los requisitos del paso 3, como asegurarse de que hayas firmado el CLA y de que el archivo .well-known sea válido.

Si se realiza correctamente, la solicitud de extracción indicará que se aprobaron las verificaciones. Las PR aprobadas se combinarán manualmente en lotes en la lista canónica de Conjuntos de sitios web relacionados una vez por semana (los martes a las 12 p.m., hora del Este). Si alguna de las verificaciones falla, se notificará al usuario que envió la solicitud a través de una falla de la solicitud de extracción en GitHub. El usuario que envía la solicitud puede corregir los errores y actualizar la PR. Ten en cuenta lo siguiente:

• Si la solicitud de extracción falla, un mensaje de error proporcionará información adicional sobre el motivo por el que se pudo haber rechazado el envío. (ejemplo).
• Todas las verificaciones técnicas que rigen los envíos de conjuntos se realizan en GitHub y, en consecuencia, todas las fallas de envío que resulten de las verificaciones técnicas se podrán ver en GitHub.

Políticas empresariales

Chrome tiene dos políticas vigentes para satisfacer las necesidades de los usuarios empresariales:

• Los sistemas que no puedan integrarse con los Conjuntos de sitios web relacionados pueden inhabilitar la función en todas las instancias empresariales de Chrome con la política RelatedWebsiteSetsEnabled.
  • Algunos sistemas empresariales tienen sitios solo para uso interno (como una intranet) con dominios registrables que difieren de los dominios de su Conjunto de sitios web relacionados. Si necesitan tratar estos sitios como parte de su conjunto de sitios web relacionados sin exponerlos públicamente (ya que los dominios pueden ser confidenciales), pueden aumentar o anular su lista pública de conjuntos de sitios web relacionados con la política RelatedWebsiteSetsOverrides.

Chrome resuelve cualquier intersección de los conjuntos públicos y empresariales de una de las siguientes dos maneras, según si se especifican replacements o additions.

Por ejemplo, para el conjunto público {primary: A, associated: [B, C]}, haz lo siguiente:

Soluciona problemas relacionados con los Conjuntos de sitios web relacionados

"Instrucción del usuario" y "gesto del usuario"

Una "instrucción del usuario" y un "gesto del usuario" son diferentes. Chrome no mostrará un mensaje de permiso a los usuarios para los sitios que se encuentren en el mismo conjunto de sitios web relacionados, pero Chrome aún requiere que el usuario haya interactuado con la página. Antes de otorgar el permiso, Chrome requiere un gesto del usuario, también llamado "interacción del usuario" o "activación del usuario". Esto se debe a que el uso de la API de Storage Access fuera del contexto de un conjunto de sitios web relacionados (es decir, requestStorageAccess()) también requiere un gesto del usuario, debido a los principios de diseño de la plataforma web.

Acceder a las cookies o al almacenamiento de otros sitios

Los Conjuntos de sitios web relacionados no combinan el almacenamiento de diferentes sitios, sino que solo permiten llamadas requestStorageAccess() más sencillas (sin mensajes). Los Conjuntos de sitios web relacionados solo reducen la fricción del usuario al usar la API de Storage Access, pero no dictan qué hacer una vez que se restablece el acceso. Si A y B son sitios diferentes en el mismo Conjunto de sitios web relacionados, y A incorpora B, B puede llamar a requestStorageAccess() y obtener acceso al almacenamiento de origen sin solicitarle permiso al usuario. Los conjuntos de sitios web relacionados no realizan ninguna comunicación entre sitios. Por ejemplo, configurar un conjunto de sitios web relacionados no hará que las cookies que pertenecen a B comiencen a enviarse a A. Si quieres compartir esos datos, deberás hacerlo tú mismo, por ejemplo, enviando un window.postMessage desde un iframe de B a un iframe de A.

Acceso a cookies sin particionar de forma predeterminada

Los Conjuntos de sitios web relacionados no permiten el acceso implícito a cookies sin particionar sin invocar ninguna API. Las cookies entre sitios no están disponibles de forma predeterminada en el conjunto. Los Conjuntos de sitios web relacionados solo permiten que los sitios del conjunto omitir el mensaje de permiso de la API de Storage Access. Un iframe debe llamar a document.requestStorageAccess() si quiere acceder a sus cookies, o bien la página de nivel superior puede llamar a document.requestStorageAccessFor().

Enviar comentarios

Enviar un conjunto en GitHub y trabajar con la API de Storage Access y la API de requestStorageAccessFor son oportunidades para compartir tu experiencia con el proceso y los problemas que encuentres.

Para participar en debates sobre los Conjuntos de sitios web relacionados, haz lo siguiente:

• Únete a la lista de distribución pública de Related Website Sets.
  • Informa problemas y sigue la discusión en el repositorio de GitHub de Related Website Sets.