Options d'intégration avancées

Options d'intégration avancées

Au-delà des approches basiques par balise script et div, le widget d'intégration ZenFlip fournit une API JavaScript programmatique pour les scénarios d'intégration dynamique. Ce guide couvre l'API, l'intégration dans les applications monopage (SPA), la gestion des événements et la configuration avancée.

API programmatique

Le script d'intégration expose un objet global ZenFlip avec des méthodes pour créer et gérer les intégrations.

ZenFlip.embed(target, options)

Créez une instance d'intégration de manière programmatique.

Paramètres :

Retourne : Un objet d'instance d'intégration avec les propriétés iframe, wrapper et destroy(), ou null si la cible n'a pas été trouvée.

`javascript // Avec un sélecteur CSS const instance = ZenFlip.embed("#flipbook-container", { pub: "product-catalog-2026", width: "100%", height: 700, autoFlip: false, startPage: 1 });

// Avec un élément DOM const el = document.getElementById("my-embed"); const instance = ZenFlip.embed(el, { pub: "annual-report-2025", height: 600 }); `

ZenFlip.scan()

Re-parcourez la page à la recherche de nouveaux conteneurs .zenflip-embed ajoutés au DOM après le chargement initial de la page. Ceci est essentiel pour les applications monopage où le contenu est rendu dynamiquement.

`javascript // Après l'ajout dynamique de conteneurs d'intégration au DOM document.getElementById("content").innerHTML = <div class="zenflip-embed" data-pub="new-publication" data-height="500"></div> ;

// Indiquer à ZenFlip de découvrir et initialiser les nouveaux conteneurs ZenFlip.scan(); `

Détruire une intégration

Appelez destroy() sur l'instance pour supprimer l'intégration du DOM et libérer les ressources :

`javascript const instance = ZenFlip.embed("#container", { pub: "my-pub" });

// Plus tard, supprimer l'intégration instance.destroy(); `

Intégration SPA

React

Créez un composant React réutilisable qui gère le cycle de vie de l'intégration :

`jsx import { useEffect, useRef } from "react";

function ZenFlipEmbed({ slug, width = "100%", height = 600, autoFlip = false, startPage = 1 }) { const containerRef = useRef(null); const instanceRef = useRef(null);

useEffect(() => { // S'assurer que le script d'intégration est chargé if (!window.ZenFlip) { const script = document.createElement("script"); script.src = "https://app.zenflip.io/embed.js"; script.onload = () => createEmbed(); document.head.appendChild(script); } else { createEmbed(); }

function createEmbed() { if (containerRef.current && window.ZenFlip) { instanceRef.current = window.ZenFlip.embed(containerRef.current, { pub: slug, width, height, autoFlip, startPage }); } }

return () => { if (instanceRef.current) { instanceRef.current.destroy(); instanceRef.current = null; } }; }, [slug, width, height, autoFlip, startPage]);

return <div ref={containerRef} />; }

// Utilisation <ZenFlipEmbed slug="product-catalog-2026" height={700} /> `

Vue 3

`vue <template> <div ref="embedContainer"></div> </template>

<script setup> import { ref, onMounted, onBeforeUnmount, watch } from "vue";

const props = defineProps({ slug: { type: String, required: true }, width: { type: String, default: "100%" }, height: { type: Number, default: 600 }, autoFlip: { type: Boolean, default: false }, startPage: { type: Number, default: 1 } });

const embedContainer = ref(null); let instance = null;

function loadScript() { return new Promise((resolve) => { if (window.ZenFlip) return resolve(); const script = document.createElement("script"); script.src = "https://app.zenflip.io/embed.js"; script.onload = resolve; document.head.appendChild(script); }); }

async function createEmbed() { await loadScript(); if (instance) instance.destroy(); if (embedContainer.value) { instance = window.ZenFlip.embed(embedContainer.value, { pub: props.slug, width: props.width, height: props.height, autoFlip: props.autoFlip, startPage: props.startPage }); } }

onMounted(createEmbed); watch(() => props.slug, createEmbed); onBeforeUnmount(() => { if (instance) instance.destroy(); }); </script> `

Angular

