Media Notification Bridge

1Qué es el puente de notificación multimedia#

Cuando tu sitio web reproduce música o audio, Android no lo sabe. No hay reproductor en la pantalla de bloqueo, ni carátula, ni botones multimedia en el panel de notificaciones.

El puente de notificación multimedia lo soluciona. Tu código JavaScript le dice a Android:

• Qué canción suena (título, artista, carátula)
• Si está reproduciéndose o en pausa

Android entonces muestra una notificación multimedia adecuada con controles. Cuando el usuario pulsa Reproducir/Pausar/Siguiente/Anterior en la notificación o en la pantalla de bloqueo, Android llama de vuelta a tu JavaScript para que puedas responder.

Piénsalo como un puente de doble sentido:
JS de tu sitio web ⟷ Pantalla de bloqueo de Android / Notificación

2Actívalo en el generador#

En el Paso 4 del generador:

1. Activa '🎵 Media Notification'
2. Genera tu APK

Ahora el JS de tu sitio web tiene acceso a window.WebToApk con métodos multimedia.

3Paso 1: dile a Android qué se está reproduciendo#

Llama a esto desde el JS de tu sitio web cada vez que empiece una pista nueva. Android actualizará la notificación y la pantalla de bloqueo de inmediato.

// When a new song starts playing:
window.WebToApk.setMediaMetadata(
  'Bohemian Rhapsody',          // track title
  'Queen',                       // artist name
  'https://yoursite.com/art.jpg' // cover art URL (or '' to skip)
);

4Paso 2: actualizar el estado de reproducción / pausa#

Llama a esto cada vez que la reproducción empiece, se pause o cambie la posición. Android lo usa para mostrar el botón correcto (▶ o ⏸) y rellenar la barra de progreso.

// When playback starts:
window.WebToApk.setPlaybackState(
  true,   // isPlaying (true = playing, false = paused)
  30000,  // current position in milliseconds (30 seconds)
  240000  // total duration in milliseconds (4 minutes)
);

// When the user presses pause on your site:
window.WebToApk.setPlaybackState(false, 30000, 240000);

5Paso 3: escuchar las pulsaciones de botones#

El usuario puede pulsar Reproducir/Pausar/Siguiente/Anterior en la notificación o en la pantalla de bloqueo. Tu sitio web debe definir esta función callback para recibir esas acciones y responder a ellas.

// Define this ONCE, early in your page JS:
window.WebToApkOnMediaAction = function(action) {
  switch (action) {
    case 'play':
      myAudioPlayer.play();
      break;
    case 'pause':
      myAudioPlayer.pause();
      break;
    case 'next':
      playNextTrack();
      break;
    case 'prev':
      playPrevTrack();
      break;
    case 'stop':
      myAudioPlayer.pause();
      myAudioPlayer.currentTime = 0;
      break;
  }
};

6Paso 4: quitar la notificación al detener#

Cuando el usuario detiene la reproducción por completo (no solo pausa), llama a esto para devolver la notificación al mensaje básico 'Running in background' y quitar los controles multimedia.

// When user stops / closes the player:
window.WebToApk.clearMediaNotification();

7Por qué Reproducir/Pausar funciona automáticamente, pero Siguiente/Anterior requiere código#

Nuestra app incluye un 'Seguimiento automático de medios'. Si no escribes código personalizado, la app detecta automáticamente cuándo se reproducen las etiquetas estándar <video> o <audio> y hace que los botones de Reproducir y Pausar funcionen automáticamente como alternativa.

Sin embargo, los reproductores multimedia HTML5 estándar NO tienen un comando universal de 'Siguiente' o 'Anterior' (porque no admiten listas de reproducción por sí mismos). Para que Siguiente/Anterior funcionen, tu sitio web DEBE usar explícitamente la API estándar MediaSession (navigator.mediaSession.setActionHandler) o definir el callback window.WebToApkOnMediaAction para indicar a la app exactamente qué hacer cuando se pulsen esos botones.

8Ejemplo completo y funcional#

Ejemplo completo: pega esto en tu sitio web para conectar un elemento de audio HTML5 con la notificación multimedia de Android:

var audio = document.getElementById('myAudio'); // your <audio> element

// — Send metadata when track loads —
audio.addEventListener('loadedmetadata', function() {
  window.WebToApk.setMediaMetadata(
    document.title,
    'My Radio Station',
    'https://yoursite.com/logo.png'
  );
});

// — Keep Android in sync with playback state —
audio.addEventListener('play', function() {
  window.WebToApk.setPlaybackState(
    true,
    Math.round(audio.currentTime * 1000),
    Math.round(audio.duration * 1000) || 0
  );
});
audio.addEventListener('pause', function() {
  window.WebToApk.setPlaybackState(
    false,
    Math.round(audio.currentTime * 1000),
    Math.round(audio.duration * 1000) || 0
  );
});

// — Receive lock-screen button presses —
window.WebToApkOnMediaAction = function(action) {
  if (action === 'play')  audio.play();
  if (action === 'pause') audio.pause();
  // next / prev: implement your playlist logic here
};

9Cómo se ve la notificación#

La notificación multimedia aparece en el panel desplegable y en la pantalla de bloqueo:

┌───────────────────────────────────────┐
│ 🎵 [Nombre de tu app] │
│ Bohemian Rhapsody │
│ Queen │
│ [carátula] ⏮ ⏸ ⏭ │
└───────────────────────────────────────┘

• ⏮ Anterior: llama a tu WebToApkOnMediaAction('prev')
• ⏸ / ▶ - llama a 'pause' o 'play'
• ⏭ Siguiente: llama a 'next'

Los botones de los auriculares Bluetooth y Android Auto también activan automáticamente los mismos callbacks.

10Requisitos y límites#

✅ Requiere que el interruptor 'Foreground Service' también esté ACTIVADO (la notificación multimedia necesita el servicio en ejecución)

✅ La carátula se obtiene de la URL que proporcionas: debe ser una imagen de acceso público (mejor HTTPS)

✅ Funciona con cualquier elemento de audio o vídeo HTML5, o con cualquier biblioteca de reproductor de música en JS

⚠️ Si no llamas a setPlaybackState(), los botones aparecerán pero Android no conocerá el estado actual: llámalo siempre después de reproducir o pausar

⚠️ window.WebToApk solo está disponible dentro de la app generada. Protege siempre las llamadas con:
if (window.WebToApk) { ... }

11Protección para pruebas en el navegador#

Tu sitio web también se abre en navegadores normales, donde window.WebToApk no existe. Usa este envoltorio para que el código no falle en Chrome/Safari:

// Safe wrapper — works in both app and browser:
function sendToAndroid(method, args) {
  if (window.WebToApk && typeof window.WebToApk[method] === 'function') {
    window.WebToApk[method].apply(window.WebToApk, args);
  }
}

// Usage:
sendToAndroid('setMediaMetadata', ['Song Title', 'Artist', 'https://art.jpg']);
sendToAndroid('setPlaybackState', [true, 0, 240000]);