Développeurs · Freedam Picker

Laissez vos utilisateurs choisir des médias Freedam dans votre application

Ajoutez à un CMS, au back-office d'une boutique en ligne ou à un outil interne un bouton qui ouvre Freedam pour choisir des médias. Les utilisateurs recherchent dans l'espace de travail et choisissent des médias dans la limite de leurs propres droits d'accès. Votre page reçoit des identifiants de médias stables et des URL publiées, prêts à afficher.

Lire le guide de démarrage Ouvrir le playground

Le code

Un script et un appel de fonction

Un administrateur de l'espace de travail crée une intégration : les origines autorisées à ouvrir le picker, les médias qu'il propose et le canal de publication de ce qu'il insère. La page Intégrations vous donne ensuite un code comme celui-ci, avec l'hôte de l'espace de travail et la clé d'intégration déjà renseignés.

open() se résout avec les médias choisis, ou avec null quand l'utilisateur annule. Les callbacks et les événements DOM signalent le même résultat pour les pages qui les préfèrent.

Balise 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>

Modes d'affichage

Dans une fenêtre, un onglet, par-dessus votre page ou à l'intérieur

Une seule option, mode, définit l'affichage, et chaque mode renvoie le même résultat. Quand le navigateur ne laisse pas le picker se connecter à l'intérieur de votre page, il continue dans une fenêtre avec les mêmes options. Les modes modal et inline nécessitent la version 1.1 du SDK, le mode tab la version 1.2.

mode: 'popup'

Dans une fenêtre

Le mode par défaut. Le picker s'ouvre dans une fenêtre sur l'hôte de l'espace de travail. La connexion, y compris l'authentification unique et les clés d'accès, se fait dans une seconde fenêtre.

mode: 'tab'

Dans un nouvel onglet

Le picker s'ouvre dans un nouvel onglet du navigateur, en pleine largeur. Il conserve window.opener pour envoyer la sélection à votre page, puis se ferme.

mode: 'modal'

Par-dessus votre page

Une iframe sur un fond assombri, en plein écran sur les petits écrans, qui garde le focus jusqu'à ce que l'utilisateur la ferme.

mode: 'inline'

Dans votre page

Une iframe qui remplit un élément de votre choix, comme un panneau latéral de votre éditeur, d'au moins 480 pixels de haut.

Ce que reçoit votre page

Un objet par média, avec des URL prêtes à l'emploi

url: Le média dans le format choisi par l'utilisateur, sur une URL publique du canal de publication de l'intégration.
url_template: La même URL signée avec {options} à la place de la taille : construisez n'importe quelle largeur, n'importe quel recadrage ou format de fichier sans appeler Freedam. widths liste les largeurs qu'elle sert, pour un srcset.
focus_point: La position du sujet, en pourcentage, prête pour object-position quand votre mise en page recadre l'image.
metadata: Les champs que l'intégration expose, comme le titre, le texte alternatif et le crédit, dans la limite de ce que l'utilisateur peut voir.
player_url: Pour les vidéos : le lecteur avec les réglages choisis dans le picker, son code d'intégration et le flux HLS.
usage_token: Déclare la page qui affiche le média, pour que l'espace de travail sache où chaque média est utilisé.

Les images, les vidéos et les documents ont chacun leurs propres champs. La référence les liste tous, avec le JSON Schema du payload.

Une image, version abrégée

{
  "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 et web component

Chargez-le selon la façon dont votre application est construite

Le même SDK existe sous forme de paquet npm @freedam/picker, et le script définit aussi un élément <freedam-picker> pour les pages où vous ne voulez pas écrire de JavaScript. Le guide de démarrage contient des exemples React et 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>

Versions

Des mises à jour sans modifier votre code, ou une version figée

/sdk/picker/v1/picker.js
La dernière version 1.x. Le code de la page Intégrations l'utilise.
/sdk/picker/{version}/picker.js
Une version exacte, dont le fichier ne change jamais. Chargez-la avec sa valeur d'intégrité, indiquée dans la référence.
protocol=1
Les messages entre le picker et votre page ont leur propre version. Freedam continue d'accepter une version précédente pendant au moins six mois.

Ce dont le picker s'occupe

Origines autorisées

Le picker ne s'ouvre que depuis les origines listées par l'intégration, et envoie la sélection à cette origine exacte, jamais à une autre page.

Les droits d'accès de chacun

Chaque utilisateur voit les médias qu'il a le droit de consulter dans Freedam, dans le respect des règles de l'intégration. Les visiteurs sans compte peuvent aussi choisir des médias, quand un administrateur active cet accès.

Aucun token sur votre page

Votre page charge un script et appelle une fonction. Elle ne détient aucun token d'API : le picker fonctionne sur l'hôte de l'espace de travail et agit pour le compte de la personne qui l'utilise.

URL publiées

Les médias insérés sont publiés sur un canal de l'espace de travail. Leurs URL restent valides jusqu'à ce que le média soit dépublié ou que ses droits d'utilisation prennent fin.

Servi par votre espace de travail

Le script provient de l'hôte de l'espace de travail, sans CDN tiers. Une URL versionnée avec une valeur Subresource Integrity fige une version exacte.

Léger et typé

Quelques kilo-octets, aucune dépendance à l'exécution, des types TypeScript et un JSON Schema pour le payload. Les versions suivent le versionnage sémantique.

Développeurs · Freedam Picker

Essayez le picker avec vos propres options

Le playground ouvre le picker sur un espace de travail de démonstration, écrit le code correspondant aux options que vous choisissez et affiche le payload que votre page recevrait.

Ouvrir le playground Lire la référence