إضافة الميزات الأساسية إلى جهاز استقبال Android TV

تحتوي هذه الصفحة على مقتطفات من الرموز البرمجية وأوصاف للميزات المتاحة ل تخصيص تطبيق Android TV Receiver.

ضبط المكتبات

لإتاحة واجهات برمجة تطبيقات Cast Connect لتطبيق Android TV، اتّبِع الخطوات التالية:

Android
  1. افتح ملف build.gradle داخل دليل وحدة التطبيق.
  2. تأكَّد من أنّ google() مضمّن في repositories المدرَج.
      repositories {
        google()
      }
  3. استنادًا إلى نوع الجهاز المستهدَف لتطبيقك، أضِف أحدث إصدارات من المكتبات إلى التبعيات:
    • بالنسبة إلى تطبيق Android Receiver:
        dependencies {
          implementation 'com.google.android.gms:play-services-cast-tv:21.1.1'
          implementation 'com.google.android.gms:play-services-cast:22.0.0'
        }
    • بالنسبة إلى تطبيق Android المُرسِل:
        dependencies {
          implementation 'com.google.android.gms:play-services-cast:21.1.1'
          implementation 'com.google.android.gms:play-services-cast-framework:22.0.0'
        }
    احرص على تعديل رقم الإصدار هذا في كل مرة يتم فيها تحديث الخدمات.
  4. احفظ التغييرات وانقر على Sync Project with Gradle Files في شريط الأدوات.
iOS
  1. تأكَّد من أنّ Podfile يستهدف الإصدار 4.8.3 من google-cast-sdk أو إصدارًا أحدث.
  2. استهدِف الإصدار iOS 14 أو إصدارًا أحدث. يمكنك الاطّلاع على ملاحظات الإصدار للحصول على مزيد من التفاصيل.
      platform: ios, '14'
    
      def target_pods
         pod 'google-cast-sdk', '~>4.8.3'
      end
الويب
  1. يتطلّب الإصدار M87 من متصفّح Chromium أو إصدارًا أحدث.
  2. إضافة مكتبة Web Sender API إلى مشروعك
      <script src="//www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

متطلبات AndroidX

تتطلّب الإصدارات الجديدة من "خدمات Google Play" تحديث التطبيق لاستخدام مساحة الاسم androidx. اتّبِع التعليمات المتعلقة بنقل البيانات إلى AndroidX.

متطلبات تطبيق Android TV الأساسية

لتفعيل ميزة Cast Connect في تطبيق Android TV، عليك إنشاء أحداث وإتاحة استخدامها من جلسة وسائط. تقدِّم البيانات المقدَّمة من جلسة الوسائط المعلومات الأساسية، مثل الموضع وحالة التشغيل وما إلى ذلك، لحالة الوسائط. تستخدم مكتبة Cast Connect أيضًا جلسة الوسائط للإشارة إلى تلقّيها رسائل معيّنة من المُرسِل، مثل إيقاف مؤقت.

لمزيد من المعلومات عن جلسة الوسائط وكيفية بدء جلسة وسائط، يُرجى الاطّلاع على دليل العمل مع جلسة وسائط.

مراحل نشاط جلسة بث الوسائط

من المفترض أن ينشئ تطبيقك جلسة وسائط عند بدء التشغيل وأن يُطلقها عندما لا يمكن التحكّم فيها بعد ذلك. على سبيل المثال، إذا كان تطبيقك تطبيق فيديو، يجب إغلاق الجلسة عندما يخرج المستخدم من نشاط التشغيل، إما عن طريق اختيار "رجوع" لتصفّح محتوى آخر أو عن طريق تشغيل التطبيق في الخلفية. وإذا كان تطبيقك تطبيقًا موسيقيًا، يجب إغلاقه عندما يتوقف عن تشغيل أي وسائط.

تعديل حالة الجلسة

يجب تعديل البيانات في جلسة الوسائط وفقًا لحالة المشغّل. على سبيل المثال، عند إيقاف التشغيل مؤقتًا، عليك تعديل حالة التشغيل بالإضافة إلى الإجراءات المتوافقة. تعرِض الجداول التالية الولايات التي تتحمل فيها مسؤولية التعديل.

MediaMetadataCompat

حقل البيانات الوصفية الوصف
METADATA_KEY_TITLE (مطلوبة) عنوان الوسائط
METADATA_KEY_DISPLAY_SUBTITLE العنوان الفرعي
METADATA_KEY_DISPLAY_ICON_URI عنوان URL للرمز
METADATA_KEY_DURATION (سمة مطلوبة) مدة الوسائط
METADATA_KEY_MEDIA_URI رقم تعريف Content ID
METADATA_KEY_ARTIST الفنّان
METADATA_KEY_ALBUM الألبوم

PlaybackStateCompat

الطريقة المطلوبة الوصف
setActions() لضبط طلبات الوسائط المتوافقة
setState() ضبط حالة التشغيل والموضع الحالي

MediaSessionCompat

الطريقة المطلوبة الوصف
setRepeatMode() ضبط وضع التكرار
setShuffleMode() لضبط وضع الترتيب العشوائي
setMetadata() لضبط البيانات الوصفية للوسائط
setPlaybackState() لضبط حالة التشغيل
Kotlin
private fun updateMediaSession() {
    val metadata = MediaMetadataCompat.Builder()
         .putString(MediaMetadataCompat.METADATA_KEY_TITLE, "title")
         .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "subtitle")
         .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_ICON_URI, mMovie.getCardImageUrl())
         .build()

    val playbackState = PlaybackStateCompat.Builder()
         .setState(
             PlaybackStateCompat.STATE_PLAYING,
             player.getPosition(),
             player.getPlaybackSpeed(),
             System.currentTimeMillis()
        )
         .build()

    mediaSession.setMetadata(metadata)
    mediaSession.setPlaybackState(playbackState)
}
Java
private void updateMediaSession() {
  MediaMetadataCompat metadata =
      new MediaMetadataCompat.Builder()
          .putString(MediaMetadataCompat.METADATA_KEY_TITLE, "title")
          .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "subtitle")
          .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_ICON_URI,mMovie.getCardImageUrl())
          .build();

  PlaybackStateCompat playbackState =
      new PlaybackStateCompat.Builder()
          .setState(
               PlaybackStateCompat.STATE_PLAYING,
               player.getPosition(),
               player.getPlaybackSpeed(),
               System.currentTimeMillis())
          .build();

  mediaSession.setMetadata(metadata);
  mediaSession.setPlaybackState(playbackState);
}

التحكّم في وسائل النقل

يجب أن ينفذ تطبيقك طلب استدعاء التحكّم في نقل جلسة الوسائط. يعرض الجدول التالي إجراءات التحكّم في النقل التي يجب معالجتها:

MediaSessionCompat.Callback

