เพิ่มฟีเจอร์หลักในตัวรับสัญญาณ Android TV

หน้านี้มีข้อมูลโค้ดและคำอธิบายฟีเจอร์ที่ใช้ได้สำหรับการปรับแต่งแอปตัวรับสัญญาณ Android TV

การกำหนดค่าไลบรารี

วิธีทำให้ Cast Connect API พร้อมใช้งานในแอป Android TV

Android
  1. เปิดไฟล์ build.gradle ในไดเรกทอรีโมดูลแอปพลิเคชัน
  2. ตรวจสอบว่า google() รวมอยู่ใน repositories ที่ระบุไว้
      repositories {
        google()
      }
  3. เพิ่มไลบรารีเวอร์ชันล่าสุดลงในทรัพยากร Dependency โดยขึ้นอยู่กับประเภทอุปกรณ์เป้าหมายสำหรับแอปของคุณ
    • สำหรับแอปตัวรับสัญญาณ Android ให้ทำดังนี้
        dependencies {
          implementation 'com.google.android.gms:play-services-cast-tv:21.1.1'
          implementation 'com.google.android.gms:play-services-cast:22.1.0'
        }
    • สำหรับแอปผู้ส่ง Android ให้ทำดังนี้
        dependencies {
          implementation 'com.google.android.gms:play-services-cast:21.1.1'
          implementation 'com.google.android.gms:play-services-cast-framework:22.1.0'
        }
    อย่าลืมอัปเดตหมายเลขเวอร์ชันนี้ทุกครั้งที่มีการอัปเดตบริการ
  4. บันทึกการเปลี่ยนแปลง แล้วคลิก Sync Project with Gradle Files ในแถบเครื่องมือ
iOS
  1. ตรวจสอบว่า Podfile กำหนดเป้าหมายเป็น google-cast-sdk 4.8.3 ขึ้นไป
  2. กำหนดเป้าหมายเป็น iOS 14 ขึ้นไป ดูรายละเอียดเพิ่มเติมได้ที่บันทึกประจำรุ่น
      platform: ios, '14'
    
      def target_pods
         pod 'google-cast-sdk', '~>4.8.3'
      end
เว็บ
  1. ต้องใช้เบราว์เซอร์ Chromium เวอร์ชัน M87 ขึ้นไป
  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());

การกำหนดค่าการรองรับการแคสต์

เมื่อแอปพลิเคชันผู้ส่งส่งคำขอเปิดใช้ ระบบจะสร้าง Intent พร้อมเนมสเปซของแอปพลิเคชัน แอปพลิเคชันของคุณมีหน้าที่จัดการและสร้างอินสแตนซ์ของออบเจ็กต์ CastReceiverContext เมื่อเปิดใช้แอป TV ต้องมีCastReceiverContextออบเจ็กต์ เพื่อโต้ตอบกับ Cast ขณะที่แอปทีวีทำงานอยู่ ออบเจ็กต์นี้ช่วยให้แอปพลิเคชันทีวี ยอมรับข้อความสื่อ Cast ที่มาจากผู้ส่งที่เชื่อมต่อได้

การตั้งค่า Android TV

การเพิ่มตัวกรองความตั้งใจในการเปิดตัว

เพิ่มตัวกรอง Intent ใหม่ไปยังกิจกรรมที่คุณต้องการจัดการ 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 เนื่องจากไม่มีการเล่น คุณควรตั้งค่าโทเค็นเป็น null ใน 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

ต้องใช้ google-cast-sdk เวอร์ชัน v4.4.8 ขึ้นไป

ตั้งค่าสถานะ androidReceiverCompatible ใน GCKLaunchOptions (ซึ่งเป็นส่วนหนึ่งของ GCKCastOptions) ดังนี้

let options = GCKCastOptions(discoveryCriteria: GCKDiscoveryCriteria(applicationID: kReceiverAppID))
...
let launchOptions = GCKLaunchOptions()
launchOptions.androidReceiverCompatible = true
options.launchOptions = launchOptions
GCKCastContext.setSharedInstanceWith(options)
เว็บ

ต้องใช้เบราว์เซอร์ Chromium เวอร์ชัน M87 ขึ้นไป

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 Store เท่านั้นเนื่องด้วยเหตุผลด้านความปลอดภัย

ดูข้อมูลเพิ่มเติมเกี่ยวกับการลงทะเบียนอุปกรณ์ Cast หรือ Android TV สำหรับการพัฒนา Cast ได้ที่หน้าลงทะเบียน

กำลังโหลดสื่อ

หากคุณได้ติดตั้งใช้งานการรองรับ Deep Link ในแอป Android TV แล้ว คุณควรมีการกำหนดค่าที่คล้ายกันใน Manifest ของ 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>

