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

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

หมายเหตุ: เราขอแนะนําให้คุณลองทําสิ่งต่อไปนี้

• บทแนะนํา Codelab ของ Android TV - ดูวิธีสร้างแอปเครื่องรับ Android TV ที่พร้อมใช้งาน Cast แบบทีละขั้นตอนโดยใช้ Google Cast SDK ที่รับการแคสต์วิดีโอได้
• แอปตัวอย่างของ CastAndroidTvReceiver (GitHub) - เรียกใช้ ไปยังส่วนต่างๆ และดูตัวอย่างแอปข้อมูลอ้างอิงนี้ ซึ่งเป็นไปตามหลักเกณฑ์ของ UX และรายการตรวจสอบการออกแบบ
• แอปตัวอย่างผู้ส่ง VideoCast (GitHub) - ทดสอบโดยใช้แอปอ้างอิงของผู้ส่งที่พร้อมใช้งาน Cast Connect

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

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

แอนดรอยด์

1. เปิดไฟล์ build.gradle ภายในไดเรกทอรีโมดูลแอปพลิเคชันของคุณ
   หมายเหตุ: โปรเจ็กต์ Android Studio มีไฟล์ build.gradle ระดับบนสุดและไฟล์ build.gradle สําหรับแต่ละโมดูล อย่าลืมแก้ไขไฟล์ของโมดูลแอปพลิเคชัน โปรดดู การสร้างโปรเจ็กต์ด้วย Gradle สําหรับข้อมูลเพิ่มเติมเกี่ยวกับ Gradle
2. ยืนยันว่า google() รวมอยู่ใน repositories ที่ระบุ

     repositories {
       google()
     }

3. เพิ่มเวอร์ชันล่าสุดของไลบรารีลงในทรัพยากร Dependency ทั้งนี้ขึ้นอยู่กับประเภทอุปกรณ์เป้าหมายของแอป
   • สําหรับแอป Android Receiver:

       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

       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 จะใช้เซสชันสื่อ เพื่อส่งสัญญาณเมื่อได้รับข้อความจากผู้ส่งบางราย เช่น หยุดชั่วคราว

สําหรับข้อมูลเพิ่มเติมเกี่ยวกับเซสชันสื่อและวิธีเริ่มต้นเซสชันสื่อ โปรดดูคําแนะนําสําหรับการใช้งานเซสชันสื่อ

วงจรเซสชันสื่อ

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

กําลังอัปเดตสถานะเซสชัน

หมายเหตุ: หากคุณใช้ Exoplayer โปรดดูการใช้ Exoplayer กับ Cast Connect เพื่อดูวิธีอัปเดตเซสชันสื่อโดยอัตโนมัติ

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

MediaMetadataCompat

ช่องข้อมูลเมตา	คำอธิบาย
METADATA_KEY_TITLE (จําเป็น)	ชื่อสื่อ
ข้อมูลเมตาETA_DISPLAY_SUBTITLE	คําบรรยาย
ข้อมูลเมตาเมตา_คีย์_ดิสเพลย์	URL ของไอคอน
METADATA_KEY_DURATION (ต้องระบุ)	ระยะเวลาของสื่อ
ข้อมูลเมตา_สื่อ	Content ID
ข้อมูลเมตาเมตาดาต้า	ศิลปิน
ข้อมูลเมตา_อัลบั้ม	อัลบั้ม

playStateCompat

วิธีการที่จําเป็น	คำอธิบาย
setActions()	ตั้งค่าคําสั่งสื่อที่รองรับ
setState()	ตั้งค่าสถานะการเล่นและตําแหน่งปัจจุบัน

MediaSessionCompat

วิธีการที่จําเป็น	คำอธิบาย
setRepeatMode()	ตั้งโหมดเล่นซ้ํา
setShuffleMode()	ตั้งค่าโหมดสุ่มเพลง
setMetadata()	ตั้งค่าข้อมูลเมตาของสื่อ
setPlayState()	ตั้งค่าสถานะการเล่น

โคตลิน

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

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

การเพิ่มตัวกรองจุดประสงค์การเปิดตัว

เพิ่มตัวกรอง Intent ใหม่ไปยังกิจกรรมที่ต้องการจัดการ 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();
  }
}

หมายเหตุ: หากคุณไม่ได้ตั้งค่า setStatusText ระบบจะดึงค่าจาก android:label ในไฟล์ Manifest ของ Android TV โดยอัตโนมัติ