المهام الوصف
onPlay() استئناف
onPause() إيقاف مؤقت
onSeekTo()‎ الانتقال إلى موضع
onStop() إيقاف الوسائط الحالية
Kotlin
class MyMediaSessionCallback : MediaSessionCompat.Callback() {
  override fun onPause() {
    // Pause the player and update the play state.
    ...
  }

  override fun onPlay() {
    // Resume the player and update the play state.
    ...
  }

  override fun onSeekTo (long pos) {
    // Seek and update the play state.
    ...
  }
  ...
}

mediaSession.setCallback( MyMediaSessionCallback() );
Java
public MyMediaSessionCallback extends MediaSessionCompat.Callback {
  public void onPause() {
    // Pause the player and update the play state.
    ...
  }

  public void onPlay() {
    // Resume the player and update the play state.
    ...
  }

  public void onSeekTo (long pos) {
    // Seek and update the play state.
    ...
  }
  ...
}

mediaSession.setCallback(new MyMediaSessionCallback());

ضبط إعدادات التوافق مع Cast

عندما يُرسِل تطبيق مُرسِل طلب تشغيل، يتم إنشاء نية باستخدام مساحة اسم التطبيق. ويكون تطبيقك مسؤولاً عن معالجتها وإنشاء مثيل للكائن CastReceiverContext عند تشغيل تطبيق التلفزيون. يجب استخدام العنصر CastReceiverContext للتفاعل مع جهاز البث أثناء تشغيل تطبيق التلفزيون. يتيح هذا العنصر لتطبيق التلفزيون قبول رسائل الوسائط عبر البث من أي مُرسِلين مرتبطين.

إعداد Android TV

إضافة فلتر لهدف الإطلاق

أضِف فلتر أهداف جديدًا إلى النشاط الذي تريد معالجة هدف الإطلاق من تطبيق المُرسِل:

<activity android:name="com.example.activity">
  <intent-filter>
      <action android:name="com.google.android.gms.cast.tv.action.LAUNCH" />
      <category android:name="android.intent.category.DEFAULT" />
  </intent-filter>
</activity>

تحديد مقدّم خيارات المستلِم

عليك تنفيذ ReceiverOptionsProvider لتوفير CastReceiverOptions:

Kotlin
class MyReceiverOptionsProvider : ReceiverOptionsProvider {
  override fun getOptions(context: Context?): CastReceiverOptions {
    return CastReceiverOptions.Builder(context)
          .setStatusText("My App")
          .build()
    }
}
Java
public class MyReceiverOptionsProvider implements ReceiverOptionsProvider {
  @Override
  public CastReceiverOptions getOptions(Context context) {
    return new CastReceiverOptions.Builder(context)
        .setStatusText("My App")
        .build();
  }
}

بعد ذلك، حدِّد مقدّم الخيارات في AndroidManifest:

 <meta-data
    android:name="com.google.android.gms.cast.tv.RECEIVER_OPTIONS_PROVIDER_CLASS_NAME"
    android:value="com.example.mysimpleatvapplication.MyReceiverOptionsProvider" />

تُستخدَم السمة ReceiverOptionsProvider لتقديم CastReceiverOptions عند بدء CastReceiverContext.

سياق جهاز استقبال البث

يمكنك إعداد ملف تعريف الارتباط CastReceiverContext عند إنشاء تطبيقك:

Kotlin
override fun onCreate() {
  CastReceiverContext.initInstance(this)

  ...
}
Java
@Override
public void onCreate() {
  CastReceiverContext.initInstance(this);

  ...
}

ابدأ CastReceiverContext عندما ينتقل تطبيقك إلى المقدّمة:

Kotlin
CastReceiverContext.getInstance().start()
Java
CastReceiverContext.getInstance().start();

اتصل على الرقم stop() على الرقم CastReceiverContext بعد أن ينتقل التطبيق إلى الخلفية في تطبيقات الفيديو أو التطبيقات التي لا تتيح التشغيل في الخلفية:

Kotlin
// Player has stopped.
CastReceiverContext.getInstance().stop()
Java
// Player has stopped.
CastReceiverContext.getInstance().stop();

بالإضافة إلى ذلك، إذا كان تطبيقك يتيح التشغيل في الخلفية، يمكنك الاتصال برقم stop() على CastReceiverContext عندما يتوقف التشغيل في الخلفية.

ننصحك بشدة باستخدام LifecycleObserver من مكتبة androidx.lifecycle لإدارة استدعاء CastReceiverContext.start() وCastReceiverContext.stop()، خاصةً إذا كان تطبيقك الأصلي يتضمّن أنشطة متعدّدة. ويساعد ذلك في تجنُّب حالات التداخل عند استدعاء start() وstop() من أنشطة مختلفة.

Kotlin
// Create a LifecycleObserver class.
class MyLifecycleObserver : DefaultLifecycleObserver {
  override fun onStart(owner: LifecycleOwner) {
    // App prepares to enter foreground.
    CastReceiverContext.getInstance().start()
  }

  override fun onStop(owner: LifecycleOwner) {
    // App has moved to the background or has terminated.
    CastReceiverContext.getInstance().stop()
  }
}

// Add the observer when your application is being created.
class MyApplication : Application() {
  fun onCreate() {
    super.onCreate()

    // Initialize CastReceiverContext.
    CastReceiverContext.initInstance(this /* android.content.Context */)

    // Register LifecycleObserver
    ProcessLifecycleOwner.get().lifecycle.addObserver(
        MyLifecycleObserver())
  }
}
Java
// Create a LifecycleObserver class.
public class MyLifecycleObserver implements DefaultLifecycleObserver {
  @Override
  public void onStart(LifecycleOwner owner) {
    // App prepares to enter foreground.
    CastReceiverContext.getInstance().start();
  }

  @Override
  public void onStop(LifecycleOwner owner) {
    // App has moved to the background or has terminated.
    CastReceiverContext.getInstance().stop();
  }
}

// Add the observer when your application is being created.
public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();

    // Initialize CastReceiverContext.
    CastReceiverContext.initInstance(this /* android.content.Context */);

    // Register LifecycleObserver
    ProcessLifecycleOwner.get().getLifecycle().addObserver(
        new MyLifecycleObserver());
  }
}
// In AndroidManifest.xml set MyApplication as the application class
<application
    ...
    android:name=".MyApplication">

ربط MediaSession بـ MediaManager

عند إنشاء MediaSession، عليك أيضًا تقديم الرمز المميّز الحالي لMediaSession إلى CastReceiverContext لكي يعرف إلى أين يرسل الأوامر ويسترجع حالة تشغيل الوسائط:

Kotlin
val mediaManager: MediaManager = receiverContext.getMediaManager()
mediaManager.setSessionCompatToken(currentMediaSession.getSessionToken())
Java
MediaManager mediaManager = receiverContext.getMediaManager();
mediaManager.setSessionCompatToken(currentMediaSession.getSessionToken());

