Media Notification Bridge

1Cos'ГЁ il Bridge notifica multimediale?#

Quando il tuo sito riproduce musica o audio, Android non lo sa. Non c'ГЁ un lettore nella schermata di blocco, nessuna copertina, nessun pulsante multimediale nell'area notifiche.

Il Bridge notifica multimediale risolve il problema. Il tuo codice JavaScript dice ad Android:

• Quale brano ГЁ in riproduzione (titolo, artista, copertina)
• Se ГЁ in riproduzione o in pausa

Android mostra quindi una vera notifica multimediale con i controlli. Quando l'utente preme Play/Pausa/Avanti/Indietro sulla notifica o sulla schermata di blocco, Android richiama il tuo JavaScript così puoi rispondere.

Pensalo come un ponte a doppio senso:
JS del tuo sito вџ· Schermata di blocco Android / Notifica

2Attivalo nel generatore#

Nel Passaggio 4 del generatore:

1. Attiva 'рџЋµ Media Notification'
2. Genera il tuo APK

Ora il JS del tuo sito ha accesso a window.WebToApk con i metodi multimediali.

3Passaggio 1 - Di' ad Android cosa sta suonando#

Chiamalo dal JS del tuo sito ogni volta che inizia un nuovo brano. Android aggiornerГ subito la notifica e la schermata di blocco.

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

4Passaggio 2 - Aggiorna lo stato Play / Pausa#

Chiamalo ogni volta che la riproduzione parte, va in pausa o cambia posizione. Android lo usa per mostrare il pulsante giusto (в–¶ o вЏё) e riempire la barra di avanzamento.

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

5Passaggio 3 - Ascolta la pressione dei pulsanti#

L'utente puГІ premere Play/Pausa/Avanti/Indietro sulla notifica o sulla schermata di blocco. Il tuo sito deve definire questa funzione di callback per ricevere quelle azioni e rispondervi.

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

6Passaggio 4 - Rimuovi la notifica quando si ferma#

Quando l'utente interrompe del tutto la riproduzione (non solo la mette in pausa), chiamalo per riportare la notifica al semplice messaggio 'In esecuzione in background' e rimuovere i controlli multimediali.

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

7PerchГ© Play/Pausa funziona in automatico, mentre Avanti/Indietro richiede codice#

La nostra app include un 'Tracker multimediale automatico'. Se non scrivi codice personalizzato, l'app rileva automaticamente quando i tag standard <video> o <audio> sono in riproduzione e fa funzionare in automatico i pulsanti Play e Pausa come alternativa.

Tuttavia, i lettori multimediali HTML5 standard NON hanno un comando universale 'Avanti' o 'Indietro' (non supportano di per sГ© le playlist). Per far funzionare Avanti/Indietro, il tuo sito DEVE usare esplicitamente la MediaSession API standard (navigator.mediaSession.setActionHandler) oppure definire il callback window.WebToApkOnMediaAction per dire all'app esattamente cosa fare quando quei pulsanti vengono premuti.

8Esempio completo e funzionante#

Esempio completo: incollalo nel tuo sito per collegare un elemento audio HTML5 alla notifica multimediale di 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
};

9Come appare la notifica#

La notifica multimediale appare nell'area a tendina e nella schermata di blocco:

┌───────────────────────────────────────┐
в”‚ рџЋµ [Nome della tua app] в”‚
в”‚ Bohemian Rhapsody в”‚
в”‚ Queen в”‚
в”‚ [copertina] вЏ® вЏё вЏ­ в”‚
└───────────────────────────────────────┘

• вЏ® Indietro: chiama il tuo WebToApkOnMediaAction('prev')
• вЏё / в–¶: chiama 'pause' o 'play'
• вЏ­ Avanti: chiama 'next'

Anche i pulsanti delle cuffie Bluetooth e Android Auto attivano automaticamente gli stessi callback.

10Requisiti e limiti#

вњ… Richiede che sia attivo anche l'interruttore 'Foreground Service' (la notifica multimediale ha bisogno del servizio in esecuzione)

вњ… La copertina viene recuperata dall'URL che indichi: deve essere un'immagine pubblicamente accessibile (meglio HTTPS)

вњ… Funziona con qualsiasi elemento audio o video HTML5, o con qualsiasi libreria JS di lettore musicale

вљ пёЏ Se non chiami setPlaybackState(), i pulsanti appariranno ma Android non conoscerГ lo stato attuale: chiamalo sempre dopo play/pause

вљ пёЏ window.WebToApk ГЁ disponibile solo all'interno dell'app generata. Proteggi sempre le chiamate con:
if (window.WebToApk) { ... }

11Protezione per i test nel browser#

Il tuo sito si apre anche nei normali browser, dove window.WebToApk non esiste. Usa questo wrapper così il codice non va in errore in 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]);