Contenido condicional

El contenido condicional te permite controlar quién puede ver contenido específico de tu documentación en función de las variables de usuario. La visibilidad del contenido se gestiona mediante audiencias, que definen condiciones que se evalúan frente a las variables enviadas en un JWT firmado. Esto funciona en un proyecto privado mediante el inicio de sesión personalizado y en un sitio de documentación público mediante un enlace firmado. También puedes indicar directamente las audiencias de un lector, que es como obtienen las suyas los lectores que inician sesión mediante SSO de lectores.

Hay dos formas de usar el contenido condicional:

  • Audiencias a nivel de página: aplica una audiencia a una página completa para controlar quién puede acceder a ella.

  • Bloques condicionales: usa bloques condicionales para controlar la visibilidad de contenido específico dentro de una página.

Ambos métodos usan el mismo sistema de audiencias y las mismas condiciones.

Gestión de audiencias

Las audiencias se crean y se gestionan en la configuración del proyecto. Cada audiencia tiene un ID y un conjunto de condiciones que determinan cuándo el contenido es visible.

Crear una audiencia

Para crear una nueva audiencia:

  1. Abre la configuración del proyecto → Contenido → Audiencias.

  2. Haz clic en Crear audiencia.

  3. Introduce un ID de audiencia (este ID se usará para hacer referencia a la audiencia). Debe empezar con una letra minúscula y solo puede contener letras minúsculas, números y guiones.

  4. Haz clic en Guardar.

Editar las condiciones de una audiencia

Para editar las condiciones de una audiencia:

  1. En la configuración del proyecto → Audiencias, busca la audiencia que quieres editar.

  2. Haz clic en Editar en la fila de la audiencia. El generador de expresiones se abre en el mismo lugar, debajo de la fila.

  3. Haz clic en Añadir condición para añadir una condición o modifica una existente.

  4. Haz clic en Guardar.

En el generador de expresiones puedes añadir tantas condiciones como necesites. Cada condición comprueba que una variable coincida con un valor. Deben cumplirse todas las condiciones para que se muestre el contenido.


Eliminar una audiencia

Para eliminar una audiencia:

  1. En la configuración del proyecto → Audiencias, busca la audiencia que quieres eliminar.

  2. Haz clic en Eliminar en la fila de la audiencia y confirma.

Eliminar audiencias

Si una audiencia se usa en páginas o bloques condicionales, eliminarla puede afectar a la visibilidad del contenido.

Establecer la audiencia de una página

Puedes aplicar una audiencia a una página completa para controlar quién puede acceder a ella. Las audiencias de página son jerárquicas, es decir, las páginas secundarias heredan automáticamente la audiencia de su página principal.

Aplicar una audiencia a una página

Para establecer una audiencia en una página:

  1. Abre la página que quieres restringir.

  2. En la barra lateral derecha, abre Información de la página y ve a la pestaña Configuración.

  3. En Audiencia, selecciona una audiencia en el menú desplegable.

  4. A partir de ahora la página solo será visible para los lectores que cumplan las condiciones de la audiencia.

De forma predeterminada, todas las páginas tienen su audiencia establecida en public, es decir, son visibles para todos.

Indicador de audiencia

Cuando una página tiene una audiencia establecida, los editores verán un icono de candado junto al título de la página en el índice, que indica que la página tiene acceso restringido.

Bloques condicionales

Los bloques condicionales te permiten controlar la visibilidad de contenido específico dentro de una página. A cada bloque condicional se le asigna una audiencia.

Para cambiar la audiencia de un bloque condicional, haz clic en la etiqueta de la audiencia (con fondo gris) en la parte superior del bloque y selecciona una de las audiencias disponibles.

Más información sobre el uso de los bloques condicionales.

Cómo se evalúan las audiencias

Cuando un lector accede a tu documentación, su audiencia se determina comparando las variables de su token JWT con las condiciones de las audiencias.

Las variables se envían mediante el objeto vars en el payload del JWT al usar el inicio de sesión personalizado. Por ejemplo:

const payload = {
version: 1,
vars: {
userId: 1234,
plan: "enterprise",
region: "us"
}
};

Estas variables se comparan después con las condiciones definidas en cada audiencia para determinar a qué contenido puede acceder el lector.

Indicar audiencias directamente

