Erweiterte Einbettungsoptionen

Erweiterte Einbettungsoptionen

Über den einfachen Script-Tag- und Div-Ansatz hinaus bietet das ZenFlip Embed-Widget eine programmatische JavaScript-API für dynamische Einbettungsszenarien. Diese Anleitung behandelt die API, die Integration in Single-Page-Anwendungen (SPA), Ereignisbehandlung und erweiterte Konfiguration.

Programmatische API

Das Embed-Script stellt ein globales ZenFlip-Objekt mit Methoden zum Erstellen und Verwalten von Einbettungen bereit.

ZenFlip.embed(target, options)

Erstellt eine Embed-Instanz programmatisch.

Parameter:

Rückgabewert: Ein Embed-Instanzobjekt mit den Eigenschaften iframe, wrapper und destroy(), oder null, wenn das Ziel nicht gefunden wurde.

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

// Mit einem DOM-Element const el = document.getElementById("my-embed"); const instance = ZenFlip.embed(el, { pub: "annual-report-2025", height: 600 }); `

ZenFlip.scan()

Durchsucht die Seite erneut nach neuen .zenflip-embed-Containern, die nach dem initialen Seitenladen zum DOM hinzugefügt wurden. Dies ist essenziell für Single-Page-Anwendungen, bei denen Inhalte dynamisch gerendert werden.

`javascript // Nach dem dynamischen Hinzufügen von Embed-Containern zum DOM document.getElementById("content").innerHTML = <div class="zenflip-embed" data-pub="new-publication" data-height="500"></div> ;

// ZenFlip anweisen, die neuen Container zu erkennen und zu initialisieren ZenFlip.scan(); `

Eine Einbettung zerstören

Rufen Sie destroy() auf der Instanz auf, um die Einbettung aus dem DOM zu entfernen und Ressourcen freizugeben:

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

// Später die Einbettung entfernen instance.destroy(); `

SPA-Integration

React

Erstellen Sie eine wiederverwendbare React-Komponente, die den Embed-Lebenszyklus verwaltet:

`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(() => { // Sicherstellen, dass das Embed-Script geladen ist 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} />; }

// Verwendung <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); }); } } `

Ereignisbehandlung

Das Embed-Widget kommuniziert mit der übergeordneten Seite über die postMessage-API. Lauschen Sie auf Nachrichten vom ZenFlip-iFrame, um auf Betrachter-Ereignisse zu reagieren:

`javascript window.addEventListener("message", (event) => { // Herkunft verifizieren if (!event.origin.includes("zenflip.io")) return;

const { type, data } = event.data;

switch (type) { case "zenflip:page_change": console.log("Seite gewechselt zu:", data.pageNumber); break; case "zenflip:ready": console.log("Flipbook geladen, Gesamtseiten:", data.pageCount); break; case "zenflip:lead_captured": console.log("Lead eingereicht:", data.email); break; } }); `

Verfügbare Ereignisse

Benutzerdefiniertes Styling

Das Embed-Widget umhüllt den iFrame mit einem Container der Klasse zenflip-wrapper. Sie können diese Klasse verwenden, um das äußere Erscheinungsbild anzupassen:

`css / Ecken stärker abrunden / .zenflip-wrapper { border-radius: 16px !important; box-shadow: 0 4px 24px rgba(0, 0, 0, 0.12); }

/ Rahmen hinzufügen / .zenflip-wrapper iframe { border: 2px solid #e5e7eb !important; border-radius: 16px !important; }

/ Standard-Hintergrund entfernen / .zenflip-wrapper { background: transparent !important; } `

Der iFrame selbst verwaltet das gesamte Viewer-Styling intern. Aufgrund von Cross-Origin-Beschränkungen können Sie kein CSS in den iFrame einschleusen, aber der Viewer berücksichtigt die Branding-Einstellungen, die über das Dashboard oder die Publications API für die Publikation konfiguriert wurden (Logo, Farben, Schriftarten).

Auto-Flip-Konfiguration

Wenn autoFlip aktiviert ist (entweder über data-auto-flip="true" oder autoFlip: true in der programmatischen API), blättert der Viewer automatisch in einem zeitgesteuerten Intervall weiter. Dies ist nützlich für digitale Beschilderung, Lobby-Displays oder unbeaufsichtigte Präsentationen.

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

Das Auto-Flip-Intervall und das Verhalten (Schleife vs. Stopp auf der letzten Seite) können über die Viewer-Einstellungen der Publikation im Dashboard oder über den Endpunkt PATCH /publications/:id/settings konfiguriert werden.

Benutzerdefinierte Basis-URL

Wenn Sie den ZenFlip-Viewer auf einer eigenen Domain oder einer selbst gehosteten Installation betreiben, können Sie die Basis-URL überschreiben:

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

Oder programmatisch:

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

Die Viewer-URL wird als {baseUrl}/view/{slug} aufgebaut. Stellen Sie daher sicher, dass Ihre benutzerdefinierte Domain den ZenFlip-Viewer unter diesem Pfad bereitstellt.

Versionsinformationen

Prüfen Sie die aktuelle Version des Embed-Widgets:

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

Schutz vor doppelter Initialisierung

Das Embed-Script enthält einen integrierten Schutz gegen doppelte Initialisierung. Wenn das Script mehrmals auf derselben Seite eingebunden wird (häufig in CMS-Umgebungen), wird nur die erste Instanz ausgeführt. Nachfolgende Script-Ladungen werden stillschweigend ignoriert.