Мост медиауведомлений

1Что такое мост медиауведомлений?#

Когда ваш сайт воспроизводит музыку или аудио, Android об этом не знает. Нет плеера на экране блокировки, нет обложки альбома, нет кнопок управления медиа в шторке уведомлений.

Мост медиауведомлений решает эту проблему. Ваш JavaScript-код сообщает Android:

• Какая песня играет (название, исполнитель, обложка)
• Воспроизводится или на паузе

После этого Android показывает полноценное медиауведомление с кнопками управления. Когда пользователь нажимает «Воспроизвести/Пауза/Далее/Назад» в уведомлении или на экране блокировки, Android вызывает ваш JavaScript, чтобы вы могли ответить.

Представьте двусторонний мост:
JS вашего сайта ⟷ Экран блокировки / уведомление Android

2Включите в генераторе#

На шаге 4 генератора:

1. Включите «🎵 Media Notification»
2. Создайте APK

Теперь JS вашего сайта имеет доступ к window.WebToApk с медиаметодами.

3Шаг 1 — сообщите Android, что воспроизводится#

Вызывайте это из JS вашего сайта каждый раз, когда начинается новый трек. Android сразу обновит уведомление и экран блокировки.

// 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Шаг 2 — обновляйте состояние воспроизведения / паузы#

Вызывайте это при каждом запуске, паузе или изменении позиции воспроизведения. Android использует это, чтобы показать нужную кнопку (▶ или ⏸) и заполнить полосу перемотки.

// 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Шаг 3 — отслеживайте нажатия кнопок#

Пользователь может нажимать «Воспроизвести/Пауза/Далее/Назад» в уведомлении или на экране блокировки. Ваш сайт должен определить эту функцию обратного вызова, чтобы получать эти действия и реагировать на них.

// 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Шаг 4 — убрать уведомление при остановке#

Когда пользователь полностью останавливает воспроизведение (а не просто ставит на паузу), вызовите это, чтобы вернуть уведомление к обычному сообщению «Работает в фоне» и убрать элементы управления медиа.

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

7Почему «Воспроизвести/Пауза» работает автоматически, а «Далее/Назад» требуют кода#

В нашем приложении есть «Автоматический медиатрекер». Если вы не пишете собственный код, приложение само определяет, когда воспроизводятся стандартные теги <video> или <audio>, и в качестве запасного варианта автоматически включает кнопки «Воспроизвести» и «Пауза».

Однако у стандартных HTML5-плееров нет универсальной команды «Далее» или «Назад» (они по своей природе не поддерживают плейлисты). Чтобы «Далее/Назад» заработали, ваш сайт ОБЯЗАТЕЛЬНО должен явно использовать стандартный MediaSession API (navigator.mediaSession.setActionHandler) или определить обратный вызов window.WebToApkOnMediaAction, чтобы приложение знало, что делать при нажатии этих кнопок.

8Полный рабочий пример#

Полный пример — вставьте его на свой сайт, чтобы связать элемент HTML5 audio с медиауведомлением 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Как выглядит уведомление#

Медиауведомление отображается в шторке и на экране блокировки:

┌───────────────────────────────────────┐
│ 🎵 [Название вашего приложения] │
│ Bohemian Rhapsody │
│ Queen │
│ [обложка альбома] ⏮ ⏸ ⏭ │
└───────────────────────────────────────┘

• ⏮ Назад — вызывает ваш WebToApkOnMediaAction('prev')
• ⏸ / ▶ — вызывает 'pause' или 'play'
• ⏭ Далее — вызывает 'next'

Кнопки Bluetooth-гарнитуры и Android Auto тоже автоматически вызывают те же обратные вызовы.

10Требования и ограничения#

✅ Нужно, чтобы переключатель «Foreground Service» тоже был ВКЛЮЧЁН (для медиауведомления должна работать служба)

✅ Обложка загружается по указанному вами URL — это должно быть публично доступное изображение (желательно HTTPS)

✅ Работает с любым элементом HTML5 audio или video и с любой JS-библиотекой музыкального плеера

⚠️ Если не вызвать setPlaybackState(), кнопки появятся, но Android не будет знать текущее состояние — всегда вызывайте его после воспроизведения или паузы

⚠️ window.WebToApk доступен только внутри созданного приложения. Всегда защищайте вызовы проверкой:
if (window.WebToApk) { ... }

11Защита для тестирования в браузере#

Ваш сайт также открывается в обычных браузерах, где window.WebToApk не существует. Используйте эту обёртку, чтобы код не падал в 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]);