Pont de notification média

1Qu'est-ce que le pont de notification multimédia ?#

Quand votre site joue de la musique ou de l'audio, Android n'en sait rien. Pas de lecteur sur l'écran de verrouillage, pas de pochette, pas de boutons multimédia dans le volet de notifications.

Le pont de notification multimédia règle cela. Votre code JavaScript indique à Android :

• Quel morceau est en cours (titre, artiste, pochette)
• S'il est en lecture ou en pause

Android affiche alors une vraie notification multimédia avec des commandes. Quand l'utilisateur appuie sur Lecture/Pause/Suivant/Précédent dans la notification ou sur l'écran de verrouillage, Android rappelle votre JavaScript pour que vous puissiez réagir.

Voyez-le comme un pont à double sens :
JS de votre site ⟷ Écran de verrouillage / Notification Android

2Activer dans le générateur#

À l'étape 4 du générateur :

1. Activez « 🎵 Notification multimédia »
2. Générez votre APK

Le JS de votre site a maintenant accès à window.WebToApk avec les méthodes multimédia.

3Étape 1 - Dire à Android ce qui est en lecture#

Appelez ceci depuis le JS de votre site chaque fois qu'un nouveau titre démarre. Android met aussitôt à jour la notification et l'écran de verrouillage.

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

4Étape 2 - Mettre à jour l'état Lecture / Pause#

Appelez ceci chaque fois que la lecture démarre, se met en pause ou que la position change. Android s'en sert pour afficher le bon bouton (▶ ou ⏸) et remplir la barre de progression.

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

5Étape 3 - Écouter les appuis sur les boutons#

L'utilisateur peut appuyer sur Lecture/Pause/Suivant/Précédent dans la notification ou sur l'écran de verrouillage. Votre site doit définir cette fonction de callback pour recevoir ces actions et y répondre.

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

6Étape 4 - Effacer la notification à l'arrêt#

Quand l'utilisateur arrête complètement la lecture (pas seulement une pause), appelez ceci pour ramener la notification au simple message « Fonctionne en arrière-plan » et supprimer les commandes multimédia.

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

7Pourquoi Lecture/Pause fonctionne automatiquement, mais Suivant/Précédent demande du code#

Notre application inclut un « suivi multimédia automatique ». Si vous n'écrivez aucun code personnalisé, l'application détecte automatiquement quand des balises <video> ou <audio> standard sont en lecture, et fait fonctionner automatiquement les boutons Lecture et Pause en solution de repli.

Cependant, les lecteurs multimédias HTML5 standard n'ont PAS de commande universelle « Suivant » ou « Précédent » (ils ne gèrent pas les playlists en eux-mêmes). Pour que Suivant/Précédent fonctionnent, votre site DOIT utiliser explicitement l'API standard MediaSession (navigator.mediaSession.setActionHandler) ou définir le callback window.WebToApkOnMediaAction pour dire à l'application quoi faire quand ces boutons sont pressés.

8Exemple complet#

Exemple complet : collez ceci dans votre site pour relier un élément audio HTML5 à la notification multimédia 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
};

9À quoi ressemble la notification#

La notification multimédia s'affiche dans le volet déroulant et sur l'écran de verrouillage :

┌───────────────────────────────────────┐
│ 🎵 [Nom de votre application] │
│ Bohemian Rhapsody │
│ Queen │
│ [pochette] ⏮ ⏸ ⏭ │
└───────────────────────────────────────┘

• ⏮ Précédent : appelle votre WebToApkOnMediaAction('prev')
• ⏸ / ▶ : appelle 'pause' ou 'play'
• ⏭ Suivant : appelle 'next'

Les boutons des écouteurs Bluetooth et Android Auto déclenchent aussi automatiquement les mêmes callbacks.

10Prérequis et limites#

✅ Nécessite que l'option « Service au premier plan » soit aussi ACTIVÉE (la notification multimédia a besoin que le service tourne)

✅ La pochette est récupérée depuis l'URL que vous fournissez : ce doit être une image accessible publiquement (HTTPS de préférence)

✅ Fonctionne avec tout élément audio ou vidéo HTML5, ou toute bibliothèque de lecteur de musique JS

⚠️ Si vous n'appelez pas setPlaybackState(), les boutons apparaîtront mais Android ne connaîtra pas l'état actuel : appelez-le toujours après lecture/pause

⚠️ window.WebToApk n'est disponible que dans l'application générée. Protégez toujours les appels avec :
if (window.WebToApk) { ... }

11Protection pour les tests dans le navigateur#

Votre site s'ouvre aussi dans des navigateurs classiques où window.WebToApk n'existe pas. Utilisez cet enveloppeur pour que le code ne plante pas dans 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]);