Widget intégrable

Ajoutez la conversion d'images à votre site web avec une seule balise script.

Démarrage rapide

Ajoutez cette balise script n'importe où dans votre HTML. Le widget s'affiche immédiatement après la balise :

<script src="https://koalapic.com/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-mode="all"
        data-theme="auto"></script>

C'est tout ! Le widget crée son propre conteneur et démarre automatiquement.

Options de configuration

Configurez le widget via les attributs data-* de la balise script ou les options transmises à KoalaPic.init() :

Option	Attribut de données	Par défaut	Description
`mode`	`data-mode`	`"all"`	Mode du widget : `convert`, `compress`, `resize`, ou `all`
`theme`	`data-theme`	`"auto"`	Thème de couleur : `light`, `dark`, ou `auto` (suit le système)
`accent_color`	`data-accent-color`	`"#3b82f6"`	Couleur d'accent principale (hex). Exemple : `#8b5cf6`
`allowed_formats`	`data-allowed-formats`	`(all)`	Formats de sortie séparés par des virgules : avif, bmp, gif, heic, ico, jpg, pdf, png, svg, tiff, webp
`max_file_size`	`data-max-file-size`	`50`	Taille maximale de téléversement en Mo (1–50)
`callback_url`	`data-callback-url`	`(none)`	URL vers laquelle envoyer les résultats de conversion (POST) une fois terminée
`hide_branding`	`data-hide-branding`	`false`	Hide "Powered by KoalaPic" footer
`api_key`	`data-api-key`	`(none)`	Clé API pour des requêtes authentifiées avec des limites de débit plus élevées
`width`	`data-width`	`"100%"`	Largeur de l'iframe du widget (toute valeur CSS)
`height`	`data-height`	`"500px"`	Hauteur de l'iframe du widget (s'ajuste automatiquement via des événements de redimensionnement)
`lang`	`data-lang`	`(auto)`	Code de langue (par ex. `fr`, `de`, `ar`). Détecté automatiquement depuis la page ou le navigateur si omis.

Toutes les options prennent en charge à la fois snake_case et camelCase dans l'API JavaScript (par ex. accent_color ou accentColor).

API JavaScript

Pour un contrôle total, utilisez KoalaPic.init() pour créer des widgets par programmation :

<div id="converter"></div>
<script src="https://koalapic.com/static/widget/koalapic-widget.js"></script>
<script>
  var iframe = KoalaPic.init('#converter', {
    mode: 'convert',
    theme: 'dark',
    accentColor: '#8b5cf6',
    allowedFormats: ['jpg', 'png', 'webp'],
    maxFileSize: 25,
    apiKey: 'kp_your_key_here'
  });
</script>

Référence de l'API

Méthode	Description
`KoalaPic.init(selector, config)`	Crée un widget à l'intérieur d'un élément conteneur. Renvoie l'élément iframe. Accepte une chaîne de sélecteur CSS ou un élément DOM.
`KoalaPic.on(event, callback)`	Enregistre un écouteur d'événement. Événements
`KoalaPic.version`	Chaîne de version de la bibliothèque.

Gestion des événements

Écoutez les événements du cycle de vie de la conversion avec KoalaPic.on() :

KoalaPic.on('conversion_completed', function(result) {
  console.log('Conversion ID:', result.id);
  console.log('Download token:', result.download_token);
  console.log('Format:', result.output_format);
  console.log('File size:', result.file_size);
});

KoalaPic.on('conversion_started', function(data) {
  console.log('Conversion started in mode:', data.mode);
});

KoalaPic.on('conversion_failed', function(data) {
  console.error('Conversion failed:', data.error);
});

Types d'événements

Événement	Charge utile	Description
`conversion_started`	`{ mode }`	Conversion soumise à l'API
`conversion_completed`	`{ id, download_token, output_format, file_size }`	La conversion s'est terminée avec succès
`conversion_failed`	`{ error }`	Échec de la conversion ou de la requête API

Vous pouvez aussi écouter directement les événements postMessage bruts :

window.addEventListener('message', function(event) {
  if (event.data.type === 'koalapic:conversion_complete') {
    console.log(event.data.payload);
  }
});

URL de rappel

Définissez callback_url pour envoyer automatiquement (POST) les résultats de conversion à votre serveur :

<script src="https://koalapic.com/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-callback-url="https://yoursite.com/api/conversion-hook"></script>

Votre point de terminaison reçoit un POST JSON contenant le résultat de la conversion :

{
  "id": "abc123",
  "download_token": "token_xyz",
  "output_format": "webp",
  "file_size": 45210
}

Style et personnalisation

Le widget s'affiche à l'intérieur d'une iframe, il n'entre donc pas en conflit avec les styles de votre page. Vous pouvez personnaliser le conteneur :

<!-- Fixed-width centered widget -->
<div id="widget" style="max-width: 600px; margin: 0 auto;"></div>
<script src="https://koalapic.com/static/widget/koalapic-widget.js"></script>
<script>
  KoalaPic.init('#widget', {
    width: '100%',
    height: '500px',
    accentColor: '#e11d48',
    theme: 'dark'
  });
</script>

L'iframe a un border-radius: 8px par défaut. Remplacez-le sur l'élément iframe renvoyé :

var iframe = KoalaPic.init('#widget', { mode: 'compress' });
iframe.style.borderRadius = '16px';
iframe.style.boxShadow = '0 4px 24px rgba(0,0,0,0.1)';

Limitation de débit

Pour une utilisation en production, nous recommandons de transmettre une clé API via l'attribut data-api-key. Les requêtes anonymes sont limitées à 10 conversions par minute. Les requêtes authentifiées bénéficient de 30 par minute.

Obtenez votre clé API gratuite sur https://koalapic.com/dashboard/keys/

Exemples

Widget compression uniquement

<script src="https://koalapic.com/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-mode="compress"
        data-theme="light"
        data-accent-color="#10b981"></script>

Redimensionnement uniquement avec formats limités

<script src="https://koalapic.com/static/widget/koalapic-widget.js"
        data-koalapic-widget
        data-mode="resize"
        data-allowed-formats="jpg,png,webp"
        data-max-file-size="10"></script>

Plusieurs widgets sur une même page

<div id="converter-1"></div>
<div id="converter-2"></div>
<script src="https://koalapic.com/static/widget/koalapic-widget.js"></script>
<script>
  KoalaPic.init('#converter-1', { mode: 'convert' });
  KoalaPic.init('#converter-2', { mode: 'compress' });
</script>

Aperçu en direct

Voici le widget en action :