عند إلغاء MediaSession بسبب عدم تشغيله، عليك ضبط رمز مميّز بلا قيمة على MediaManager:

Kotlin
myPlayer.stop()
mediaSession.release()
mediaManager.setSessionCompatToken(null)
Java
myPlayer.stop();
mediaSession.release();
mediaManager.setSessionCompatToken(null);

إذا كان تطبيقك يتيح تشغيل الوسائط عندما يكون في الخلفية، بدلاً من استدعاء CastReceiverContext.stop() عند إرسال تطبيقك إلى الخلفية، يجب عدم استدعائه إلا عندما يكون تطبيقك في الخلفية ولم يعُد يشغّل الوسائط. على سبيل المثال:

Kotlin
class MyLifecycleObserver : DefaultLifecycleObserver {
  ...
  // App has moved to the background.
  override fun onPause(owner: LifecycleOwner) {
    mIsBackground = true
    myStopCastReceiverContextIfNeeded()
  }
}

// Stop playback on the player.
private fun myStopPlayback() {
  myPlayer.stop()

  myStopCastReceiverContextIfNeeded()
}

// Stop the CastReceiverContext when both the player has
// stopped and the app has moved to the background.
private fun myStopCastReceiverContextIfNeeded() {
  if (mIsBackground && myPlayer.isStopped()) {
    CastReceiverContext.getInstance().stop()
  }
}
Java
public class MyLifecycleObserver implements DefaultLifecycleObserver {
  ...
  // App has moved to the background.
  @Override
  public void onPause(LifecycleOwner owner) {
    mIsBackground = true;

    myStopCastReceiverContextIfNeeded();
  }
}

// Stop playback on the player.
private void myStopPlayback() {
  myPlayer.stop();

  myStopCastReceiverContextIfNeeded();
}

// Stop the CastReceiverContext when both the player has
// stopped and the app has moved to the background.
private void myStopCastReceiverContextIfNeeded() {
  if (mIsBackground && myPlayer.isStopped()) {
    CastReceiverContext.getInstance().stop();
  }
}

استخدام Exoplayer مع Cast Connect

إذا كنت تستخدم Exoplayer، يمكنك استخدام MediaSessionConnector للحفاظ تلقائيًا على الجلسة وجميع المعلومات ذات الصلة، بما في ذلك حالة التشغيل بدلاً من تتبُّع التغييرات يدويًا.

يمكن استخدام MediaSessionConnector.MediaButtonEventHandler للتعامل مع أحداث MediaButton من خلال استدعاء setMediaButtonEventHandler(MediaButtonEventHandler) التي يتم التعامل معها تلقائيًا من خلال MediaSessionCompat.Callback.

لدمج MediaSessionConnector في تطبيقك، أضِف ما يلي إلى فئة نشاط المشغّل أو إلى أي مكان تديره فيه جلسة الوسائط:

Kotlin
class PlayerActivity : Activity() {
  private var mMediaSession: MediaSessionCompat? = null
  private var mMediaSessionConnector: MediaSessionConnector? = null
  private var mMediaManager: MediaManager? = null

  override fun onCreate(savedInstanceState: Bundle?) {
    ...
    mMediaSession = MediaSessionCompat(this, LOG_TAG)
    mMediaSessionConnector = MediaSessionConnector(mMediaSession!!)
    ...
  }

  override fun onStart() {
    ...
    mMediaManager = receiverContext.getMediaManager()
    mMediaManager!!.setSessionCompatToken(currentMediaSession.getSessionToken())
    mMediaSessionConnector!!.setPlayer(mExoPlayer)
    mMediaSessionConnector!!.setMediaMetadataProvider(mMediaMetadataProvider)
    mMediaSession!!.isActive = true
    ...
  }

  override fun onStop() {
    ...
    mMediaSessionConnector!!.setPlayer(null)
    mMediaSession!!.release()
    mMediaManager!!.setSessionCompatToken(null)
    ...
  }
}
Java
public class PlayerActivity extends Activity {
  private MediaSessionCompat mMediaSession;
  private MediaSessionConnector mMediaSessionConnector;
  private MediaManager mMediaManager;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ...
    mMediaSession = new MediaSessionCompat(this, LOG_TAG);
    mMediaSessionConnector = new MediaSessionConnector(mMediaSession);
    ...
  }

  @Override
  protected void onStart() {
    ...
    mMediaManager = receiverContext.getMediaManager();
    mMediaManager.setSessionCompatToken(currentMediaSession.getSessionToken());

    mMediaSessionConnector.setPlayer(mExoPlayer);
    mMediaSessionConnector.setMediaMetadataProvider(mMediaMetadataProvider);
    mMediaSession.setActive(true);
    ...
  }

  @Override
  protected void onStop() {
    ...
    mMediaSessionConnector.setPlayer(null);
    mMediaSession.release();
    mMediaManager.setSessionCompatToken(null);
    ...
  }
}

إعداد تطبيق المُرسِل

تفعيل التوافق مع Cast Connect

بعد تحديث تطبيق المُرسِل لتضمين واجهة برمجة التطبيقات Cast Connect، يمكنك تحديد جاهزيته من خلال ضبط علامة androidReceiverCompatible LaunchOptions على "صحيح".

Android

يتطلب الإصدار play-services-cast-framework 19.0.0 أو إصدارًا أحدث.

يتم ضبط العلامة androidReceiverCompatible في LaunchOptions (التي تشكّل جزءًا من CastOptions):

Kotlin
class CastOptionsProvider : OptionsProvider {
  override fun getCastOptions(context: Context?): CastOptions {
    val launchOptions: LaunchOptions = Builder()
          .setAndroidReceiverCompatible(true)
          .build()
    return CastOptions.Builder()
          .setLaunchOptions(launchOptions)
          ...
          .build()
    }
}
Java
public class CastOptionsProvider implements OptionsProvider {
  @Override
  public CastOptions getCastOptions(Context context) {
    LaunchOptions launchOptions = new LaunchOptions.Builder()
              .setAndroidReceiverCompatible(true)
              .build();
    return new CastOptions.Builder()
        .setLaunchOptions(launchOptions)
        ...
        .build();
  }
}
iOS

يتطلب الإصدار v4.4.8 من google-cast-sdk أو إصدارًا أحدث.

يتم ضبط العلامة androidReceiverCompatible في GCKLaunchOptions (التي هي جزء من GCKCastOptions):

let options = GCKCastOptions(discoveryCriteria: GCKDiscoveryCriteria(applicationID: kReceiverAppID))
...
let launchOptions = GCKLaunchOptions()
launchOptions.androidReceiverCompatible = true
options.launchOptions = launchOptions
GCKCastContext.setSharedInstanceWith(options)
الويب

يتطلب الإصدار M87 أو إصدارًا أحدث من متصفّح Chromium.