En lugar de comparar condiciones, un token puede enumerar las audiencias del lector por sus IDs en una variable _audience:

const payload = {
version: 1,
vars: {
userId: 1234,
_audience: ["enterprise", "beta"]
}
};

También sirve una cadena separada por comas como "enterprise,beta". Cuando _audience está presente, el lector pertenece exactamente a las audiencias que indica y no se comprueba ninguna condición, de modo que una lista vacía no lo incluye en ninguna audiencia.

Audiencias con SSO de lectores

Los lectores que inician sesión mediante SSO de lectores no tienen variables con las que comparar condiciones. Para incluirlos en audiencias, añade un atributo _audience en tu proveedor de identidad con los IDs de sus audiencias, en la misma forma de lista o separada por comas. Un lector cuyo inicio de sesión no incluya _audience solo ve el contenido que no está asignado a ninguna audiencia.

Las audiencias se leen cuando el lector inicia sesión, por lo que un cambio en tu proveedor de identidad se aplica desde su siguiente inicio de sesión.

El SSO de lectores establece audiencias tanto si tu documentación es privada como pública. En un sitio de documentación público, los lectores que inician sesión ven el contenido de sus audiencias y los demás ven la documentación pública. Un sitio de documentación público no tiene botón de inicio de sesión, así que los lectores inician sesión desde tu proveedor de identidad.

Para configurar el SSO de lectores, contáctanos.

Identificar lectores en un sitio de documentación público

Las audiencias no se limitan a la documentación privada. Un sitio de documentación público puede identificar a un lector mediante un enlace firmado, de modo que puedes adaptar lo que ve cada lector sin proteger tu documentación con un inicio de sesión.

Tu método de acceso sigue siendo Público. Lo único que debes configurar es una clave de API con el permiso access.write Modificar reglas de acceso, que es la clave con la que se firma tu token.

Para identificar a un lector:

  1. Firma un JWT en tu backend exactamente como harías para el inicio de sesión personalizado, incluyendo los datos del lector en el objeto vars. Es obligatorio indicar una caducidad.

  2. Envía al lector a tu sitio de documentación con el token en un parámetro de consulta jwt, por ejemplo https://docs.pied-piper.com/getting-started?jwt=<token>.

  3. Tu sitio de documentación verifica el token, aplica las audiencias a las que corresponde el lector y elimina el token de la URL.

Un lector que llega sin token, o con uno caducado o que no se puede verificar, no es enviado a una pantalla de inicio de sesión. Ve la documentación pública, que es todo lo que no has asignado a una audiencia.

Solo un token firmado establece audiencias

Las variables inyectadas mediante los parámetros de consulta vars y hvars o la cookie vars personalizan el texto, pero no incluyen al lector en una audiencia. Un lector puede modificarlas, por lo que nunca pueden desbloquear contenido restringido por audiencia. Firma un JWT para cualquier cosa que necesites restringir.

Qué debes saber
  • Enlaza a una página dentro de la ruta base de tu documentación. Si tu documentación se sirve en pied-piper.com/docs, un enlace a pied-piper.com/?jwt=... envía al lector a /docs y se pierde el resto de la ruta.

  • Un lector que ya ha sido identificado no se identifica de nuevo hasta que caduque su token. Enviar un nuevo enlace con variables distintas no tiene efecto mientras el anterior siga siendo válido, así que conviene usar caducidades cortas.

  • El botón Generar JWT de la configuración del proyecto → Acceso solo está disponible cuando el método de acceso es JWT, así que firma tú mismo tus tokens de prueba.

  • error_redirect_url no tiene efecto en un proyecto público, ya que no hay una pantalla de error desde la que redirigir.

Los resultados de búsqueda se filtran según la audiencia del lector. Los lectores solo verán resultados de búsqueda de las páginas y el contenido a los que tienen acceso, de modo que el contenido restringido permanece oculto incluso en la búsqueda.

El asistente de IA responde del mismo modo. Se basa en la documentación que el lector tiene derecho a ver, de manera que un lector identificado puede preguntar por contenido restringido por audiencia y encontrarlo, mientras que a un lector no identificado se le responde únicamente con la documentación pública.

Si necesitas más de la función de contenido condicional, no dudes en contactarnos.

  Última actualización