Con la integración de Kontainer con Storyblok, tus editores pueden elegir imágenes, vídeos y archivos directamente desde tu DAM sin subir archivos a Storyblok. Storyblok solo guarda una referencia al archivo; el archivo en sí permanece en Kontainer y se entrega a través de la CDN.

Ve a la página de integraciones de Kontainer para saber más sobre los casos de uso, las ventajas y más.

Requisitos

Un espacio (space) de Storyblok y derechos de administrador sobre él: la extensión no se puede instalar sin ellos
Una cuenta de Kontainer (https://yourcompany.kontainer.com)
La integración con Storyblok activada en tu cuenta de Kontainer: confirma con tu responsable de cuenta que está incluida en tu plan

¿Qué se guarda y dónde?

Tus archivos se quedan en Kontainer. No se sube nada a la biblioteca de archivos de Storyblok. Storyblok guarda un valor de archivo estándar que apunta a la CDN de Kontainer, con la referencia de Kontainer a su lado:

filename: la URL de la CDN, incluida la plantilla de descarga que hayas elegido
alt, title: se toman de la descripción del archivo en Kontainer
focus: el punto focal que has definido en Kontainer, en el formato propio de Storyblok
meta_data.kontainer_file_id, kontainer_folder_id, kontainer_url: identificadores para recuperar el archivo
meta_data.kontainer_thumbnail_url, kontainer_extension, kontainer_type

Como el texto alternativo y el punto focal viajan con la referencia, los editores no tienen que volver a escribir los metadatos en Storyblok, y al sustituir un archivo en Kontainer se actualiza en todos los lugares donde se usa.

Primeros pasos

1. Activa la integración en Kontainer

Pide a tu responsable de cuenta que active la integración con Storyblok en tu cuenta de Kontainer. Esto permite que Storyblok incruste el selector de archivos de Kontainer y es necesario para que el selector se abra.

2. Instala la extensión en Storyblok

Abre el enlace de instalación, elige el espacio en el que quieres instalarla y confirma:

https://app.storyblok.com/#/install/kontainer@asset-picker

Necesitas derechos de administrador en el espacio de destino. Instálala una vez por espacio.

3. Añade el campo de Kontainer a un bloque

En tu espacio, ve a «Block Library» (biblioteca de bloques), abre el bloque en el que quieras el selector y añade un campo nuevo. Define su tipo como «Plugin» y elige kontainer en la lista.

4. Apunta el campo a tu Kontainer

Con el campo seleccionado, añade la opción kontainerHost y define su valor como tu dominio de Kontainer, por ejemplo yourcompany.kontainer.com (con o sin https://).

Storyblok guarda las opciones de los plugins por campo, así que repite este paso en todos los campos que usen el selector. Storyblok no traslada los valores de las opciones de un espacio a otro, así que cada espacio se configura por separado.

5. Elige archivos

Abre una historia (story) que use el bloque y haz clic en «Select from Kontainer» (elegir desde Kontainer) en el campo. La primera vez, inicia sesión con tu nombre de usuario y tu contraseña habituales de Kontainer. Navega, busca y filtra tu biblioteca como siempre, aplica opcionalmente una plantilla de descarga (recorte, cambio de tamaño, formato) y elige el archivo.

El campo muestra entonces una vista previa y el nombre del archivo. «Replace asset» (reemplazar el archivo) elige otro archivo y «Remove asset» (quitar el archivo) vacía el campo. Los archivos que no son imágenes, como PDF y vídeos, muestran una tarjeta con el tipo de archivo en lugar de una vista previa.

Opciones del campo

Opción	Obligatoria	Valor
`kontainerHost`	Sí	Tu dominio de Kontainer, por ejemplo `yourcompany.kontainer.com`
`mode`	No	`external` (predeterminado) enlaza el archivo en Kontainer. `import` lo copia a la biblioteca de archivos de Storyblok.
`storyblokRegion`	Solo con import	`eu` (predeterminado), `us`, `ca`, `ap` o `cn`
`storyblokManagementToken`	Solo con import	Un token de acceso personal de Storyblok con acceso de escritura a los archivos
`maxImportMb`	No	El archivo más grande que acepta la importación; por defecto `50`

Opcional: importar archivos a Storyblok

Algunos equipos exigen que todos los archivos estén alojados en el propio Storyblok. Si defines mode como import, el archivo se copia a la biblioteca de archivos del espacio en lugar de enlazarse. El archivo es entonces un archivo normal de Storyblok y el servicio de imágenes de Storyblok puede transformarlo.

Dos cosas que debes tener en cuenta antes de pasar un campo al modo de importación:

La copia deja de actualizarse cuando el archivo cambia en Kontainer.
El token de gestión es una opción del campo, lo que significa que se entrega al navegador de todos los editores que usan ese campo. Crea para ello un token con alcance limitado: en Storyblok, dale solo el alcance de archivos (Assets) y restríngelo al único espacio que lo necesita. No reutilices un token que tenga acceso a toda tu cuenta.

Usar el archivo en tu frontend

El campo devuelve un objeto de archivo estándar de Storyblok, así que se comporta como cualquier otro campo de archivo:

const { filename, alt, focus } = story.content.hero;

Solicita el archivo desde filename: se sirve desde la CDN de Kontainer.

El servicio de imágenes de Storyblok no cambia el tamaño ni recorta una URL externa, así que usa los parámetros de transformación propios de Kontainer, o una plantilla de descarga elegida al seleccionar el archivo, para controlar el tamaño y el formato entregados. El punto focal está disponible tanto como valor focus de Storyblok como en coordenadas de píxeles sin procesar en meta_data.

Soporte

Si necesitas ayuda para configurar el plugin de Storyblok, nuestro equipo de soporte te ayudará encantado.

Escribe a: support@kontainer.com