`typescript import { Component, ElementRef, Input, OnInit, OnDestroy, ViewChild } from "@angular/core";

@Component({ selector: "app-zenflip-embed", template: <div #embedContainer></div> }) export class ZenFlipEmbedComponent implements OnInit, OnDestroy { @Input() slug!: string; @Input() width = "100%"; @Input() height = 600; @Input() autoFlip = false; @Input() startPage = 1;

@ViewChild("embedContainer", { static: true }) container!: ElementRef; private instance: any = null;

ngOnInit(): void { this.loadScript().then(() => { this.instance = (window as any).ZenFlip.embed( this.container.nativeElement, { pub: this.slug, width: this.width, height: this.height, autoFlip: this.autoFlip, startPage: this.startPage } ); }); }

ngOnDestroy(): void { if (this.instance) this.instance.destroy(); }

private loadScript(): Promise<void> { return new Promise((resolve) => { if ((window as any).ZenFlip) return resolve(); const script = document.createElement("script"); script.src = "https://app.zenflip.io/embed.js"; script.onload = () => resolve(); document.head.appendChild(script); }); } } `

Gestion des événements

Le widget d'intégration communique avec la page parente via l'API postMessage. Écoutez les messages provenant de l'iframe ZenFlip pour réagir aux événements du lecteur :

`javascript window.addEventListener("message", (event) => { // Vérifier l'origine if (!event.origin.includes("zenflip.io")) return;

const { type, data } = event.data;

switch (type) { case "zenflip:page_change": console.log("Page changée vers :", data.pageNumber); break; case "zenflip:ready": console.log("Flipbook chargé, nombre total de pages :", data.pageCount); break; case "zenflip:lead_captured": console.log("Prospect soumis :", data.email); break; } }); `

Événements disponibles

Style personnalisé

Le widget d'intégration enveloppe l'iframe dans un conteneur avec la classe zenflip-wrapper. Vous pouvez cibler cette classe pour personnaliser l'apparence extérieure :

`css / Arrondir les coins de manière plus prononcée / .zenflip-wrapper { border-radius: 16px !important; box-shadow: 0 4px 24px rgba(0, 0, 0, 0.12); }

/ Ajouter une bordure / .zenflip-wrapper iframe { border: 2px solid #e5e7eb !important; border-radius: 16px !important; }

/ Supprimer l'arrière-plan par défaut / .zenflip-wrapper { background: transparent !important; } `

L'iframe elle-même gère tout le style du lecteur en interne. Vous ne pouvez pas injecter de CSS dans l'iframe en raison des restrictions cross-origin, mais le lecteur respecte les paramètres de marque configurés sur la publication (logo, couleurs, polices) via le tableau de bord ou l'API Publications.

Configuration du défilement automatique

Lorsque autoFlip est activé (soit via data-auto-flip="true" soit via autoFlip: true dans l'API programmatique), le lecteur avance automatiquement les pages à un intervalle défini. Ceci est utile pour l'affichage numérique, les écrans de hall ou les présentations sans surveillance.

`html <script src="https://app.zenflip.io/embed.js" data-pub="lobby-display" data-auto-flip="true" data-width="100%" data-height="100vh"> </script> `

L'intervalle de défilement automatique et le comportement (boucle ou arrêt à la dernière page) peuvent être configurés via les paramètres du lecteur de la publication dans le tableau de bord ou via l'endpoint PATCH /publications/:id/settings.

URL de base personnalisée

Si vous hébergez le lecteur ZenFlip sur un domaine personnalisé ou un déploiement auto-hébergé, remplacez l'URL de base :

`html <script src="https://app.zenflip.io/embed.js" data-pub="my-publication" data-base-url="https://flipbooks.yourcompany.com"> </script> `

Ou de manière programmatique :

`javascript ZenFlip.embed("#container", { pub: "my-publication", baseUrl: "https://flipbooks.yourcompany.com" }); `

L'URL du lecteur est construite comme {baseUrl}/view/{slug}, assurez-vous donc que votre domaine personnalisé serve le lecteur ZenFlip à ce chemin.

Informations de version

Vérifiez la version actuelle du widget d'intégration :

`javascript console.log(ZenFlip.version); // "0.1.0" `

Prévention de la double initialisation

Le script d'intégration inclut une protection intégrée contre la double initialisation. Si le script est inclus plusieurs fois sur la même page (courant dans les environnements CMS), seule la première instance s'exécute. Les chargements de scripts suivants sont silencieusement ignorés.