เพิ่มฟีเจอร์หลักในตัวรับสัญญาณ 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.0.0'
          implementation 'com.google.android.gms:play-services-cast:21.3.0'
        }
    • สำหรับแอป Android Sender:
        dependencies {
          implementation 'com.google.android.gms:play-services-cast:21.0.0'
          implementation 'com.google.android.gms:play-services-cast-framework:21.3.0'
        }
    อย่าลืมอัปเดตหมายเลขเวอร์ชันนี้ทุกครั้งที่อัปเดตบริการ
  4. บันทึกการเปลี่ยนแปลงและคลิก Sync Project with Gradle Files ในแถบเครื่องมือ
iOS
  1. ตรวจสอบว่า Podfile กำหนดเป้าหมายเป็น google-cast-sdk 4.8.0 ขึ้นไป
  2. กําหนดเป้าหมายเป็น iOS 13 ขึ้นไป ดูรายละเอียดเพิ่มเติมได้ที่บันทึกประจำรุ่น
      platform: ios, '13'
    
      def target_pods
         pod 'google-cast-sdk', '~>4.8.0'
      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() ตั้งสถานะการเล่น
โกตลิน
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() หยุดสื่อปัจจุบัน
โกตลิน
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

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

โกตลิน
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เมื่อสร้างแอป ดังนี้

โกตลิน
override fun onCreate() {
  CastReceiverContext.initInstance(this)

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

  ...
}

เริ่มต้น CastReceiverContext เมื่อแอปย้ายไปอยู่เบื้องหน้า

โกตลิน
CastReceiverContext.getInstance().start()
Java
CastReceiverContext.getInstance().start();

โทร stop() ใน CastReceiverContext หลังจากที่แอปเข้าสู่พื้นหลังสำหรับแอปวิดีโอหรือแอปที่ไม่รองรับ การเล่นขณะล็อกหน้าจอหรือขณะใช้แอปอื่น

โกตลิน
// Player has stopped.
CastReceiverContext.getInstance().stop()
Java
// Player has stopped.
CastReceiverContext.getInstance().stop();

นอกจากนี้ หากแอปของคุณรองรับการเล่นขณะล็อกหน้าจอหรือขณะใช้แอปอื่น ให้โทรหา stop() ที่ CastReceiverContext เมื่อแอปหยุดเล่นขณะเล่นอยู่เบื้องหลัง

เราขอแนะนำให้คุณใช้ LifecycleObserver จากไลบรารี androidx.lifecycle เพื่อจัดการการโทร CastReceiverContext.start() และ CastReceiverContext.stop() โดยเฉพาะอย่างยิ่งหากแอปที่มาพร้อมเครื่องของคุณมีหลายกิจกรรม การดำเนินการนี้จะทำให้หลีกเลี่ยงเงื่อนไขเชื้อชาติเมื่อคุณเรียกใช้ start() และ stop() จากกิจกรรมที่แตกต่างกัน

โกตลิน
// 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 ด้วย เพื่อให้ทราบว่าควรส่งคำสั่งและเรียกข้อมูลสถานะการเล่นสื่อที่ไหน

โกตลิน
val mediaManager: MediaManager = receiverContext.getMediaManager()
mediaManager.setSessionCompatToken(currentMediaSession.getSessionToken())
Java
MediaManager mediaManager = receiverContext.getMediaManager();
mediaManager.setSessionCompatToken(currentMediaSession.getSessionToken());

เมื่อปล่อย MediaSession เนื่องจากไม่มีการใช้งานการเล่น คุณควรตั้งค่าโทเค็น Null ใน MediaManager ดังนี้

โกตลิน
myPlayer.stop()
mediaSession.release()
mediaManager.setSessionCompatToken(null)
Java
myPlayer.stop();
mediaSession.release();
mediaManager.setSessionCompatToken(null);

หากแอปรองรับการเล่นสื่อขณะที่แอปอยู่ในเบื้องหลัง แทนที่จะเรียกใช้ CastReceiverContext.stop() เมื่อมีการส่งแอปไปยังเบื้องหลัง คุณควรเรียกใช้แอปเฉพาะเมื่อแอปอยู่ในเบื้องหลังและไม่เล่นสื่ออีกต่อไป เช่น

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

โกตลิน
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) ดังนี้

โกตลิน
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 เพื่อเชื่อมโยงแอปกับรหัสแอปแคสต์

