Media Notification Bridge

1پل اعلان رسانه چیست؟#

وقتی وب‌سایت شما موسیقی یا صدا پخش می‌کند، Android از آن خبر ندارد. نه پخش‌کننده صفحه قفل هست، نه تصویر آلبوم، نه دکمه رسانه در پرده اعلان‌ها.

پل اعلان رسانه این مشکل را حل می‌کند. کد جاوا‌اسکریپت شما به Android می‌گوید:

• چه آهنگی پخش می‌شود (عنوان، هنرمند، تصویر جلد)
• در حال پخش است یا مکث شده

Android سپس یک اعلان رسانه مناسب با کنترل‌ها نشان می‌دهد. وقتی کاربر روی اعلان یا صفحه قفل Play/Pause/Next/Prev را می‌زند، Android جاوا‌اسکریپت شما را فراخوانی می‌کند تا پاسخ دهید.

آن را مثل یک پل دوطرفه تصور کنید:
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 - به‌روزرسانی وضعیت Play / Pause#

هر وقت پخش شروع شد، مکث شد یا موقعیت تغییر کرد این را فراخوانی کنید. 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 - گوش دادن به فشار دکمه‌ها#

کاربر می‌تواند روی اعلان یا صفحه قفل Play/Pause/Next/Prev را بزند. وب‌سایت شما باید این تابع callback را تعریف کند تا آن اقدام‌ها را دریافت کند و به آن‌ها پاسخ دهد.

// 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 - پاک کردن اعلان هنگام توقف#

وقتی کاربر پخش را کاملاً متوقف می‌کند (نه فقط مکث)، این را فراخوانی کنید تا اعلان به پیام ساده «Running in background» برگردد و کنترل‌های رسانه حذف شوند.

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

7چرا Play/Pause خودکار کار می‌کند، اما Next/Prev به کد نیاز دارد#

اپلیکیشن ما یک «ردیاب خودکار رسانه» دارد. اگر هیچ کد سفارشی ننویسید، اپلیکیشن به‌طور خودکار تشخیص می‌دهد که تگ‌های استاندارد <video> یا <audio> در حال پخش هستند و دکمه‌های Play و Pause را به‌عنوان جایگزین خودکار فعال می‌کند.

با این حال، پخش‌کننده‌های رسانه استاندارد HTML5 دستور «Next» یا «Previous» همگانی ندارند (چون ذاتاً از فهرست پخش پشتیبانی نمی‌کنند). برای کار کردن Next/Prev، وب‌سایت شما باید صریحاً از MediaSession API استاندارد (navigator.mediaSession.setActionHandler) استفاده کند یا تابع callback ـ window.WebToApkOnMediaAction را تعریف کند تا به اپلیکیشن بگوید با فشار این دکمه‌ها دقیقاً چه کند.

8مثال کامل و کارآمد#

مثال کامل - این را در وب‌سایت خود قرار دهید تا یک عنصر audio در HTML5 را به اعلان رسانه 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 │
│ [album art] ⏮ ⏸ ⏭ │
└───────────────────────────────────────┘

• ⏮ Prev - WebToApkOnMediaAction('prev') شما را فراخوانی می‌کند
• ⏸ / ▶ - 'pause' یا 'play' را فراخوانی می‌کند
• ⏭ Next - 'next' را فراخوانی می‌کند

دکمه‌های هدست بلوتوث و Android Auto هم به‌طور خودکار همین callbackها را فعال می‌کنند.

10الزامات و محدودیت‌ها#

✅ لازم است کلید «Foreground Service» هم روشن باشد (اعلان رسانه به اجرای سرویس نیاز دارد)

✅ تصویر جلد از نشانی‌ای که می‌دهید دریافت می‌شود - باید تصویری با دسترسی عمومی باشد (HTTPS ترجیح داده می‌شود)

✅ با هر عنصر صوتی یا تصویری HTML5، یا هر کتابخانه پخش‌کننده موسیقی جاوا‌اسکریپت کار می‌کند

⚠️ اگر setPlaybackState() را فراخوانی نکنید، دکمه‌ها ظاهر می‌شوند اما Android وضعیت فعلی را نمی‌داند - همیشه بعد از play/pause آن را فراخوانی کنید

⚠️ 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]);