const context = cast.framework.CastContext.getInstance();
const castOptions = new cast.framework.CastOptions();
castOptions.receiverApplicationId = kReceiverAppID;
castOptions.androidReceiverCompatible = true;
context.setOptions(castOptions);

إعداد Play Console لأجهزة البث

ضبط تطبيق Android TV

أضِف اسم حزمة تطبيق Android TV في Cast Developer Console لربطه بمعرّف تطبيق Cast.

تسجيل أجهزة المطوّرين

سجِّل الرقم التسلسلي لجهاز Android TV الذي ستستخدمه للتعلّم في Cast Developer Console.

بدون التسجيل، لن تعمل أداة Cast Connect إلا مع التطبيقات المثبَّتة من متجر Google Play لأسباب تتعلق بالأمان.

لمزيد من المعلومات حول تسجيل جهاز Cast أو Android TV لتطوير تطبيقات Cast، يُرجى الاطّلاع على صفحة التسجيل.

جارٍ تحميل الوسائط

إذا سبق لك تفعيل ميزة الروابط لصفحات في تطبيق Android TV، يجب أن يكون لديك تعريف مشابه تم ضبطه في بيان Android TV:

<activity android:name="com.example.activity">
  <intent-filter>
     <action android:name="android.intent.action.VIEW" />
     <category android:name="android.intent.category.DEFAULT" />
     <data android:scheme="https"/>
     <data android:host="www.example.com"/>
     <data android:pathPattern=".*"/>
  </intent-filter>
</activity>

التحميل حسب نوع المحتوى في الرسالة المرسَلة

بالنسبة إلى المُرسِلين، يمكنك تمرير الرابط لصفحة في التطبيق من خلال ضبط entity في ملف media معلومات طلب التحميل:

Kotlin
val mediaToLoad = MediaInfo.Builder("some-id")
    .setEntity("https://example.com/watch/some-id")
    ...
    .build()
val loadRequest = MediaLoadRequestData.Builder()
    .setMediaInfo(mediaToLoad)
    .setCredentials("user-credentials")
    ...
    .build()
remoteMediaClient.load(loadRequest)
Android
Java
MediaInfo mediaToLoad =
    new MediaInfo.Builder("some-id")
        .setEntity("https://example.com/watch/some-id")
        ...
        .build();
MediaLoadRequestData loadRequest =
    new MediaLoadRequestData.Builder()
        .setMediaInfo(mediaToLoad)
        .setCredentials("user-credentials")
        ...
        .build();
remoteMediaClient.load(loadRequest);
iOS
let mediaInfoBuilder = GCKMediaInformationBuilder(entity: "https://example.com/watch/some-id")
...
mediaInformation = mediaInfoBuilder.build()

let mediaLoadRequestDataBuilder = GCKMediaLoadRequestDataBuilder()
mediaLoadRequestDataBuilder.mediaInformation = mediaInformation
mediaLoadRequestDataBuilder.credentials = "user-credentials"
...
let mediaLoadRequestData = mediaLoadRequestDataBuilder.build()

remoteMediaClient?.loadMedia(with: mediaLoadRequestData)
الويب

يتطلب الإصدار M87 أو إصدارًا أحدث من متصفّح Chromium.

let mediaInfo = new chrome.cast.media.MediaInfo('some-id"', 'video/mp4');
mediaInfo.entity = 'https://example.com/watch/some-id';
...

let request = new chrome.cast.media.LoadRequest(mediaInfo);
request.credentials = 'user-credentials';
...

cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request);

يتم إرسال أمر التحميل من خلال نية تتضمّن الرابط لصفحة معيّنة في تطبيقك واسم الحزمة التي حدّدتها في "وحدة تحكّم المطوّر".

ضبط بيانات اعتماد ATV على المُرسِل

من الممكن أن يتيح تطبيق Web Receiver وتطبيق Android TV استخدام روابط credentials وعناوين مقصودة مختلفة (على سبيل المثال، إذا كنت تتعامل مع المصادقة بشكل مختلف على النظامَين الأساسيَين). لحلّ هذه المشكلة، يمكنك تقديم بديلين entity وcredentials لأجهزة Android TV:

Android
Kotlin
val mediaToLoad = MediaInfo.Builder("some-id")
        .setEntity("https://example.com/watch/some-id")
        .setAtvEntity("myscheme://example.com/atv/some-id")
        ...
        .build()
val loadRequest = MediaLoadRequestData.Builder()
        .setMediaInfo(mediaToLoad)
        .setCredentials("user-credentials")
        .setAtvCredentials("atv-user-credentials")
        ...
        .build()
remoteMediaClient.load(loadRequest)
Java
MediaInfo mediaToLoad =
    new MediaInfo.Builder("some-id")
        .setEntity("https://example.com/watch/some-id")
        .setAtvEntity("myscheme://example.com/atv/some-id")
        ...
        .build();
MediaLoadRequestData loadRequest =
    new MediaLoadRequestData.Builder()
        .setMediaInfo(mediaToLoad)
        .setCredentials("user-credentials")
        .setAtvCredentials("atv-user-credentials")
        ...
        .build();
remoteMediaClient.load(loadRequest);
iOS
let mediaInfoBuilder = GCKMediaInformationBuilder(entity: "https://example.com/watch/some-id")
mediaInfoBuilder.atvEntity = "myscheme://example.com/atv/some-id"
...
mediaInformation = mediaInfoBuilder.build()

let mediaLoadRequestDataBuilder = GCKMediaLoadRequestDataBuilder()
mediaLoadRequestDataBuilder.mediaInformation = mediaInformation
mediaLoadRequestDataBuilder.credentials = "user-credentials"
mediaLoadRequestDataBuilder.atvCredentials = "atv-user-credentials"
...
let mediaLoadRequestData = mediaLoadRequestDataBuilder.build()

remoteMediaClient?.loadMedia(with: mediaLoadRequestData)
الويب

يتطلب الإصدار M87 أو إصدارًا أحدث من متصفّح Chromium.

let mediaInfo = new chrome.cast.media.MediaInfo('some-id"', 'video/mp4');
mediaInfo.entity = 'https://example.com/watch/some-id';
mediaInfo.atvEntity = 'myscheme://example.com/atv/some-id';
...

let request = new chrome.cast.media.LoadRequest(mediaInfo);
request.credentials = 'user-credentials';
request.atvCredentials = 'atv-user-credentials';
...

cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request);

في حال تشغيل تطبيق Web Receiver، يستخدم entity وcredentials في طلب التحميل. ومع ذلك، إذا تم تشغيل تطبيق Android TV، تلغي حزمة SDK entity وcredentials وتستخدِم atvEntity وatvCredentials (إذا تم تحديدهما).

التحميل باستخدام Content ID أو MediaQueueData

