Visión General del SDK

La capa de renderizado de Percus está compuesta por dos paquetes independientes que trabajan en conjunto para embeber experiencias de video personalizadas en cualquier página web.

┌─────────────────────────────────────────────────────────┐
│  Página Host  (sitio web del cliente)                   │
│                                                         │
│   ┌──────────────────────────────────────────────────┐  │
│   │  percus-embed-sdk  (SmartEmbed)                  │  │
│   │  - Crea <iframe>                                 │  │
│   │  - Envía INIT / PLAY / PAUSE / SEEK via postMsg  │  │
│   │  - Recibe callbacks READY / PROGRESS / ERROR     │  │
│   └────────────────────┬─────────────────────────────┘  │
└────────────────────────│────────────────────────────────┘
                postMessage (cross-origin)
┌──────────────────────────────────────────────────────────┐
│  <iframe>  (origen del Percus Player)                    │
│                                                          │
│   ┌──────────────────────────────────────────────────┐   │
│   │  percus-player  (Player Runtime)                 │   │
│   │  - Carga el template (Lottie JSON)               │   │
│   │  - Carga manifest y datos de personalización     │   │
│   │  - Aplica bindings mediante BindingEngine        │   │
│   │  - Renderiza la animación con lottie-web         │   │
│   └──────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────┘

¿Qué hacen estos componentes?

Antes de entrar en detalles técnicos, aquí hay un resumen en lenguaje simple de todo lo que estos dos componentes permiten.

Percus Player — qué ofrece

• Reproduce animaciones de video personalizadas — renderiza animaciones basadas en Lottie que han sido customizadas con los datos propios de cada cliente (nombre, saldo de cuenta, detalles del plan, etc.).
• Carga el contenido bajo demanda — descarga el template de animación y los recursos necesarios solo cuando un usuario abre la experiencia, por lo que no hay nada que pre-generar ni almacenar.
• Aplica los bindings de datos automáticamente — toma los datos del cliente y reemplaza los marcadores correctos dentro de la animación sin ningún trabajo manual por cada usuario.
• Responde a controles de reproducción — puede reproducirse, pausarse y saltar a cualquier punto en el tiempo, igual que un reproductor de video convencional.
• Reporta el progreso en tiempo real — informa continuamente a la página host sobre el avance de la animación, habilitando barras de progreso personalizadas, marcadores de capítulos o analíticas.
• Comunica errores con claridad — si algo falla durante la carga o reproducción, envía un error estructurado a la página host para que la experiencia pueda fallar de forma elegante.
• Corre en un entorno aislado — opera dentro de un iframe en su propio dominio, manteniendo los datos del cliente y la lógica de renderizado separados de la página host.
• Soporta módulos intercambiables — cada pieza interna (cargador de templates, proveedor de datos, motor de bindings, renderizador) puede ser reemplazada, haciendo al player adaptable a distintos formatos de templates o fuentes de datos.
• (planificado) Dispara eventos dentro del video — notifica a la página host cuando se alcanza un botón de CTA, un marcador de capítulo o cualquier punto de interacción personalizado durante la reproducción.
• (planificado) Maneja el autoplay de forma elegante — detecta cuando el navegador bloquea el autoplay y lo reporta como un evento específico para que la página host pueda mostrar un botón de play manual.
• (planificado) Soporta subtítulos y transcripciones — renderiza pistas de subtítulos sincronizadas con la animación para accesibilidad y cumplimiento regulatorio.
• (planificado) Emite señales de finalización — distingue entre un usuario que vio la animación completa y uno que salió antes del final, habilitando métricas de engagement.

Percus SmartEmbed SDK — qué ofrece

• Integración en una línea — una sola llamada a función (PercusEmbed.init) es todo lo que se necesita para colocar el player dentro de cualquier <div> en una página web.
• Compatible con cualquier stack web — disponible como <script> para páginas estáticas y como módulo ES para React, Vue, Angular o cualquier bundler moderno.
• Gestiona el iframe automáticamente — crea, configura e inyecta el iframe para que los desarrolladores nunca tengan que escribir HTML repetitivo ni preocuparse por el tamaño.
• Envía los datos de personalización de forma segura — reenvía los datos del cliente directamente al player al momento de la inicialización; los datos nunca se almacenan ni se exponen fuera del iframe.
• Expone controles de reproducción simples — play(), pause(), seek() y destroy() brindan control total sobre la experiencia de visualización sin necesitar conocer el protocolo subyacente.
• Entrega callbacks de ciclo de vida — los hooks onReady, onProgress y onError permiten que la página reaccione a los eventos del player (mostrar un spinner, actualizar una barra de progreso, mostrar un mensaje de error).
• Completamente tipado para proyectos TypeScript — incluye declaraciones de tipos completas para que los editores puedan autocompletar parámetros y detectar errores en tiempo de compilación.
• Se limpia solo — destroy() elimina el iframe y todos los event listeners, evitando pérdidas de memoria en aplicaciones de una sola página.
• (planificado) Analíticas integradas — registra eventos del player (reproducciones, finalizaciones, clics en CTA, vistas de capítulos) y puede reenviarlos a un backend de analíticas o a Google Analytics sin código adicional en la página host.
• (planificado) Gestión de consentimiento — respeta las regulaciones de privacidad gateando todo el tracking detrás del consentimiento explícito del usuario, con callbacks para los estados de aceptado y rechazado.
• (planificado) Callbacks de llamada a la acción (CTA) — expone las interacciones CTA del interior de la animación para que la página host pueda abrir un formulario, redirigir a un producto o disparar cualquier acción de negocio.
• (planificado) Modo modal / lightbox — puede abrir el player como una superposición a pantalla completa con un delay de apertura automática opcional, útil para experiencias promocionales o de onboarding.
• (planificado) Relación de aspecto y tamaño responsivo — acepta un único parámetro de relación de aspecto ("16x9", "1x1", etc.) y gestiona todo el CSS necesario para hacer el iframe completamente responsivo.
• (planificado) Múltiples instancias de player — provee un registro para gestionar y controlar varios players independientes en la misma página.
• (planificado) Opciones de mute, loop y autoplay — configuraciones estándar de reproducción configurables al momento de la inicialización con manejo de fallback para políticas del navegador.

