Guía de Integración Multimarco

Tanto <oim-player> como <ovm-player> son Custom Elements estándar del W3C que se integran de forma natural en cualquier framework frontend moderno. A continuación se presentan patrones de código listos para producción para cada tecnología.

---

1. React 19 y Next.js (App Router / Pages)

En aplicaciones React, registra el componente dentro de un efecto para garantizar la hidratación correcta en el cliente:

'use client';

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

interface OimViewerProps {
  src: string;
  lang?: string;
  onAction?: (actionName: 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: Event) => {
      const customEvent = e as CustomEvent;
      if (onAction) {
        onAction(customEvent.detail.name);
      }
    };

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

  return (
    <div className="w-full max-w-2xl mx-auto">
      {/* @ts-expect-error custom-element */}
      <oim-player ref={playerRef} src={src} lang={lang} fit="contain" />
    </div>
  );
}

---

2. Vue 3 (Composition API / Nuxt 3)

Vue soporta elementos personalizados de forma nativa sin necesidad de adaptadores:

<template>
  <div class="player-container">
    <oim-player
      ref="playerRef"
      :src="src"
      :lang="activeLang"
      fit="contain"
      @oim:action="handleAction"
    />
  </div>
</template>

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

const props = defineProps<{ src: string }>();
const activeLang = ref('es');
const playerRef = ref<HTMLElement | null>(null);

const handleAction = (e: CustomEvent) => {
  console.log('Acción seleccionada:', e.detail.name);
};
</script>

---

3. Svelte 5 y SvelteKit

La importación dinámica en el cliente asegura que el renderizado en servidor (SSR) no intente evaluar Custom Elements:

<script lang="ts">
  import { onMount } from 'svelte';

  export let src: string;
  export let lang: string = 'es';

  onMount(async () => {
    await import('@oim-media/player-oim');
  });
</script>

<div class="oim-wrapper">
  <oim-player {src} {lang} fit="contain"></oim-player>
</div>

<style>
  .oim-wrapper {
    width: 100%;
    aspect-ratio: 16 / 9;
  }
</style>

---

4. Astro (Arquitectura de Islas)

En Astro, las etiquetas <script> se ejecutan exclusivamente en el cliente sin sobrecoste de hidratación:

---
interface Props {
  src: string;
  lang?: string;
}

const { src, lang = 'es' } = Astro.props;
---

<div class="interactive-card">
  <oim-player src={src} lang={lang} fit="contain"></oim-player>
</div>

<script>
  import '@oim-media/player-oim';
</script>

---

5. JavaScript Puro y HTML5

No se requiere ningún empaquetador ni paso de compilación para páginas web estándar:

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="UTF-8">
  <script type="module" src="https://cdn.oim.media/player/v1/oim-player.js"></script>
</head>
<body>
  <oim-player
    id="myPromo"
    src="/media/hero.oim.png"
    lang="es"
    fit="cover">
  </oim-player>

  <script>
    const player = document.getElementById('myPromo');
    player.addEventListener('oim:loaded', () => {
      console.log('¡OIM Listo!');
    });
  </script>
</body>
</html>