إذا كنت لا تستخدم entity أو atvEntity، وكنت تستخدم Content ID أو عنوان URL للمحتوى في معلومات الوسائط أو كنت تستخدم بيانات طلب تحميل الوسائط المفصّلة أكثر، عليك إضافة فلتر الغرض المحدّد مسبقًا التالي في تطبيق Android TV:

<activity android:name="com.example.activity">
  <intent-filter>
     <action android:name="com.google.android.gms.cast.tv.action.LOAD"/>
     <category android:name="android.intent.category.DEFAULT" />
  </intent-filter>
</activity>

على جانب المُرسِل، يمكنك، مثل التحميل حسب نوع المحتوى، إنشاء طلب تحميل يتضمّن معلومات المحتوى وطلب load().

Android
Kotlin
val mediaToLoad = MediaInfo.Builder("some-id").build()
val loadRequest = MediaLoadRequestData.Builder()
    .setMediaInfo(mediaToLoad)
    .setCredentials("user-credentials")
    ...
    .build()
remoteMediaClient.load(loadRequest)
Java
MediaInfo mediaToLoad =
    new MediaInfo.Builder("some-id").build();
MediaLoadRequestData loadRequest =
    new MediaLoadRequestData.Builder()
        .setMediaInfo(mediaToLoad)
        .setCredentials("user-credentials")
        ...
        .build();
remoteMediaClient.load(loadRequest);
iOS
let mediaInfoBuilder = GCKMediaInformationBuilder(contentId: "some-id")
...
mediaInformation = mediaInfoBuilder.build()

let mediaLoadRequestDataBuilder = GCKMediaLoadRequestDataBuilder()
mediaLoadRequestDataBuilder.mediaInformation = mediaInformation
mediaLoadRequestDataBuilder.credentials = "user-credentials"
...
let mediaLoadRequestData = mediaLoadRequestDataBuilder.build()

remoteMediaClient?.loadMedia(with: mediaLoadRequestData)
الويب

يتطلب الإصدار M87 أو إصدارًا أحدث من متصفّح Chromium.

let mediaInfo = new chrome.cast.media.MediaInfo('some-id"', 'video/mp4');
...

let request = new chrome.cast.media.LoadRequest(mediaInfo);
...

cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request);

التعامل مع طلبات التحميل

في نشاطك، لمعالجة طلبات التحميل هذه، عليك معالجة النوايا في وظائف الاستدعاء الخاصة بدورة حياة النشاط:

Kotlin
class MyActivity : Activity() {
  override fun onStart() {
    super.onStart()
    val mediaManager = CastReceiverContext.getInstance().getMediaManager()
    // Pass the intent to the SDK. You can also do this in onCreate().
    if (mediaManager.onNewIntent(intent)) {
        // If the SDK recognizes the intent, you should early return.
        return
    }
    // If the SDK doesn't recognize the intent, you can handle the intent with
    // your own logic.
    ...
  }

  // For some cases, a new load intent triggers onNewIntent() instead of
  // onStart().
  override fun onNewIntent(intent: Intent) {
    val mediaManager = CastReceiverContext.getInstance().getMediaManager()
    // Pass the intent to the SDK. You can also do this in onCreate().
    if (mediaManager.onNewIntent(intent)) {
        // If the SDK recognizes the intent, you should early return.
        return
    }
    // If the SDK doesn't recognize the intent, you can handle the intent with
    // your own logic.
    ...
  }
}
Java
public class MyActivity extends Activity {
  @Override
  protected void onStart() {
    super.onStart();
    MediaManager mediaManager =
        CastReceiverContext.getInstance().getMediaManager();
    // Pass the intent to the SDK. You can also do this in onCreate().
    if (mediaManager.onNewIntent(getIntent())) {
      // If the SDK recognizes the intent, you should early return.
      return;
    }
    // If the SDK doesn't recognize the intent, you can handle the intent with
    // your own logic.
    ...
  }

  // For some cases, a new load intent triggers onNewIntent() instead of
  // onStart().
  @Override
  protected void onNewIntent(Intent intent) {
    MediaManager mediaManager =
        CastReceiverContext.getInstance().getMediaManager();
    // Pass the intent to the SDK. You can also do this in onCreate().
    if (mediaManager.onNewIntent(intent)) {
      // If the SDK recognizes the intent, you should early return.
      return;
    }
    // If the SDK doesn't recognize the intent, you can handle the intent with
    // your own logic.
    ...
  }
}

إذا رصد MediaManager أنّ النية هي نية تحميل، يستخرج MediaLoadRequestData كائنًا من النية، ويُستخدَم MediaLoadCommandCallback.onLoad(). عليك إلغاء هذه الطريقة لمعالجة طلب التحميل. يجب تسجيل دالة الاستدعاء قبل استدعاءMediaManager.onNewIntent() (ننصح باستخدام طريقة onCreate() في النشاط أو التطبيق).

Kotlin
class MyActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val mediaManager = CastReceiverContext.getInstance().getMediaManager()
        mediaManager.setMediaLoadCommandCallback(MyMediaLoadCommandCallback())
    }
}

class MyMediaLoadCommandCallback : MediaLoadCommandCallback() {
  override fun onLoad(
        senderId: String?,
        loadRequestData: MediaLoadRequestData
  ): Task {
      return Tasks.call {
        // Resolve the entity into your data structure and load media.
        val mediaInfo = loadRequestData.getMediaInfo()
        if (!checkMediaInfoSupported(mediaInfo)) {
            // Throw MediaException to indicate load failure.
            throw MediaException(
                MediaError.Builder()
                    .setDetailedErrorCode(DetailedErrorCode.LOAD_FAILED)
                    .setReason(MediaError.ERROR_REASON_INVALID_REQUEST)
                    .build()
            )
        }
        myFillMediaInfo(MediaInfoWriter(mediaInfo))
        myPlayerLoad(mediaInfo.getContentUrl())

        // Update media metadata and state (this clears all previous status
        // overrides).
        castReceiverContext.getMediaManager()
            .setDataFromLoad(loadRequestData)
        ...
        castReceiverContext.getMediaManager().broadcastMediaStatus()

        // Return the resolved MediaLoadRequestData to indicate load success.
        return loadRequestData
     }
  }

  private fun myPlayerLoad(contentURL: String) {
    myPlayer.load(contentURL)

    // Update the MediaSession state.
    val playbackState: PlaybackStateCompat = Builder()
        .setState(
            player.getState(), player.getPosition(), System.currentTimeMillis()
        )
        ...
        .build()
    mediaSession.setPlaybackState(playbackState)
  }
Java
public class MyActivity extends Activity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    MediaManager mediaManager =
        CastReceiverContext.getInstance().getMediaManager();
    mediaManager.setMediaLoadCommandCallback(new MyMediaLoadCommandCallback());
  }
}