ลงทะเบียนอุปกรณ์ของนักพัฒนาซอฟต์แวร์

ลงทะเบียนหมายเลขซีเรียลของอุปกรณ์ Android TV ที่คุณจะใช้สำหรับการพัฒนาในคอนโซลของนักพัฒนาซอฟต์แวร์ Cast

หากไม่ลงทะเบียน 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 ในข้อมูลสื่อสำหรับคำขอโหลด ดังนี้

โกตลิน
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 byentity คุณสามารถสร้างคำขอโหลดพร้อมข้อมูลเนื้อหาและเรียก 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 ในโค้ดเรียกกลับในวงจรกิจกรรม ดังนี้

โกตลิน
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() ของกิจกรรมหรือแอปพลิเคชัน)

โกตลิน
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);
}

หากต้องการประมวลผลความตั้งใจในการโหลด คุณสามารถแยกวิเคราะห์ Intent ลงในโครงสร้างข้อมูลที่เรากำหนด (MediaLoadRequestData สำหรับคำขอโหลด)

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

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

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

โกตลิน
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() และต้องใช้คำสั่งคิวบางอย่างที่นี่เนื่องจากคิวแคสต์ทำงานร่วมกับคิว MediaSession ได้ไม่สมบูรณ์

โกตลิน
class MyMediaCommandCallback : MediaCommandCallback() {
    override fun onSkipAd(requestData: RequestData?): Task {
        // 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 ควรระบุว่ารองรับคำสั่งใดบ้าง เช่นเดียวกับอุปกรณ์รับการแคสต์ เพื่อให้ผู้ส่งเปิดหรือปิดใช้การควบคุม UI บางอย่างได้ สำหรับคำสั่งที่เป็นส่วนหนึ่งของ MediaSession ให้ระบุคำสั่งใน PlaybackStateCompat ควรระบุคำสั่งเพิ่มเติมใน MediaStatusModifier

โกตลิน
// 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 รองรับ คุณควรตั้งค่าการดำเนินการที่รองรับในแต่ละแพลตฟอร์มอย่างถูกต้องและตรวจสอบว่าแอปผู้ส่งแสดง UI อย่างถูกต้อง

การแก้ไขสถานะสื่อ

หากต้องการรองรับฟีเจอร์ขั้นสูง เช่น แทร็ก โฆษณา การถ่ายทอดสด และการจัดคิว แอป Android TV ต้องให้ข้อมูลเพิ่มเติมที่ยืนยันไม่ได้ผ่าน MediaSession

เรามีชั้นเรียน MediaStatusModifier ที่จะช่วยให้คุณบรรลุเป้าหมายนี้ได้ MediaStatusModifier จะดำเนินการกับ MediaSession ที่คุณตั้งค่าไว้ใน CastReceiverContext เสมอ

หากต้องการสร้างและเผยแพร่ MediaStatus ให้ทำดังนี้

โกตลิน
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 ก่อนที่จะส่งออกมา

โกตลิน
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 ขึ้นไป

โกตลิน
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.0 ขึ้นไป

เรียกใช้ได้ทุกเมื่อหลังจากตั้งค่าตัวเลือกแล้ว: 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ได้ เพื่ออนุญาตหรือปฏิเสธคำขอนี้

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

หากคำขอได้รับอนุญาต แอป ATV จะเปิดขึ้น คุณปรับแต่งลักษณะการทำงานนี้ได้โดยขึ้นอยู่กับว่าแอปรองรับการส่งคำขอโหลดเมื่อผู้ใช้ไม่ได้เข้าสู่ระบบแอป ATV หรือมีผู้ใช้ที่ไม่ตรงกันหรือไม่ ลักษณะการทำงานนี้ปรับแต่งได้อย่างเต็มที่ใน LaunchRequestChecker

สร้างคลาสที่ใช้อินเทอร์เฟซ CastReceiverOptions.LaunchRequestChecker

โกตลิน
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:

โกตลิน
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 ของคุณ

การส่งและรับข้อความที่กำหนดเอง

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

Android TV - ระบุเนมสเปซที่กำหนดเอง

คุณต้องระบุเนมสเปซที่รองรับใน CastReceiverOptions ระหว่างการตั้งค่าดังนี้

โกตลิน
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 - การส่งข้อความ

โกตลิน
// 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 - รับข้อความเนมสเปซที่กำหนดเอง

โกตลิน
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());