โหลดตามเอนทิตีในผู้ส่ง

ในฝั่งผู้ส่ง คุณสามารถส่ง Deep Link ได้โดยการตั้งค่า 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)
เว็บ

ต้องใช้เบราว์เซอร์ Chromium เวอร์ชัน M87 ขึ้นไป

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

ระบบจะส่งคำสั่งโหลดผ่าน Intent พร้อม Deep Link และชื่อแพ็กเกจ ที่คุณกำหนดไว้ใน Developer Console

การตั้งค่าข้อมูลเข้าสู่ระบบ ATV ในผู้ส่ง

เป็นไปได้ที่แอป Web Receiver และแอป Android TV จะรองรับ Deep Link และ credentials ที่แตกต่างกัน (เช่น หากคุณจัดการการตรวจสอบสิทธิ์แตกต่างกันใน 2 แพลตฟอร์ม) หากต้องการแก้ไขปัญหานี้ คุณสามารถระบุ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)
เว็บ

ต้องใช้เบราว์เซอร์ Chromium เวอร์ชัน M87 ขึ้นไป

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 ที่กำหนดไว้ล่วงหน้าต่อไปนี้ใน แอป 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)
เว็บ

ต้องใช้เบราว์เซอร์ Chromium เวอร์ชัน M87 ขึ้นไป

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

การจัดการคำขอโหลด

ในกิจกรรมของคุณ คุณต้องจัดการ Intent เพื่อจัดการคำขอโหลดเหล่านี้ ในการเรียกกลับของวงจรกิจกรรม

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 ตรวจพบว่า Intent เป็น Intent การโหลด ระบบจะดึงออบเจ็กต์ MediaLoadRequestData จาก Intent และเรียกใช้ 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 สำหรับคำขอโหลด)

รองรับคำสั่งสื่อ

รองรับการควบคุมการเล่นขั้นพื้นฐาน

คำสั่งการผสานรวมพื้นฐานรวมถึงคำสั่งที่เข้ากันได้กับเซสชันสื่อ ระบบจะแจ้งคำสั่งเหล่านี้ผ่าน Callback ของเซสชันสื่อ คุณต้อง ลงทะเบียนการเรียกกลับไปยังเซสชันสื่อเพื่อรองรับฟีเจอร์นี้ (คุณอาจทำสิ่งนี้ อยู่แล้ว)

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 บางอย่างไม่พร้อมใช้งานใน 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());

ระบุคำสั่งสื่อที่รองรับ

เช่นเดียวกับตัวรับ Cast แอป Android TV ควรระบุคำสั่งที่รองรับ เพื่อให้ผู้ส่งเปิดหรือปิดใช้การควบคุม UI บางอย่างได้ สำหรับคำสั่งที่เป็นส่วนหนึ่งของ 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 รองรับเฉพาะการควบคุมสื่อขั้นพื้นฐาน แต่แอปตัวรับสัญญาณเว็บรองรับการควบคุมขั้นสูงกว่า คุณควรตรวจสอบว่าแอปผู้ส่งทำงานอย่างถูกต้องเมื่อแคสต์ไปยังแอป Android TV เช่น หากแอป Android TV ไม่รองรับการเปลี่ยนอัตราการเล่น แต่แอปตัวรับสัญญาณเว็บรองรับ คุณควรตั้งค่าการดำเนินการที่รองรับอย่างถูกต้องในแต่ละแพลตฟอร์ม และตรวจสอบว่าแอปผู้ส่งแสดง UI อย่างถูกต้อง

การแก้ไข 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 ก่อนส่งออก

เช่นเดียวกับ Web Receiver 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 คุณสามารถระบุ เครื่องมือตรวจสอบการเปิดตัวเพื่อดูว่าระบบอนุญาตข้อมูลเข้าสู่ระบบของผู้ส่งหรือไม่ หากไม่เป็นเช่นนั้น Cast Connect SDK จะกลับไปเปิดตัว 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

ต้องใช้ google-cast-sdk เวอร์ชัน v4.8.3 ขึ้นไป

เรียกใช้ได้ทุกเมื่อหลังจากตั้งค่าตัวเลือกแล้ว GCKCastContext.setSharedInstanceWith(options).

GCKCastContext.sharedInstance().setLaunch(
    GCKCredentialsData(credentials: "{\"userId\": \"abc\"}")
เว็บ

ต้องใช้เบราว์เซอร์ Chromium เวอร์ชัน M87 ขึ้นไป

เรียกใช้ได้ทุกเมื่อหลังจากตั้งค่าตัวเลือกแล้ว cast.framework.CastContext.getInstance().setOptions(options);.

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

การติดตั้งใช้งานเครื่องมือตรวจสอบคำขอเปิดตัว ATV

ระบบจะส่ง 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());