Media Notification Bridge

1O que é a ponte de notificação de mídia?#

Quando seu site toca música ou áudio, o Android não sabe disso. Não há player na tela de bloqueio, nem capa do álbum, nem botões de mídia na barra de notificações.

A ponte de notificação de mídia resolve isso. Seu código JavaScript informa ao Android:

• Qual música está tocando (título, artista, capa)
• Se está tocando ou pausado

O Android então mostra uma notificação de mídia adequada, com controles. Quando o usuário pressiona Play/Pause/Próxima/Anterior na notificação ou na tela de bloqueio, o Android chama de volta o seu JavaScript para que você possa responder.

Pense nisso como uma ponte de mão dupla:
JS do seu site ⟷ Tela de bloqueio / notificação do Android

2Ative no gerador#

Na Etapa 4 do gerador:

1. Ative '🎵 Notificação de mídia'
2. Gere seu APK

Agora o JS do seu site tem acesso a window.WebToApk com os métodos de mídia.

3Etapa 1 - Informar ao Android o que está tocando#

Chame isto a partir do JS do seu site sempre que uma nova faixa começar. O Android atualiza a notificação e a tela de bloqueio imediatamente.

// 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)
);

4Etapa 2 - Atualizar o estado de Play / Pause#

Chame isto sempre que a reprodução começar, pausar ou a posição mudar. O Android usa isso para mostrar o botão certo (▶ ou ⏸) e preencher a barra de progresso.

// 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);

5Etapa 3 - Escutar os toques nos botões#

O usuário pode pressionar Play/Pause/Próxima/Anterior na notificação ou na tela de bloqueio. Seu site precisa definir essa função de callback para receber essas ações e respondê-las.

// 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;
  }
};

6Etapa 4 - Remover a notificação ao parar#

Quando o usuário para a reprodução por completo (não apenas pausa), chame isto para voltar a notificação à mensagem básica 'Em execução em segundo plano' e remover os controles de mídia.

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

7Por que Play/Pause funciona automaticamente, mas Próxima/Anterior exigem código#

Nosso app inclui um 'Rastreador de mídia automático'. Se você não escrever nenhum código personalizado, o app detecta automaticamente quando tags <video> ou <audio> padrão estão tocando e faz os botões Play e Pause funcionarem automaticamente como alternativa.

No entanto, os players de mídia HTML5 padrão NÃO têm um comando universal de 'Próxima' ou 'Anterior' (já que não oferecem playlists por padrão). Para que Próxima/Anterior funcionem, seu site PRECISA usar explicitamente a API MediaSession padrão (navigator.mediaSession.setActionHandler) ou definir o callback window.WebToApkOnMediaAction para dizer ao app exatamente o que fazer quando esses botões forem pressionados.

8Exemplo completo e funcional#

Exemplo completo - cole isto no seu site para ligar um elemento de áudio HTML5 à notificação de mídia do 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
};

9Como é a notificação#

A notificação de mídia aparece na barra de notificações e na tela de bloqueio:

┌───────────────────────────────────────┐
│ 🎵 [Nome do seu app] │
│ Bohemian Rhapsody │
│ Queen │
│ [capa do álbum] ⏮ ⏸ ⏭ │
└───────────────────────────────────────┘

• ⏮ Anterior - chama seu WebToApkOnMediaAction('prev')
• ⏸ / ▶ - chama 'pause' ou 'play'
• ⏭ Próxima - chama 'next'

Os botões de fones Bluetooth e o Android Auto também acionam os mesmos callbacks automaticamente.

10Requisitos e limites#

✅ Exige que a opção 'Serviço em primeiro plano' também esteja ATIVADA (a notificação de mídia precisa do serviço em execução)

✅ A capa é buscada na URL que você informar - precisa ser uma imagem de acesso público (HTTPS de preferência)

✅ Funciona com qualquer elemento de áudio ou vídeo HTML5, ou qualquer biblioteca de player de música em JS

⚠️ Se você não chamar setPlaybackState(), os botões vão aparecer, mas o Android não saberá o estado atual - sempre chame depois de play/pause

⚠️ window.WebToApk só está disponível dentro do app gerado. Sempre proteja as chamadas com:
if (window.WebToApk) { ... }

11Proteção para testes no navegador#

Seu site também abre em navegadores comuns, onde window.WebToApk não existe. Use este wrapper para o código não quebrar no 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]);