Medya Bildirim Koprusu

1Medya Bildirim Köprüsü nedir?#

Web siteniz müzik veya ses çaldığında Android bundan haberdar olmaz. Kilit ekranı oynatıcısı, albüm kapağı, bildirim panelinde medya düğmeleri yoktur.

Medya Bildirim Köprüsü bunu çözer. JavaScript kodunuz Android'e şunları söyler:

• Hangi şarkının çaldığı (başlık, sanatçı, kapak görseli)
• Oynatılıyor mu yoksa duraklatılmış mı

Android daha sonra kontrollü uygun bir medya bildirimi gösterir. Kullanıcı bildirimde veya kilit ekranında Oynat/Duraklat/İleri/Geri'ye bastığında Android JavaScript'inizi geri çağırır ve siz yanıt verebilirsiniz.

Bunu iki yönlü bir köprü olarak düşünün:
Web sitenizin JS'si ⟷ Android Kilit Ekranı / Bildirim

2Oluşturucuda etkinleştirin#

Oluşturucunun 4. Adım'ında:

1. '🎵 Medya Bildirimi'ni AÇIN
2. APK'nızı oluşturun

Artık web sitenizin JS'si medya yöntemleriyle birlikte window.WebToApk'e erişebilir.

31. Adım - Android'e neyin çaldığını söyleyin#

Yeni bir parça başladığında web sitenizin JS'sinden bunu çağırın. Android bildirimi ve kilit ekranını hemen günceller.

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

42. Adım - Oynat / Duraklat durumunu güncelleyin#

Oynatma başladığında, duraklatıldığında veya konum değiştiğinde bunu çağırın. Android bunu doğru düğmeyi (▶ veya ⏸) göstermek ve arama çubuğunu doldurmak için kullanır.

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

53. Adım - Düğme basışlarını dinleyin#

Kullanıcı bildirimde veya kilit ekranında Oynat/Duraklat/İleri/Geri düğmelerine basabilir. Bu eylemleri almak ve yanıtlamak için web siteniz bu geri çağrı işlevini tanımlamalıdır.

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

64. Adım - Durdurulunca bildirimi temizleyin#

Kullanıcı oynatmayı tamamen durdurduğunda (yalnızca duraklatmadığında) bildirimi temel 'Arka planda çalışıyor' mesajına döndürmek ve medya kontrollerini kaldırmak için bunu çağırın.

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

7Oynat/Duraklat neden otomatik çalışır, ama İleri/Geri kod gerektirir#

Uygulamamızda bir 'Otomatik Medya Takipçisi' bulunur. Hiç özel kod yazmazsanız uygulama, standart <video> veya <audio> etiketlerinin oynatıldığını otomatik olarak algılar ve yedek olarak Oynat ve Duraklat düğmelerini otomatik çalıştırır.

Ancak standart HTML5 medya oynatıcılarında evrensel bir 'İleri' veya 'Geri' komutu YOKTUR (çünkü doğal olarak çalma listelerini desteklemezler). İleri/Geri'nin çalışması için web siteniz standart MediaSession API'sini (navigator.mediaSession.setActionHandler) açıkça kullanmalı veya bu düğmelere basıldığında uygulamanın tam olarak ne yapacağını söylemek için window.WebToApkOnMediaAction geri çağrısını tanımlamalıdır.

8Eksiksiz çalışan örnek#

Eksiksiz örnek - bir HTML5 ses öğesini Android medya bildirimine bağlamak için bunu web sitenize yapıştırın:

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

9Bildirim nasıl görünür#

Medya bildirimi, aşağı çekilen panelde ve kilit ekranında görünür:

┌───────────────────────────────────────┐
│ 🎵 [Uygulama Adınız] │
│ Bohemian Rhapsody │
│ Queen │
│ [albüm kapağı] ⏮ ⏸ ⏭ │
└───────────────────────────────────────┘

• ⏮ Geri - WebToApkOnMediaAction('prev') işlevinizi çağırır
• ⏸ / ▶ - 'pause' veya 'play' çağırır
• ⏭ İleri - 'next' çağırır

Bluetooth kulaklık düğmeleri ve Android Auto da aynı geri çağrıları otomatik olarak tetikler.

10Gereksinimler ve sınırlar#

✅ 'Foreground Service' anahtarının da AÇIK olmasını gerektirir (medya bildirimi için hizmetin çalışıyor olması gerekir)

✅ Kapak görseli sağladığınız URL'den alınır - herkese açık erişilebilir bir görsel olmalıdır (HTTPS tercih edilir)

✅ Herhangi bir HTML5 ses veya video öğesiyle ya da herhangi bir JS müzik çalar kütüphanesiyle çalışır

⚠️ setPlaybackState() çağırmazsanız düğmeler görünür ama Android mevcut durumu bilmez - oynat/duraklat sonrasında her zaman çağırın

⚠️ window.WebToApk yalnızca oluşturulan uygulamanın içinde bulunur. Çağrıları her zaman şununla koruyun:
if (window.WebToApk) { ... }

11Tarayıcı testi için güvenlik önlemi#

Web siteniz window.WebToApk'in bulunmadığı normal tarayıcılarda da açılır. Kodun Chrome/Safari'de çökmemesi için bu sarmalayıcıyı kullanın:

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