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

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

ضبط المكتبات

لإتاحة واجهات برمجة تطبيقات 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:23.0.0'
  }
    • بالنسبة إلى تطبيق المُرسِل على Android: 
        dependencies {
    implementation 'com.google.android.gms:play-services-cast:21.1.1'
    implementation 'com.google.android.gms:play-services-cast-framework:23.0.0'
  }
    تأكَّد من تعديل رقم الإصدار هذا في كل مرة يتم فيها تعديل الخدمات.
  4. احفظ التغييرات وانقر على Sync Project with Gradle Files في شريط الأدوات.
iOS
  1. تأكَّد من أنّ تطبيقك Podfile يستهدف الإصدار 4.8.6 من google-cast-sdk أو إصدارًا أحدث
  2. استهداف الإصدار 16 من نظام التشغيل iOS أو الإصدارات الأحدث يُرجى الاطّلاع على ملاحظات الإصدار لمزيد من التفاصيل. 
      platform: ios, '16'

  def target_pods
     pod 'google-cast-sdk', '~>4.8.6'
  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 رقم تعريف المحتوى
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 للتفاعل مع Cast أثناء تشغيل تطبيق البث التلفزيوني. يتيح هذا العنصر لتطبيق التلفزيون قبول رسائل وسائط Cast الواردة من أي مُرسِلين متصلين.

إعداد Android TV

إضافة فلتر intent للإطلاق

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

<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

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

تم ضبط العلامة 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);

إعداد Cast Developer 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 في معلومات الوسائط لطلب التحميل:

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

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

جارٍ ضبط بيانات اعتماد Apple TV على جهاز المُرسِل

من الممكن أن يتيح تطبيق 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 للمحتوى في معلومات الوسائط أو تستخدم بيانات طلب تحميل الوسائط الأكثر تفصيلاً، عليك إضافة intent filter المحدّد مسبقًا التالي في تطبيق 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() في Activity أو Application).

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 لطلبات التحميل).

إتاحة الطلبات المتعلقة بالوسائط

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

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

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

إتاحة طلبات التحكّم في Cast

هناك بعض طلبات Cast غير متاحة في MediaSession، مثل skipAd() أو setActiveMediaTracks(). بالإضافة إلى ذلك، يجب تنفيذ بعض أوامر قائمة المحتوى التالي هنا لأنّ قائمة المحتوى التالي في Cast غير متوافقة بالكامل مع قائمة المحتوى التالي في 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.

لإنشاء إعلان وبثّه 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) لتطبيق Web Receiver، إذا أردت إجراء بعض اللمسات الأخيرة قبل الإرسال، يمكنك تحديد 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 لمستخدمين معيّنين فقط ببدء جلسة التطبيق أو الانضمام إليها. على سبيل المثال، يمكنك السماح للمُرسِل ببدء الاجتماع أو الانضمام إليه فقط في الحالات التالية:

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

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

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

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

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

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

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

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

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

Android

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

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

يتطلّب الإصدار v4.8.6 من 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);

تنفيذ أداة التحقّق من طلبات تشغيل Android TV

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

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

إذا تم السماح بالطلب، يتم تشغيل تطبيق Android TV. يمكنك تخصيص هذا السلوك حسب ما إذا كان تطبيقك يتيح إرسال طلبات التحميل عندما لا يكون المستخدم مسجِّلاً الدخول إلى تطبيق 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());
السابق
نظرة عامة
التالي
الأغاني