جسر إشعارات الوسائط

1ما هو جسر إشعار الوسائط؟#

عندما يشغّل موقعك موسيقى أو صوتًا، لا يعلم Android بذلك. لا مشغّل على شاشة القفل ولا غلاف ألبوم ولا أزرار وسائط في لوحة الإشعارات.

يحل جسر إشعار الوسائط هذا الأمر. يخبر كود JavaScript الخاص بك Android بما يلي:

• ما المقطع الذي يُشغَّل (العنوان والفنان وصورة الغلاف)
• هل هو قيد التشغيل أم متوقف مؤقتًا

يعرض Android بعد ذلك إشعار وسائط مناسبًا مع عناصر التحكم. وعندما يضغط المستخدم على تشغيل/إيقاف مؤقت/التالي/السابق في الإشعار أو شاشة القفل، يستدعي Android كود JavaScript الخاص بك لتتمكن من الاستجابة.

تخيّله جسرًا باتجاهين:
JS موقعك ⟷ شاشة القفل / الإشعار في Android

2التفعيل في المولّد#

في الخطوة 4 من المولّد:

1. فعّل '🎵 إشعار الوسائط'
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 القياسية (navigator.mediaSession.setActionHandler) أو يعرّف دالة window.WebToApkOnMediaAction لإخبار التطبيق بما يفعله عند الضغط على هذين الزرين.

8مثال عملي كامل#

مثال كامل: الصقه في موقعك لربط عنصر صوت 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 │
│ [غلاف الألبوم] ⏮ ⏸ ⏭ │
└───────────────────────────────────────┘

• ⏮ السابق: يستدعي WebToApkOnMediaAction('prev') الخاصة بك
• ⏸ / ▶ - يستدعي 'pause' أو 'play'
• ⏭ التالي: يستدعي 'next'

أزرار سماعات Bluetooth وAndroid Auto تُطلق دوال الاستدعاء نفسها تلقائيًا أيضًا.

10المتطلبات والحدود#

✅ يتطلب أن يكون مفتاح 'Foreground Service' مفعّلًا أيضًا (إشعار الوسائط يحتاج إلى تشغيل الخدمة)

✅ تُجلب صورة الغلاف من الرابط الذي تقدمه، ويجب أن تكون صورة متاحة للعامة (يُفضّل HTTPS)

✅ يعمل مع أي عنصر صوت أو فيديو HTML5، أو أي مكتبة مشغّل موسيقى بـ 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]);