Guía de Inicio Rápido

Esta guía explica paso a paso cómo integrar el reproductor <oim-player> en aplicaciones web, desde páginas HTML básicas hasta frameworks de frontend modernos.

---

1. Vía Rápida: HTML Puro y CDN

La forma más rápida de visualizar archivos .oim interactivos es utilizar el script precompilado del Web Component distribuido por CDN:

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="UTF-8">
  <title>Medio Interactivo OIM</title>
  <!-- Carga del Web Component OIM Player -->
  <script src="https://cdn.oim.media/player/v1/oim-player.js"></script>
</head>
<body>

  <!-- Inserción de imagen interactiva (una demo firmada en español e inglés) -->
  <oim-player 
    src="https://cdn.oim.media/demo/imagen-muestra.oim.png"
    lang="es"
    mode="full"
    fit="contain"
    style="max-width: 800px; height: 600px; display: block; margin: 0 auto;">
  </oim-player>

</body>
</html>

URL estable y caché

/player/v1/ es la ruta estable: sigue siendo compatible mientras la versión mayor sea la 1. El navegador guarda el script hasta 4 horas, así que una actualización puede tardar eso en llegar a quien ya visitó la página.

Abrir el archivo .oim.png directamente vs. usar <oim-player>

Un archivo .oim es un PNG estándar válido donde el fondo visual se almacena en la Capa −1 (Horneada) y toda la tipografía interactiva, botones y textos multilingües residen en el chunk de metadatos de la Capa +1 (Dinámica).

• Si abres https://cdn.oim.media/demo/imagen-muestra.oim.png directamente en la barra del navegador (o mediante una etiqueta <img> normal), el visor de imágenes del sistema solo renderizará la imagen de fondo estática sin el texto.
• Para decodificar y visualizar el texto dinámico, cambio de idioma y animaciones, el archivo debe incrustarse usando el componente <oim-player> (tal como se ilustra en el ejemplo de código arriba).

Dónde alojar tu .oim

El player descarga el archivo con fetch, así que el servidor tiene que permitir el origen de tu página (CORS). La demo de arriba se sirve desde cdn.oim.media, que lo permite a cualquier origen.

Alojamiento en la nube y CDN para incrustar

Al alojarse en un endpoint de incrustación autorizado (ej. https://embed.oim.media/<id>.oim.png), el archivo se distribuye desde cachés globales edge con cabeceras CORS permisivas, proporcionando código listo para incrustar en cualquier web.

Si alojas el player tú mismo

Si copias oim-player.js a tu servidor, copia también la carpeta vendor/ a su lado. El player carga Lottie desde ahí solo cuando un .oim tiene una capa Lottie.

---

2. Instalación mediante Gestor de Paquetes

Si utilizas un empaquetador (Vite, Webpack, Rollup) o un framework moderno, instala @oim-media/player-oim:

Disponibilidad del Paquete

@oim-media/player-oim está disponible en el workspace del proyecto y en el registro privado. Utiliza siempre pnpm dentro del ecosistema OIM.

# Con pnpm (recomendado)
pnpm add @oim-media/player-oim

# O con npm
npm install @oim-media/player-oim

En tu archivo de entrada principal (ej. main.ts o index.js), importa el paquete para registrar el elemento personalizado:

import '@oim-media/player-oim';

// El elemento <oim-player> ya está registrado en window.customElements

---

3. Integración en Frameworks de Producción

JavaScript Puro / TypeScript

import '@oim-media/player-oim';

const player = document.querySelector('oim-player') as any;

// Escuchar la carga de metadatos y verificación de firma
player.addEventListener('oim:loaded', (event: CustomEvent) => {
  const { metadata, security } = event.detail;
  console.log(`Documento cargado. Estado de seguridad: ${security}`);
  console.log(`Idiomas disponibles:`, player.languages);
});

// Interceptar acciones interactivas del usuario
player.addEventListener('oim:action', (event: CustomEvent) => {
  console.log(`Interacción en el slot: ${event.detail.slot}`);
  
  // Lógica de negocio personalizada: vetar el cambio visual interno si es necesario
  if (event.detail.slot === 'btn_comprar') {
    event.preventDefault(); // Cancela la mutación interna del DOM en el player
    abrirModalDePago();
  }
});

// Cambio imperativo de idioma
function cambiarIdioma(codigo: string) {
  player.setLang(codigo);
}

React 18 / 19 y Next.js

Dado que los Custom Elements aceptan atributos serializados y emiten eventos DOM nativos, encapsula <oim-player> en un componente tipado:

import React, { useEffect, useRef } from 'react';
import '@oim-media/player-oim';

// Declaración de tipos JSX para TypeScript
declare global {
  namespace JSX {
    interface IntrinsicElements {
      'oim-player': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
        src?: string;
        lang?: string;
        mode?: 'full' | 'image';
        fit?: 'contain' | 'cover';
        align?: 'center' | 'top' | 'bottom';
        'allow-dynamic-colors'?: 'true' | 'false';
        'activate-on'?: 'visible' | 'hover' | 'manual';
      };
    }
  }
}

interface OimViewerProps {
  src: string;
  lang?: string;
  onAction?: (slotId: string, targets: string[]) => void;
}

export function OimViewer({ src, lang = 'es', onAction }: OimViewerProps) {
  const playerRef = useRef<HTMLElement>(null);

  useEffect(() => {
    const el = playerRef.current;
    if (!el) return;

    const handleAction = (e: any) => {
      onAction?.(e.detail.slot, e.detail.targets);
    };

    el.addEventListener('oim:action', handleAction);
    return () => el.removeEventListener('oim:action', handleAction);
  }, [onAction]);

  return (
    <div style={{ width: '100%', height: '500px' }}>
      <oim-player
        ref={playerRef}
        src={src}
        lang={lang}
        mode="full"
        fit="contain"
      />
    </div>
  );
}

Vue 3

En tu archivo vite.config.ts, instruye al compilador de Vue para reconocer las etiquetas nativas de OIM:

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('oim-') || tag.startsWith('ovm-'),
        },
      },
    }),
  ],
});

Uso en componentes Single File (.vue):

<script setup lang="ts">
import { ref } from 'vue';
import '@oim-media/player-oim';

const idiomaActual = ref('es');

function onOimAction(event: any) {
  console.log('Acción detectada:', event.detail.slot);
}
</script>

<template>
  <div class="contenedor-player">
    <div class="controles">
      <button @click="idiomaActual = 'es'">Español</button>
      <button @click="idiomaActual = 'en'">English</button>
    </div>

    <oim-player
      :src="'/media/demo.oim.png'"
      :lang="idiomaActual"
      mode="full"
      @oim:action="onOimAction"
    />
  </div>
</template>

---

4. Referencia de Atributos Principales

Atributo	Tipo	Por Defecto	Descripción
src	string	""	URL al archivo .oim.png o Blob asignado.
lang	string	"es"	Código de idioma activo para resolver en slot.content.
mode	"full" | "image"	"image"	"full" habilita animaciones WAAPI y estados interactivos hover/active. "image" preserva visualización estática.
fit	"contain" | "cover"	"contain"	Modo de ajuste de la imagen horneada (Capa −1) dentro del contenedor.
align	"center" | "top" | "bottom"	"center"	Alineación vertical de la obra en el contenedor.
activate-on	"visible" | "hover" | "manual"	"visible"	Activa el movimiento al ser visible en el viewport, solo al pasar el cursor (hover), o solo cuando la página llama a play() (manual).
allow-dynamic-colors	"true" | "false"	"true"	Cuando es "true", resuelve variables CSS de roles semánticos.