Opciones Avanzadas de Integracion
Usa la API programatica de JavaScript para integracion dinamica, integra con SPAs de React/Vue/Angular, maneja eventos, personaliza estilos y configura el comportamiento de paso automatico de paginas.
Opciones Avanzadas de Integracion
Mas alla de los enfoques basicos de etiqueta script y div, el widget de integracion de ZenFlip proporciona una API programatica de JavaScript para escenarios de integracion dinamica. Esta guia cubre la API, la integracion con aplicaciones de pagina unica (SPA), el manejo de eventos y la configuracion avanzada.
API Programatica
El script de integracion expone un objeto global ZenFlip con metodos para crear y gestionar integraciones.
ZenFlip.embed(target, options)
Crea una instancia de integracion de forma programatica.
Parametros:
Parametro | Tipo | Requerido | Descripcion |
|---|---|---|---|
| string o HTMLElement | Si | Selector CSS o elemento DOM |
| string | Si | Slug de la publicacion |
| string o number | No | Ancho (por defecto: |
| string o number | No | Alto en pixeles (por defecto: |
| boolean | No | Habilitar paso automatico de paginas (por defecto: |
| number | No | Numero de pagina inicial (por defecto: |
| string | No | Sobreescribir URL base del visor |
Retorna: Un objeto de instancia de integracion con las propiedades iframe, wrapper y destroy(), o null si no se encontro el objetivo.
`javascript // Usando un selector CSS const instance = ZenFlip.embed("#flipbook-container", { pub: "product-catalog-2026", width: "100%", height: 700, autoFlip: false, startPage: 1 });
// Usando un elemento DOM const el = document.getElementById("my-embed"); const instance = ZenFlip.embed(el, { pub: "annual-report-2025", height: 600 }); `
ZenFlip.scan()
Re-escanea la pagina en busca de nuevos contenedores .zenflip-embed que se hayan anadido al DOM despues de la carga inicial de la pagina. Esto es esencial para aplicaciones de pagina unica donde el contenido se renderiza dinamicamente.
`javascript // Despues de anadir dinamicamente contenedores de integracion al DOM document.getElementById("content").innerHTML = <div class="zenflip-embed" data-pub="new-publication" data-height="500"></div> ;
// Indica a ZenFlip que descubra e inicialice los nuevos contenedores ZenFlip.scan(); `
Destruir una Integracion
Llama a destroy() en la instancia para eliminar la integracion del DOM y liberar recursos:
`javascript const instance = ZenFlip.embed("#container", { pub: "my-pub" });
// Mas tarde, eliminar la integracion instance.destroy(); `
Integracion con SPA
React
Crea un componente React reutilizable que gestione el ciclo de vida de la integracion:
`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(() => { // Asegurar que el script de integracion esta cargado 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} />; }
// Uso <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); }); } } `
Manejo de Eventos
El widget de integracion se comunica con la pagina principal a traves de la API postMessage. Escucha los mensajes del iframe de ZenFlip para responder a los eventos del lector:
`javascript window.addEventListener("message", (event) => { // Verificar el origen if (!event.origin.includes("zenflip.io")) return;
const { type, data } = event.data;
switch (type) { case "zenflip:page_change": console.log("Page changed to:", data.pageNumber); break; case "zenflip:ready": console.log("Flipbook loaded, total pages:", data.pageCount); break; case "zenflip:lead_captured": console.log("Lead submitted:", data.email); break; } }); `
Eventos Disponibles
Tipo de Evento | Descripcion | Datos |
|---|---|---|
| El flipbook ha terminado de cargar |
|
| El lector navego a una nueva pagina |
|
| Se envio un formulario de captura de leads |
|
Estilos Personalizados
El widget de integracion envuelve el iframe en un contenedor con la clase zenflip-wrapper. Puedes dirigirte a esta clase para personalizar la apariencia exterior:
`css / Redondear las esquinas mas agresivamente / .zenflip-wrapper { border-radius: 16px !important; box-shadow: 0 4px 24px rgba(0, 0, 0, 0.12); }
/ Anadir un borde / .zenflip-wrapper iframe { border: 2px solid #e5e7eb !important; border-radius: 16px !important; }
/ Eliminar el fondo por defecto / .zenflip-wrapper { background: transparent !important; } `
El iframe en si maneja todos los estilos del visor internamente. No puedes inyectar CSS en el iframe debido a restricciones de origen cruzado, pero el visor respeta la configuracion de marca establecida en la publicacion (logo, colores, fuentes) a traves del panel de control o la API de Publicaciones.
Configuracion de Paso Automatico de Paginas
Cuando autoFlip esta habilitado (ya sea mediante data-auto-flip="true" o autoFlip: true en la API programatica), el visor avanza las paginas automaticamente a intervalos de tiempo. Esto es util para senalizacion digital, pantallas de vestibulo o presentaciones sin supervision.
`html <script src="https://app.zenflip.io/embed.js" data-pub="lobby-display" data-auto-flip="true" data-width="100%" data-height="100vh"> </script> `
El intervalo de paso automatico y el comportamiento (bucle vs. detenerse en la ultima pagina) se pueden configurar a traves de los ajustes del visor de la publicacion en el panel de control o mediante el endpoint PATCH /publications/:id/settings.
URL Base Personalizada
Si alojas el visor de ZenFlip en un dominio personalizado o una implementacion autoalojada, sobreescribe la URL base:
`html <script src="https://app.zenflip.io/embed.js" data-pub="my-publication" data-base-url="https://flipbooks.yourcompany.com"> </script> `
O de forma programatica:
`javascript ZenFlip.embed("#container", { pub: "my-publication", baseUrl: "https://flipbooks.yourcompany.com" }); `
La URL del visor se construye como {baseUrl}/view/{slug}, asi que asegurate de que tu dominio personalizado sirva el visor de ZenFlip en esa ruta.
Informacion de Version
Verifica la version actual del widget de integracion:
`javascript console.log(ZenFlip.version); // "0.1.0" `
Prevencion de Doble Inicializacion
El script de integracion incluye proteccion integrada contra la doble inicializacion. Si el script se incluye multiples veces en la misma pagina (comun en entornos CMS), solo se ejecuta la primera instancia. Las cargas de script posteriores se ignoran silenciosamente.