mode: 'popup'En una ventana
El modo predeterminado. El picker se abre en una ventana en el host del espacio de trabajo. El inicio de sesión, incluidos el inicio de sesión único y las llaves de acceso, se hace en una segunda ventana.
Desarrolladores · Freedam Picker
Deja que las personas elijan recursos de Freedam dentro de tu aplicación
Añade a un CMS, al back office de una tienda en línea o a una herramienta interna un botón que abre Freedam. Las personas buscan en el espacio de trabajo y eligen recursos dentro de sus propios derechos de acceso. Tu página recibe ID de recursos estables y URL publicadas, listas para mostrar.
El fragmento
Un script y una llamada a una función
Un administrador del espacio de trabajo crea una integración: los orígenes autorizados a abrir el picker, los recursos que ofrece y el canal de publicación de lo que inserta. La página Integraciones te da entonces un código como este, con el host del espacio de trabajo y la clave de la integración ya rellenados.
open() se resuelve con los recursos elegidos, o con null cuando la persona cancela. Los callbacks y los eventos DOM informan del mismo resultado para las páginas que los prefieren.
Etiqueta script
<script src="https://acme.freedam.io/sdk/picker/v1/picker.js"></script>
<button type="button" id="choose">Choose from Freedam</button>
<script>
document.getElementById('choose').addEventListener('click', async () => {
const assets = await Freedam.picker.open({
workspace: 'acme.freedam.io',
integration: 'w5r8n2c4t7bd',
});
if (assets) showImage(assets[0].url, assets[0].metadata.alt);
});
</script>Modos de visualización
En una ventana, en una pestaña, sobre tu página o dentro de ella
Una sola opción, mode, define la visualización, y todos los modos devuelven el mismo resultado. Cuando el navegador no permite que el picker inicie sesión dentro de tu página, continúa en una ventana con las mismas opciones. Los modos modal e inline requieren la versión 1.1 del SDK, el modo tab la versión 1.2.
mode: 'tab'En una pestaña nueva
El picker se abre en una pestaña nueva del navegador, a todo el ancho. Conserva window.opener para enviar la selección a tu página y luego se cierra.
mode: 'modal'Sobre tu página
Un iframe sobre un fondo oscurecido, a pantalla completa en pantallas pequeñas, con el foco dentro de él hasta que la persona lo cierra.
mode: 'inline'Dentro de tu página
Un iframe que ocupa un elemento que eliges, como un panel lateral de tu editor, de al menos 480 píxeles de alto.
Lo que recibe tu página
Un objeto por recurso, con URL listas para usar
url- El recurso en el formato que eligió la persona, en una URL pública del canal de publicación de la integración.
url_template- La misma URL firmada con {options} en lugar del tamaño: construye cualquier ancho, recorte o formato de archivo sin llamar a Freedam. widths enumera los anchos que sirve, para un srcset.
focus_point- Dónde está el sujeto, en porcentaje, listo para object-position cuando tu diseño recorta la imagen.
metadata- Los campos que expone la integración, como el título, el texto alternativo y el crédito, dentro de lo que la persona puede ver.
player_url- Para los videos: el reproductor con la configuración elegida en el picker, su código de inserción y el stream HLS.
usage_token- Declara la página que muestra el recurso, para que el espacio de trabajo vea dónde se usa cada recurso.
Las imágenes, los videos y los documentos tienen cada uno sus propios campos. La referencia los enumera todos, con el JSON Schema del payload.
Una imagen, abreviada
{
"gaid": "IM-20260309-UDXZH8PP6VPW",
"type": "image",
"url": "https://acme.freedam.io/i/w=2048,fmt=hero/IM-…",
"url_template": "https://acme.freedam.io/i/{options}/IM-…",
"widths": [128, 256, 512, 1024, 2048],
"focus_point": { "x": 45.2, "y": 38.7 },
"metadata": {
"title": "Head office, Lyon",
"alt": "Glass front at sunset",
"credit": "Studio Martin"
},
"usage_id": "9d4e1f3a-6b2c-4f8e-a1d7-3c5b9e2f0a64",
"usage_token": "fdu_…",
"choice": { "format": "hero", "file_format": null }
}npm y web component
Cárgalo según cómo esté construida tu aplicación
El mismo SDK está disponible como el paquete npm @freedam/picker, y el script también define un elemento <freedam-picker> para las páginas en las que no quieres escribir JavaScript. La guía de inicio rápido tiene ejemplos para React y Vue.
npm install @freedam/picker
import { open } from '@freedam/picker';
const assets = await open({
workspace,
integration,
select: 'multiple',
types: ['image', 'video'],
});<freedam-picker workspace="acme.freedam.io" integration="w5r8n2c4t7bd">
<button type="button">Choose from Freedam</button>
</freedam-picker>Versiones
Actualizaciones sin cambiar el código, o una versión fija
/sdk/picker/v1/picker.jsLa última versión 1.x. La usa el fragmento de la página Integraciones.
/sdk/picker/{version}/picker.jsUna versión exacta, cuyo archivo nunca cambia. Cárgala con su valor de integridad, que figura en la referencia.
protocol=1Los mensajes entre el picker y tu página tienen su propia versión. Freedam sigue aceptando una versión anterior durante al menos seis meses.
De qué se encarga el picker
Orígenes autorizados
El picker solo se abre desde los orígenes que enumera la integración, y envía la selección a ese origen exacto, nunca a otra página.
Los derechos de acceso de cada persona
Las personas ven los recursos que pueden ver en Freedam, dentro de las reglas de la integración. Los visitantes sin cuenta también pueden elegir recursos, cuando un administrador activa ese acceso.
Ningún token en tu página
Tu página carga un script y llama a una función. No contiene ningún token de API: el picker se ejecuta en el host del espacio de trabajo y actúa en nombre de la persona que lo usa.
URL publicadas
Los recursos insertados se publican en un canal del espacio de trabajo. Sus URL siguen siendo válidas hasta que se despublica el recurso o terminan sus derechos de uso.
Servido por tu espacio de trabajo
El script viene del host del espacio de trabajo, sin CDN de terceros. Una URL versionada con un valor de Subresource Integrity fija una versión exacta.
Pequeño y tipado
Unos pocos kilobytes, ninguna dependencia en tiempo de ejecución, tipos de TypeScript y un JSON Schema para el payload. Las versiones siguen el versionado semántico.
Desarrolladores · Freedam Picker
Prueba el picker con tus propias opciones
El playground abre el picker en un espacio de trabajo de demostración, escribe el código de las opciones que elijas y muestra el payload que recibiría tu página.