จากนั้นระบุผู้ให้บริการตัวเลือกใน 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 เนื่องจากการเล่นที่ไม่ทํางาน คุณควรตั้งค่าโทเค็นว่างบน 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 เป็นจริง

แอนดรอยด์

ต้องใช้ 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 เพื่อเชื่อมโยงกับรหัสแอป Cast

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

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

หมายเหตุ: อุปกรณ์ Android TV (ATV) มีหมายเลขซีเรียลหลายหมายเลขเชื่อมโยงกัน คุณต้องใช้หมายเลขซีเรียลของซอฟต์แวร์ ATV (Cast) ดูการระบุหมายเลขซีเรียลของอุปกรณ์ ATV สําหรับรายละเอียดเกี่ยวกับวิธีค้นหาหมายเลขซีเรียล

หากไม่ลงทะเบียน Cast Connect จะทํางานเฉพาะแอปที่ติดตั้งจาก Google Play สโตร์ด้วยสาเหตุด้านความปลอดภัย

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

กําลังโหลดสื่อ

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

แอนดรอยด์

โคตลิน

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

หากมีการเปิดตัวแอปตัวรับสัญญาณบนเว็บ แอปจะใช้ 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()

แอนดรอยด์

โคตลิน

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 ตรวจพบว่าเป็นความตั้งใจการโหลด ฟังก์ชันดังกล่าวจะดึงออบเจ็กต์ 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

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

การแก้ไข MediaStatus

แอป 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 ระบุเสมอ

หมายเหตุ: คุณจะต้องโทรหา broadcastMediaStatus() เมื่อเปลี่ยนหรืออัปเดต MediaStatusModifier แล้วเท่านั้น ระบบจะเผยแพร่การเปลี่ยนแปลง MediaSession โดยอัตโนมัติ

สกัดกั้น MediaStatus ก่อนส่ง

เช่นเดียวกับใน Web Receiver SDK หากคุณต้องการปรับแต่งขั้นสุดท้ายก่อนที่จะส่ง คุณอาจระบุ 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 จะกลับไปใช้การเปิดตัวเครื่องรับเว็บของคุณ

ข้อมูลเข้าสู่ระบบการเปิดแอปของผู้ส่ง

ทางด้านผู้ส่ง คุณสามารถระบุ CredentialsData เพื่อเป็นตัวแทนของคนที่เข้าร่วมเซสชัน

credentials คือสตริงที่ผู้ใช้กําหนดได้ ตราบใดที่แอป ATV เข้าใจได้ credentialsType จะกําหนดแพลตฟอร์มที่ CredentialsData มา หรืออาจเป็นค่าที่กําหนดเองก็ได้ โดยค่าเริ่มต้น จะมีการตั้งค่าเป็น แพลตฟอร์มที่ส่ง

ระบบจะส่ง CredentialsData ไปยังแอป Android TV ของคุณระหว่างเวลาเริ่มหรือเข้าร่วมเท่านั้น หากคุณตั้งค่าอีกครั้งขณะเชื่อมต่อ ระบบจะไม่ส่งแอป Android TV ของคุณ หากผู้ส่งเปลี่ยนโปรไฟล์ขณะเชื่อมต่อ คุณอาจอยู่ในเซสชันหรือโทร SessionManager.endCurrentCastSession(boolean stopCasting) หากคิดว่าโปรไฟล์ใหม่ใช้งานร่วมกับเซสชันนี้ไม่ได้

ซึ่ง CredentialsData สามารถดึงผู้ส่งแต่ละรายได้โดยใช้ getSenders ใน CastReceiverContext เพื่อโหลดSenderInfo getCastLaunchRequest() เพื่อรับ CastLaunchRequest และจากนั้น getCredentialsData()

แอนดรอยด์

ต้องใช้ 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 จะเป็นแอปตัวรับสัญญาณเว็บของคุณ

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

โปรโตคอลแคสต์ช่วยให้คุณส่งข้อความสตริงที่กําหนดเองระหว่างผู้ส่งและแอปพลิเคชัน ผู้รับได้ คุณต้องลงทะเบียนเนมสเปซ (ช่อง) เพื่อส่งข้อความก่อนที่จะเริ่มต้น 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();
  }
}

หมายเหตุ: เนมสเปซ ต้อง ขึ้นต้นด้วย urn:x-cast: นําหน้า

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 - รับข้อความ Namespace ที่กําหนดเอง

โคตลิน

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