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

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

หมายเหตุ: เราขอแนะนำให้ลองทำตามขั้นตอนต่อไปนี้

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

การกำหนดค่าคลัง

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

Android

1. เปิดไฟล์ build.gradle ในไดเรกทอรีโมดูลแอปพลิเคชัน
   หมายเหตุ: โปรเจ็กต์ Android Studio มีไฟล์ build.gradle ระดับบนสุดและไฟล์ build.gradle สำหรับแต่ละโมดูล อย่าลืมแก้ไขไฟล์สําหรับโมดูลแอปพลิเคชัน ดูข้อมูลเพิ่มเติมเกี่ยวกับ Gradle ได้ที่หัวข้อการสร้างโปรเจ็กต์ด้วย 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 ยังใช้เซสชันสื่อของคุณเพื่อส่งสัญญาณเมื่อได้รับข้อความบางอย่างจากผู้ส่ง เช่น ข้อความหยุดชั่วคราว

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

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

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

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

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

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

MediaMetadataCompat

ฟิลด์ข้อมูลเมตา	คำอธิบาย
METADATA_KEY_TITLE (ต้องระบุ)	ชื่อสื่อ
METADATA_KEY_DISPLAY_SUBTITLE	ชื่อรอง
METADATA_KEY_DISPLAY_ICON_URI	URL ของไอคอน
METADATA_KEY_DURATION (ต้องระบุ)	ระยะเวลาของสื่อ
METADATA_KEY_MEDIA_URI	Content ID
METADATA_KEY_ARTIST	ศิลปิน
METADATA_KEY_ALBUM	อัลบั้ม

PlaybackStateCompat

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

MediaSessionCompat

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

Kotlin

private fun updateMediaSession() {
    val metadata = MediaMetadataCompat.Builder()
         .putString(MediaMetadataCompat.METADATA_KEY_TITLE, "title")
         .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "subtitle")
         .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_ICON_URI, mMovie.getCardImageUrl())
         .build()

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

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

Java

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

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

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

การจัดการการควบคุมการนำส่ง

แอปของคุณควรใช้การเรียกกลับการควบคุมการรับส่งเซสชันสื่อ ตารางต่อไปนี้แสดงการดำเนินการควบคุมการขนส่งที่อุปกรณ์ต้องจัดการ

MediaSessionCompat.Callback

การทำงาน	คำอธิบาย
onPlay()	ทำต่อ
onPause()	หยุดชั่วคราว
onSeekTo()	กรอไปยังตำแหน่งที่ต้องการ
onStop()	หยุดสื่อปัจจุบัน

Kotlin

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

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

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

mediaSession.setCallback( MyMediaSessionCallback() );

Java

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

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

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

mediaSession.setCallback(new MyMediaSessionCallback());

การกำหนดค่าการรองรับ Cast

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

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

หมายเหตุ: หากคุณไม่ได้ตั้งค่า 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 เมื่อสร้างแอป

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 แล้ว คุณสามารถประกาศความพร้อมของแอปได้โดยตั้งค่า Flag ของ androidReceiverCompatible ให้เป็นจริง LaunchOptions

Android

ต้องใช้ play-services-cast-framework เวอร์ชัน 19.0.0 ขึ้นไป

การตั้งค่า Flag 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 ขึ้นไป

การตั้งค่า Flag 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);

การตั้งค่าคอนโซลของนักพัฒนาแอปแคสต์

กำหนดค่าแอป Android TV

เพิ่มชื่อแพ็กเกจของแอป Android TV ใน Cast Developer Console เพื่อเชื่อมโยงกับรหัสแอป Cast

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

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

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

หากไม่ได้ลงทะเบียน 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 และชื่อแพ็กเกจที่คุณกําหนดไว้ในคอนโซลนักพัฒนาแอป

การตั้งค่าข้อมูลเข้าสู่ระบบ 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 และใช้รหัสเนื้อหาหรือ 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 ใน Callback ของวงจรกิจกรรมเพื่อจัดการคําขอโหลดเหล่านี้

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

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

หากต้องการประมวลผล Intent การโหลด คุณสามารถแยกวิเคราะห์ Intent ดังกล่าวเป็นโครงสร้างข้อมูลที่เราได้กําหนดไว้ (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

คำสั่ง Cast บางรายการไม่พร้อมใช้งานใน MediaSession เช่น skipAd() หรือ setActiveMediaTracks() นอกจากนี้ ต้องใช้คําสั่งคิวบางรายการที่นี่เนื่องจากคิว Cast ไม่เข้ากันได้กับคิว MediaSession อย่างเต็มรูปแบบ

Kotlin

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

val mediaManager = CastReceiverContext.getInstance().getMediaManager()
mediaManager.setMediaCommandCallback(MyMediaCommandCallback())

Java

public class MyMediaCommandCallback extends MediaCommandCallback {
  @Override
  public Task onSkipAd(RequestData requestData) {
    // Skip your ad
    ...
    return Tasks.forResult(null);
  }
}

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

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

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

วิธีสร้างและออกอากาศ 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 ระบุไว้เสมอ

หมายเหตุ: คุณจะต้องเรียกใช้ broadcastMediaStatus() ก็ต่อเมื่อคุณเปลี่ยนแปลงหรืออัปเดต MediaStatusModifier ระบบจะเผยแพร่การเปลี่ยนแปลงใน 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();
  }
}

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

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