Contenido condicional

El contenido condicional te permite controlar quién puede ver contenido específico de tu documentación en función de 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 por 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 el menú junto a la audiencia.

3. Selecciona Editar.

4. Usa el generador de expresiones para añadir o modificar condiciones.

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 el menú junto a la audiencia.

3. Selecciona Eliminar.

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 Ajustes.

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, lo que significa que 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, lo que indica que la página tiene el acceso restringido.

Bloques condicionales

Los bloques condicionales te permiten controlar la visibilidad de contenido específico dentro de una página. Cada bloque condicional tiene asignada una audiencia.

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

Más información sobre cómo usar 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 la audiencia.

Las variables se envían mediante el objeto vars en la carga útil del JWT cuando se usa el inicio de sesión personalizado. Por ejemplo:

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:

También funciona una cadena separada por comas como "enterprise,beta". Cuando está presente _audience, el lector pertenece exactamente a las audiencias que indica y no se comprueba ninguna condición, por lo 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 que las condiciones puedan comparar. 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.

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 poner tu documentación tras 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 igual que 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 con las que coincide 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.

Audiencias y búsqueda

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, lo que garantiza que el contenido restringido permanezca oculto también 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 modo que un lector identificado puede preguntar sobre contenido restringido por audiencia y encontrarlo, mientras que a un lector no identificado se le responde solo con la documentación pública.

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