public class MyMediaLoadCommandCallback extends MediaLoadCommandCallback {
  @Override
  public Task onLoad(String senderId, MediaLoadRequestData loadRequestData) {
    return Tasks.call(() -> {
        // Resolve the entity into your data structure and load media.
        MediaInfo mediaInfo = loadRequestData.getMediaInfo();
        if (!checkMediaInfoSupported(mediaInfo)) {
          // Throw MediaException to indicate load failure.
          throw new MediaException(
              new MediaError.Builder()
                  .setDetailedErrorCode(DetailedErrorCode.LOAD_FAILED)
                  .setReason(MediaError.ERROR_REASON_INVALID_REQUEST)
                  .build());
        }
        myFillMediaInfo(new MediaInfoWriter(mediaInfo));
        myPlayerLoad(mediaInfo.getContentUrl());

        // Update media metadata and state (this clears all previous status
        // overrides).
        castReceiverContext.getMediaManager()
            .setDataFromLoad(loadRequestData);
        ...
        castReceiverContext.getMediaManager().broadcastMediaStatus();

        // Return the resolved MediaLoadRequestData to indicate load success.
        return loadRequestData;
    });
}

private void myPlayerLoad(String contentURL) {
  myPlayer.load(contentURL);

  // Update the MediaSession state.
  PlaybackStateCompat playbackState =
      new PlaybackStateCompat.Builder()
          .setState(
              player.getState(), player.getPosition(), System.currentTimeMillis())
          ...
          .build();
  mediaSession.setPlaybackState(playbackState);
}

لمعالجة نية التحميل، يمكنك تحليل النية إلى هياكل البيانات التي حدّدناها (MediaLoadRequestData لطلبات التحميل).

إتاحة طلبات الوسائط

إتاحة عناصر التحكّم الأساسية في التشغيل

تتضمّن أوامر الدمج الأساسية الأوامر المتوافقة مع جلسة media. يتم إرسال إشعارات بشأن هذه الأوامر من خلال عمليات الاستدعاء لجلسة الوسائط. عليك تسجيل مكالمة لاحقة لجلسة الوسائط لتفعيل هذه الميزة (قد تكون تفعل ذلك حاليًا).

Kotlin
private class MyMediaSessionCallback : MediaSessionCompat.Callback() {
  override fun onPause() {
    // Pause the player and update the play state.
    myPlayer.pause()
  }

  override fun onPlay() {
    // Resume the player and update the play state.
    myPlayer.play()
  }

  override fun onSeekTo(pos: Long) {
    // Seek and update the play state.
    myPlayer.seekTo(pos)
  }
    ...
 }

mediaSession.setCallback(MyMediaSessionCallback())
Java
private class MyMediaSessionCallback extends MediaSessionCompat.Callback {
  @Override
  public void onPause() {
    // Pause the player and update the play state.
    myPlayer.pause();
  }
  @Override
  public void onPlay() {
    // Resume the player and update the play state.
    myPlayer.play();
  }
  @Override
  public void onSeekTo(long pos) {
    // Seek and update the play state.
    myPlayer.seekTo(pos);
  }

  ...
}

mediaSession.setCallback(new MyMediaSessionCallback());

إتاحة طلبات التحكّم في أجهزة البث

هناك بعض أوامر البث التي لا تتوفّر في MediaSession، مثل skipAd() أو setActiveMediaTracks(). يجب أيضًا تنفيذ بعض أوامر قائمة الانتظار هنا لأنّ قائمة انتظار البث لا تتوافق تمامًا مع قائمة انتظار MediaSession.

Kotlin
class MyMediaCommandCallback : MediaCommandCallback() {
    override fun onSkipAd(requestData: RequestData?): Task<Void?> {
        // Skip your ad
        ...
        return Tasks.forResult(null)
    }
}

val mediaManager = CastReceiverContext.getInstance().getMediaManager()
mediaManager.setMediaCommandCallback(MyMediaCommandCallback())
Java
public class MyMediaCommandCallback extends MediaCommandCallback {
  @Override
  public Task onSkipAd(RequestData requestData) {
    // Skip your ad
    ...
    return Tasks.forResult(null);
  }
}

MediaManager mediaManager =
    CastReceiverContext.getInstance().getMediaManager();
mediaManager.setMediaCommandCallback(new MyMediaCommandCallback());

تحديد أوامر الوسائط المتوافقة

كما هو الحال مع جهاز استقبال البث، يجب أن يحدِّد تطبيق Android TV الأوامر المتوافقة، حتى يتمكّن المرسِلون من تفعيل عناصر تحكّم معيّنة في واجهة المستخدم أو إيقافها. بالنسبة إلى الطلبات التي تشكّل جزءًا من MediaSession، حدِّد الطلبات في PlaybackStateCompat. يجب تحديد الأوامر الإضافية في ملف برمجي MediaStatusModifier.

Kotlin
// Set media session supported commands
val playbackState: PlaybackStateCompat = PlaybackStateCompat.Builder()
    .setActions(PlaybackStateCompat.ACTION_PLAY or PlaybackStateCompat.ACTION_PAUSE)
    .setState(PlaybackStateCompat.STATE_PLAYING)
    .build()

mediaSession.setPlaybackState(playbackState)

// Set additional commands in MediaStatusModifier
val mediaManager = CastReceiverContext.getInstance().getMediaManager()
mediaManager.getMediaStatusModifier()
    .setMediaCommandSupported(MediaStatus.COMMAND_QUEUE_NEXT)
Java
// Set media session supported commands
PlaybackStateCompat playbackState =
    new PlaybackStateCompat.Builder()
        .setActions(PlaybackStateCompat.ACTION_PLAY | PlaybackStateCompat.ACTION_PAUSE)
        .setState(PlaybackStateCompat.STATE_PLAYING)
        .build();

mediaSession.setPlaybackState(playbackState);

// Set additional commands in MediaStatusModifier
MediaManager mediaManager = CastReceiverContext.getInstance().getMediaManager();
mediaManager.getMediaStatusModifier()
            .setMediaCommandSupported(MediaStatus.COMMAND_QUEUE_NEXT);

إخفاء الأزرار غير المتوافقة

إذا كان تطبيق Android TV يتيح فقط التحكّم الأساسي في الوسائط ولكن تطبيق Web Receiver يتيح التحكّم بشكل أكثر تقدمًا، يجب التأكّد من سلوك تطبيق المُرسِل بشكل صحيح عند البث إلى تطبيق Android TV. على سبيل المثال، إذا كان تطبيق Android TV لا يتيح تغيير معدل التشغيل ولكن تطبيق Web Receiver يتيح ذلك، يجب ضبط الإجراءات المتوافقة بشكل صحيح على كل نظام أساسي والتأكّد من عرض تطبيق المُرسِل واجهة المستخدم بشكل صحيح.

تعديل MediaStatus

لتفعيل الميزات المتقدّمة، مثل الأغاني والإعلانات والبث المباشر وإضافة المحتوى إلى "قائمة المحتوى التالي"، يجب أن يقدّم تطبيق Android TV معلومات إضافية لا يمكن الحصول عليها من خلال MediaSession.

نوفّر لك فئة MediaStatusModifier لتحقيق ذلك. سيتم تشغيل MediaStatusModifier دائمًا على السرعة MediaSession التي ضبطتها في CastReceiverContext.

لإنشاء بث مباشر على Facebook باستخدام MediaStatus:

Kotlin
val mediaManager: MediaManager = castReceiverContext.getMediaManager()
val statusModifier: MediaStatusModifier = mediaManager.getMediaStatusModifier()

statusModifier
    .setLiveSeekableRange(seekableRange)
    .setAdBreakStatus(adBreakStatus)
    .setCustomData(customData)

mediaManager.broadcastMediaStatus()
Java
MediaManager mediaManager = castReceiverContext.getMediaManager();
MediaStatusModifier statusModifier = mediaManager.getMediaStatusModifier();

statusModifier
    .setLiveSeekableRange(seekableRange)
    .setAdBreakStatus(adBreakStatus)
    .setCustomData(customData);

mediaManager.broadcastMediaStatus();

ستحصل مكتبة العملاء على القيمة الأساسية MediaStatus من MediaSession، ويمكن لتطبيق Android TV تحديد حالة إضافية وإلغاء الحالة من خلال مُعدِّل MediaStatus.

يمكن ضبط بعض الحالات والبيانات الوصفية في كل من MediaSession و MediaStatusModifier. ننصحك بشدّة بضبطها في MediaSession فقط. لا يزال بإمكانك استخدام المُعدِّل لإلغاء الحالات في MediaSession، ولكن لا يُنصح بذلك لأنّ الحالة في المُعدِّل تُمنَح دائمًا أولوية أعلى من القيم التي يوفّرها MediaSession.

اعتراض MediaStatus قبل الإرسال

تمامًا مثل حزمة تطوير البرامج (SDK) لمستقبل الويب، إذا كنت تريد إجراء بعض اللمسات النهائية قبل الإرسال، يمكنك تحديد MediaStatusInterceptor لمعالجة MediaStatus المطلوب إرساله. نُدخل MediaStatusWriter لمعالجة MediaStatus قبل إرساله.

Kotlin
mediaManager.setMediaStatusInterceptor(object : MediaStatusInterceptor {
    override fun intercept(mediaStatusWriter: MediaStatusWriter) {
      // Perform customization.
        mediaStatusWriter.setCustomData(JSONObject("{data: \"my Hello\"}"))
    }
})
Java
mediaManager.setMediaStatusInterceptor(new MediaStatusInterceptor() {
    @Override
    public void intercept(MediaStatusWriter mediaStatusWriter) {
        // Perform customization.
        mediaStatusWriter.setCustomData(new JSONObject("{data: \"my Hello\"}"));
    }
});

التعامل مع بيانات اعتماد المستخدمين

قد لا يسمح تطبيق Android TV إلا لمستخدمين معيّنين بتشغيل جلسة التطبيق أو الانضمام إليها. على سبيل المثال، لا تسمح للمُرسِل ببدء جلسة أو الانضمام إليها إلا في الحالات التالية:

