Cómo incrustar una imagen interactiva en tu web

Un archivo .oim es un PNG normal con textos, botones y animaciones guardados dentro. Para que esas capas funcionen, la página tiene que cargar <oim-player>, el componente que las dibuja. Esta guía sigue los pasos en el orden en que los harías tú.

Antes de empezar

Necesitas tres cosas:

• Un archivo .oim.png. Puedes usar el de muestra del CDN para probar.
• Una URL pública donde esté alojado. El player descarga el archivo con fetch, así que el servidor tiene que permitir tu sitio (CORS). El CDN de demostración lo permite para cualquier origen.
• Unos cinco minutos.

Hay una trampa que conviene saber desde el principio. Si abres el archivo directamente en el navegador, o lo pones en una etiqueta <img>, solo verás la imagen base. Los textos y las animaciones aparecen únicamente cuando el player los dibuja.

Paso 1: carga el player

En una página HTML sencilla basta con un script:

<script src="https://cdn.oim.media/player/v1/oim-player.js"></script>

Paso 2: declara la imagen

Pon la etiqueta donde quieras que aparezca la imagen:

<oim-player
  src="https://cdn.oim.media/demo/imagen-muestra.oim.png"
  lang="en"
  mode="full"
  fit="contain"
  style="max-width: 800px; height: 600px; display: block; margin: 0 auto;">
</oim-player>

Los atributos que más vas a tocar son estos:

• src: la URL del archivo.
• lang: el idioma inicial, por ejemplo en o es.
• mode="full": activa las animaciones y los estados de paso del ratón y clic. Sin él, la imagen se queda quieta.
• fit: contain deja ver la imagen completa; cover la llena y recorta los bordes.

Dale a la etiqueta un ancho y un alto, como en el ejemplo. El player ocupa el espacio que le das.

Paso 3: elige el idioma

El archivo guarda cada texto en varios idiomas. Para cambiar de idioma desde tu página, llama a un método:

player.setLang('es');

Cada cambio dispara el evento oim:langchange, por si tu página necesita enterarse.

Paso 4: escucha lo que hace el usuario

Cuando alguien pulsa un elemento con acción, el player lanza oim:action. El archivo no puede llevar a nadie a ningún sitio por sí mismo: solo avisa. Tu página decide qué hacer:

player.addEventListener('oim:action', (event) => {
  const { slot, name, trigger, targets } = event.detail;
  // Si quieres que el clic navegue, la página decide la URL.
  if (name === 'Buy') {
    event.preventDefault();
    window.location.href = '/product/42';
  }
});

Así un anuncio puede abrir tu carrito en lugar de una web externa. Y si no escuchas el evento, no pasa nada.

Paso 5: usarlo en React

En React, el elemento se usa como cualquier otra etiqueta. Instala el paquete e importa el registro del componente:

import '@oim/player-oim';

export function Banner() {
  return (
    <oim-player
      src="https://cdn.oim.media/demo/imagen-muestra.oim.png"
      lang="en"
      mode="full"
      fit="contain"
    />
  );
}

En React 18 o 19 con TypeScript, la guía añade una declaración de tipos para que la etiqueta no dé error. Cópiala de la guía de inicio rápido.

Paso 6: comprueba la firma

Cada archivo firmado trae una firma ECDSA. Para saber en qué estado está, pregunta al player:

const estado = player.getSecurityStatus(); // el estado de la firma

Si la firma no cuadra, la imagen no se muestra. Esto tiene sentido: un archivo alterado no debe parecer auténtico. Para saber más sobre cómo funciona la comprobación, lee la comprobación de integridad en la guía de seguridad.

Ajustes para casos concretos

Algunos atributos sirven para situaciones habituales:

• disable-animations="true": detiene los bucles. Respeta la preferencia de movimiento reducido del sistema.
• allow-zoom="true": permite acercar con la rueda o pellizcando. Útil en diagramas.
• auto-rotate-lang="3000": cambia de idioma cada tres segundos.
• allow-lottie="false": no carga las animaciones Lottie, lo que ahorra memoria en una cuadrícula con muchas imágenes.

La guía de accesibilidad explica cómo lee la página un lector de pantalla, y qué hace falta describir en el archivo. Para el uso general de cada opción, mira también la guía del player.

Preguntas frecuentes

¿Por qué veo solo la imagen, sin textos?

Casi siempre porque el archivo se abre directamente, o porque falta el script del player. Comprueba que la página carga oim-player.js sin errores en la consola, y que la URL del src responde desde tu dominio.

¿Necesito JavaScript para ver la imagen?

Para ver la imagen base, no. Un .oim es un PNG válido, y cualquier visor la muestra. Para ver los textos, los idiomas y las animaciones, sí necesitas el player, que es JavaScript.

¿Puedo cambiar un texto sin tocar la imagen?

El texto vive dentro del archivo, no en la imagen base, así que cambiarlo no obliga a redibujar los píxeles. Pero como la firma cubre esos datos, editarlo a mano rompe la firma: el archivo tiene que volver a firmarse.

¿Funciona en una web estática?

Sí. El ejemplo de HTML puro no necesita compilador ni framework. Sirve la página y el .oim.png desde tu hosting, con el CORS correcto.

Si quieres entender por qué la imagen puede demostrar que no fue alterada, lee la firma ECDSA de cada píxel. Y para ver qué puede hacer el player con microinteracciones, mira las microinteracciones vectoriales sin framework.

Para el concepto de fondo, la idea de que el texto viaja con la imagen está en la imagen que sabe lo que es.