---

Paquetes

Paquete	NPM / Build	Rol
percus-player	IIFE servido desde CDN	Corre dentro del iframe – carga, vincula y renderiza animaciones
percus-embed-sdk	ESM + IIFE	Corre en la página host – crea el iframe y expone una API de control

Contrato de Mensajes

Ambos paquetes comparten un protocolo postMessage versionado (PERCUS_MESSAGE_VERSION = 1). Todos los mensajes siguen el mismo sobre:

{
  version: 1;
  type: PercusMessageType;
  payload: TPayload;
}

Flujo de mensajes

Dirección	Tipo de mensaje	Propósito
Host → Player	PERCUS/INIT	Enviar template, manifest y datos de personalización
Host → Player	PERCUS/PLAY	Iniciar / reanudar reproducción
Host → Player	PERCUS/PAUSE	Pausar reproducción
Host → Player	PERCUS/SEEK	Saltar a una posición en el tiempo
Player → Host	PERCUS/READY	El player cargó y está listo
Player → Host	PERCUS/PROGRESS	Heartbeat periódico de reproducción (≈500 ms)
Player → Host	PERCUS/ERROR	Ocurrió un error

Modelo de seguridad

• El Player Runtime acepta mensajes solo de orígenes en una lista blanca configurable.
• El SmartEmbed SDK valida que los mensajes entrantes provengan del iframe inyectado (event.source === iframe.contentWindow).
• Los datos de personalización (PII) se mantienen en memoria solo durante el binding y nunca se registran, persisten ni reenvían.
• Las llamadas a postMessage deben apuntar al origen real en producción (evitar "*").
• La página host es responsable de establecer atributos sandbox restrictivos en el iframe.

---

Hoja de ruta de funcionalidades

La siguiente tabla cubre el alcance completo de ambos componentes — funcionalidades core y mejoras. Los elementos están agrupados por categoría y ordenados por prioridad de implementación dentro de cada grupo.

Funcionalidades core (aún no implementadas)

Prioridad	Funcionalidad	Componente(s)	Notas
Alta	Carga de template	Player	Obtener el template Lottie JSON desde una URL al recibir PERCUS/INIT
Alta	Carga de manifest	Player	Obtener y validar el manifest de bindings desde una URL
Alta	Carga de datos de personalización	Player	Aceptar data inline o descargarlo desde dataUrl
Alta	Motor de bindings de datos	Player	Aplicar los bindings del manifest al JSON del template, reemplazando los marcadores con los datos del cliente
Alta	Renderizado de animación	Player	Renderizar la animación Lottie vinculada mediante lottie-web
Alta	Controles de play / pausa / seek	Player + SDK	Manejar los comandos PERCUS/PLAY, PERCUS/PAUSE, PERCUS/SEEK; exponer play(), pause(), seek() en el controlador
Alta	Heartbeat de progreso	Player + SDK	Emitir PERCUS/PROGRESS cada ~500 ms; exponer mediante el callback onProgress
Alta	Reporte de errores	Player + SDK	Emitir PERCUS/ERROR ante cualquier fallo; exponer mediante el callback onError
Alta	Inyección del iframe	SDK	Crear, configurar y adjuntar el <iframe> al elemento target
Alta	Envío de PERCUS/INIT	SDK	Enviar las URLs de template, manifest y datos al player después de que el iframe cargue
Alta	Aplicación de lista blanca de orígenes	Player	Rechazar comandos postMessage de orígenes que no estén en la lista blanca configurada
Alta	Arquitectura de módulos intercambiables	Player	Permitir reemplazar TemplateLoader, ManifestLoader, DataProvider, BindingEngine y Renderer mediante opciones del constructor

Mejoras (identificadas a partir del análisis competitivo)

Prioridad	Funcionalidad	Componente(s)	Notas
Alta	Analíticas / Smart Tracking	SDK + Player	Clave de tracking por sesión, captura de eventos, integración con backend de analíticas
Alta	Gestión de consentimiento	SDK	Gatear todo el tracking detrás del consentimiento; callbacks onConsentAccepted / onConsentDeclined
Alta	Eventos CTA	SDK + Player	Exponer triggers de llamada a la acción del interior de la animación a la página host
Alta	onPlayComplete / onPlayIncomplete	SDK + Player	Distinguir vistas completas de abandonos para métricas de engagement
Media	Autoplay + fallback con mute	SDK + Player	Detectar bloqueos de autoplay del navegador; evento onAutoplayFailure + opción de inicio muteado
Media	Subtítulos / transcripción	Player	Renderizado de pistas de subtítulos para accesibilidad y cumplimiento regulatorio
Media	Modo modal / lightbox	SDK	Abrir el player como overlay; delay auto-open-time opcional
Media	Relación de aspecto y tamaño responsivo	SDK	Un solo parámetro de configuración maneja todo el CSS responsivo
Baja	Eventos de navegación por capítulos	SDK + Player	onChapterEnter / onChapterExit para contenido de larga duración
Baja	Múltiples instancias de player	SDK	API de registro para gestionar varios players en la misma página
Baja	Temas / esquemas de color	SDK	Branding por cliente sin necesidad de una nueva compilación

---

Consulta Percus Player y SmartEmbed SDK para las referencias completas de API.