  • يجب أن يكون تطبيق المُرسِل مسجّلاً الدخول إلى الحساب والملف الشخصي نفسهما المستخدَمَين في تطبيق ATV.
  • تم تسجيل الدخول إلى تطبيق المُرسِل باستخدام الحساب نفسه، ولكن باستخدام ملف شخصي مختلف عن تطبيق ATV.

إذا كان تطبيقك قادرًا على التعامل مع مستخدمين متعدّدين أو مجهولين، يمكنك السماح لأي مستخدم إضافي بالانضمام إلى جلسة ATV. إذا قدّم المستخدم بيانات الاعتماد، يجب أن يتعامل تطبيق ATV مع بيانات اعتماده حتى يمكن تتبُّع مستوى تقدّمه وبيانات المستخدم الأخرى بشكلٍ سليم.

عند تشغيل تطبيق المُرسِل أو الانضمام إلى تطبيق Android TV، يجب أن يقدّم تطبيق المُرسِل بيانات الاعتماد التي تمثّل المستخدم الذي ينضم إلى الجلسة.

قبل أن يطلق المُرسِل تطبيق Android TV وينضم إليه، يمكنك تحديد أداة التحقّق من الإطلاق لمعرفة ما إذا كانت بيانات اعتماد المُرسِل مسموحًا بها. وإذا لم يكن الأمر كذلك، سيعود حِزم تطوير البرامج (SDK) لـ Cast Connect إلى تشغيل Web Receiver.

بيانات بيانات اعتماد تشغيل تطبيق المرسِل

على جانب المُرسِل، يمكنك تحديد CredentialsData لتمثيل المستخدم الذي ينضم إلى الجلسة.

credentials هي سلسلة يمكن للمستخدم تحديدها، ما دام تطبيق ATV يمكنه فهمها. يحدِّد credentialsType المنصة التي تأتي منها CredentialsData أو يمكن أن يكون قيمة مخصّصة. يتم ضبطه تلقائيًا على المنصة التي يتم إرسالها منها.

لا يتم تمرير CredentialsData إلى تطبيق Android TV إلا أثناء الإطلاق أو وقت الانضمام. إذا أعددت الملف الشخصي مرة أخرى أثناء الاتصال، لن يتم تمريره إلى تطبيق Android TV. إذا بدّل المُرسِل الملف الشخصي أثناء الاتصال، يمكنك البقاء في الجلسة أو الاتصال بـ SessionManager.endCurrentCastSession(boolean stopCasting) إذا كنت تعتقد أنّ الملف الشخصي الجديد غير متوافق مع الجلسة.

يمكن استرداد ملف تعريف البريد الإلكتروني CredentialsData لكل مُرسِل باستخدام getSenders في CastReceiverContext للحصول على SenderInfo، getCastLaunchRequest() للحصول على CastLaunchRequest، ثم getCredentialsData().

Android

يتطلب الإصدار play-services-cast-framework 19.0.0 أو إصدارًا أحدث.

Kotlin
CastContext.getSharedInstance().setLaunchCredentialsData(
    CredentialsData.Builder()
        .setCredentials("{\"userId\": \"abc\"}")
        .build()
)
Java
CastContext.getSharedInstance().setLaunchCredentialsData(
    new CredentialsData.Builder()
        .setCredentials("{\"userId\": \"abc\"}")
        .build());
iOS

يتطلب الإصدار v4.8.3 من google-cast-sdk أو إصدارًا أحدث.

يمكن الاتصال بها في أي وقت بعد ضبط الخيارات: GCKCastContext.setSharedInstanceWith(options).

GCKCastContext.sharedInstance().setLaunch(
    GCKCredentialsData(credentials: "{\"userId\": \"abc\"}")
الويب

يتطلب الإصدار M87 أو إصدارًا أحدث من متصفّح Chromium.

يمكن الاتصال بها في أي وقت بعد ضبط الخيارات: cast.framework.CastContext.getInstance().setOptions(options);.

let credentialsData =
    new chrome.cast.CredentialsData("{\"userId\": \"abc\"}");
cast.framework.CastContext.getInstance().setLaunchCredentialsData(credentialsData);

تنفيذ أداة التحقّق من طلبات إطلاق التطبيقات على التلفزيون

يتم تمرير رمز الالتقاط CredentialsData إلى تطبيق Android TV عندما يحاول المُرسِل تشغيله أو الانضمام إليه. يمكنك تنفيذ LaunchRequestChecker. للسماح بهذا الطلب أو رفضه

في حال رفض طلب، يتم تحميل Web Receiver بدلاً من تشغيله بشكل أصلي في تطبيق ATV. يجب رفض الطلب إذا تعذّر على ATV معالجة طلب المستخدم لبدء البث أو الانضمام إليه. يمكن أن تشمل الأمثلة تسجيل دخول مستخدم مختلف إلى تطبيق ATV عن المستخدم الذي يطلب التبديل وعدم تمكّن تطبيقك من معالجة تبديل بيانات الاعتماد، أو عدم تسجيل أي مستخدم حاليًا الدخول إلى تطبيق ATV.

إذا تم السماح بالطلب، سيتم تشغيل تطبيق ATV. يمكنك تخصيص هذا السلوك تبعًا لما إذا كان تطبيقك يتيح إرسال طلبات التحميل عندما يكون أحد المستخدمين لم يسجِّل الدخول إلى تطبيق ATV أو إذا كان هناك تعارض في بيانات المستخدم. يمكن تعديل هذا السلوك بشكل كامل في LaunchRequestChecker.

أنشئ فئة تنفِّذ واجهة CastReceiverOptions.LaunchRequestChecker:

Kotlin
class MyLaunchRequestChecker : LaunchRequestChecker {
  override fun checkLaunchRequestSupported(launchRequest: CastLaunchRequest): Task {
    return Tasks.call {
      myCheckLaunchRequest(
           launchRequest
      )
    }
  }
}

private fun myCheckLaunchRequest(launchRequest: CastLaunchRequest): Boolean {
  val credentialsData = launchRequest.getCredentialsData()
     ?: return false // or true if you allow anonymous users to join.

  // The request comes from a mobile device, e.g. checking user match.
  return if (credentialsData.credentialsType == CredentialsData.CREDENTIALS_TYPE_ANDROID) {
     myCheckMobileCredentialsAllowed(credentialsData.getCredentials())
  } else false // Unrecognized credentials type.
}
Java
public class MyLaunchRequestChecker
    implements CastReceiverOptions.LaunchRequestChecker {
  @Override
  public Task checkLaunchRequestSupported(CastLaunchRequest launchRequest) {
    return Tasks.call(() -> myCheckLaunchRequest(launchRequest));
  }
}

private boolean myCheckLaunchRequest(CastLaunchRequest launchRequest) {
  CredentialsData credentialsData = launchRequest.getCredentialsData();
  if (credentialsData == null) {
    return false;  // or true if you allow anonymous users to join.
  }

  // The request comes from a mobile device, e.g. checking user match.
  if (credentialsData.getCredentialsType().equals(CredentialsData.CREDENTIALS_TYPE_ANDROID)) {
    return myCheckMobileCredentialsAllowed(credentialsData.getCredentials());
  }

  // Unrecognized credentials type.
  return false;
}

بعد ذلك، اضبطه في ReceiverOptionsProvider:

Kotlin
class MyReceiverOptionsProvider : ReceiverOptionsProvider {
  override fun getOptions(context: Context?): CastReceiverOptions {
    return CastReceiverOptions.Builder(context)
        ...
        .setLaunchRequestChecker(MyLaunchRequestChecker())
        .build()
  }
}
Java
public class MyReceiverOptionsProvider implements ReceiverOptionsProvider {
  @Override
  public CastReceiverOptions getOptions(Context context) {
    return new CastReceiverOptions.Builder(context)
        ...
        .setLaunchRequestChecker(new MyLaunchRequestChecker())
        .build();
  }
}

يؤدي حلّ المشكلة true في LaunchRequestChecker إلى تشغيل تطبيق ATV وfalse لتشغيل تطبيق Web Receiver.

إرسال الرسائل المخصّصة واستلامها

يتيح لك بروتوكول Cast إرسال رسائل سلاسل مخصّصة بين المُرسِلين و تطبيق المُستلِم. يجب تسجيل مساحة اسم (قناة) لإرسال الرسائل إليها قبل بدء استخدام CastReceiverContext.

Android TV: تحديد مساحة اسم مخصّصة

عليك تحديد مساحات الأسماء المتوافقة فيملف CastReceiverOptions أثناء الإعداد:

Kotlin
class MyReceiverOptionsProvider : ReceiverOptionsProvider {
  override fun getOptions(context: Context?): CastReceiverOptions {
    return CastReceiverOptions.Builder(context)
        .setCustomNamespaces(
            Arrays.asList("urn:x-cast:com.example.cast.mynamespace")
        )
        .build()
  }
}
Java
public class MyReceiverOptionsProvider implements ReceiverOptionsProvider {
  @Override
  public CastReceiverOptions getOptions(Context context) {
    return new CastReceiverOptions.Builder(context)
        .setCustomNamespaces(
              Arrays.asList("urn:x-cast:com.example.cast.mynamespace"))
        .build();
  }
}

Android TV: إرسال الرسائل

Kotlin
// If senderId is null, then the message is broadcasted to all senders.
CastReceiverContext.getInstance().sendMessage(
    "urn:x-cast:com.example.cast.mynamespace", senderId, customString)
Java
// If senderId is null, then the message is broadcasted to all senders.
CastReceiverContext.getInstance().sendMessage(
    "urn:x-cast:com.example.cast.mynamespace", senderId, customString);

‫Android TV: تلقّي رسائل نطاق اسم مخصّص

Kotlin
class MyCustomMessageListener : MessageReceivedListener {
    override fun onMessageReceived(
        namespace: String, senderId: String?, message: String ) {
        ...
    }
}

CastReceiverContext.getInstance().setMessageReceivedListener(
    "urn:x-cast:com.example.cast.mynamespace", new MyCustomMessageListener());
Java
class MyCustomMessageListener implements CastReceiverContext.MessageReceivedListener {
  @Override
  public void onMessageReceived(
      String namespace, String senderId, String message) {
    ...
  }
}

CastReceiverContext.getInstance().setMessageReceivedListener(
    "urn:x-cast:com.example.cast.mynamespace", new MyCustomMessageListener());