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

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

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

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

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

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

Android

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

     repositories {
       google()
     }

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

       dependencies {
         implementation 'com.google.android.gms:play-services-cast-tv:21.1.0'
         implementation 'com.google.android.gms:play-services-cast:21.5.0'
       }

   • สำหรับแอปผู้ส่ง Android:

       dependencies {
         implementation 'com.google.android.gms:play-services-cast:21.1.0'
         implementation 'com.google.android.gms:play-services-cast-framework:21.5.0'
       }

   โปรดอัปเดตหมายเลขเวอร์ชันนี้ทุกครั้งที่อัปเดตบริการ
4. บันทึกการเปลี่ยนแปลงแล้วคลิก Sync Project with Gradle Files ในแถบเครื่องมือ

iOS

1. ตรวจสอบว่า Podfile กําหนดเป้าหมายเป็น google-cast-sdk 4.8.1 ขึ้นไป
2. กําหนดเป้าหมายเป็น iOS 14 ขึ้นไป ดูรายละเอียดเพิ่มเติมได้ที่บันทึกประจำรุ่น

     platform: ios, '14'
   
     def target_pods
        pod 'google-cast-sdk', '~>4.8.1'
     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);
}

การควบคุมการขนส่งที่ดำเนินการอยู่

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

MediaSessionCompat.Callback

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

Kotlin

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

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

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

mediaSession.setCallback( MyMediaSessionCallback() );

Java

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

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

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

mediaSession.setCallback(new MyMediaSessionCallback());

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

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

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

Android

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

แฟล็ก androidReceiverCompatible ได้รับการตั้งค่าใน LaunchOptions (ซึ่งเป็นส่วนหนึ่งของ CastOptions) ดังนี้

Kotlin

class CastOptionsProvider : OptionsProvider {
  override fun getCastOptions(context: Context?): CastOptions {
    val launchOptions: LaunchOptions = Builder()
          .setAndroidReceiverCompatible(true)
          .build()
    return CastOptions.Builder()
          .setLaunchOptions(launchOptions)
          ...
          .build()
    }
}

Java

public class CastOptionsProvider implements OptionsProvider {
  @Override
  public CastOptions getCastOptions(Context context) {
    LaunchOptions launchOptions = new LaunchOptions.Builder()
              .setAndroidReceiverCompatible(true)
              .build();
    return new CastOptions.Builder()
        .setLaunchOptions(launchOptions)
        ...
        .build();
  }
}

iOS

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

แฟล็ก androidReceiverCompatible ได้รับการตั้งค่าใน GCKLaunchOptions (ซึ่งเป็นส่วนหนึ่งของ GCKCastOptions) ดังนี้

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

เว็บ

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

const context = cast.framework.CastContext.getInstance();
const castOptions = new cast.framework.CastOptions();
castOptions.receiverApplicationId = kReceiverAppID;
castOptions.androidReceiverCompatible = true;
context.setOptions(castOptions);

การตั้งค่า Cast Developer Console

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

เพิ่มชื่อแพ็กเกจของแอป Android TV ในคอนโซลของนักพัฒนาซอฟต์แวร์ Cast เพื่อเชื่อมโยงกับรหัสแอป Cast

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

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

หมายเหตุ: อุปกรณ์ 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 และชื่อแพ็กเกจที่คุณกำหนดใน 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);

หากเปิดแอปตัวรับเว็บแล้ว แอปจะใช้ 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() ได้ ซึ่งคล้ายกับ load byentity

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 เป็นการโหลด ระบบจะดึงออบเจ็กต์ MediaLoadRequestData ออกจาก Intent และเรียกใช้ MediaLoadCommandCallback.onLoad() คุณต้องลบล้างเมธอดนี้เพื่อจัดการคำขอโหลด คุณต้องลงทะเบียน Callback ก่อนที่จะเรียกใช้ 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);
}

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

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

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

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

การรองรับคำสั่งควบคุมการแคสต์

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

Kotlin

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

Kotlin

// Set media session supported commands
val playbackState: PlaybackStateCompat = PlaybackStateCompat.Builder()
    .setActions(PlaybackStateCompat.ACTION_PLAY or PlaybackStateCompat.ACTION_PAUSE)
    .setState(PlaybackStateCompat.STATE_PLAYING)
    .build()

mediaSession.setPlaybackState(playbackState)

// Set additional commands in MediaStatusModifier
val mediaManager = CastReceiverContext.getInstance().getMediaManager()
mediaManager.getMediaStatusModifier()
    .setMediaCommandSupported(MediaStatus.COMMAND_QUEUE_NEXT)

Java

// Set media session supported commands
PlaybackStateCompat playbackState =
    new PlaybackStateCompat.Builder()
        .setActions(PlaybackStateCompat.ACTION_PLAY | PlaybackStateCompat.ACTION_PAUSE)
        .setState(PlaybackStateCompat.STATE_PLAYING)
        .build();

mediaSession.setPlaybackState(playbackState);

// Set additional commands in MediaStatusModifier
MediaManager mediaManager = CastReceiverContext.getInstance().getMediaManager();
mediaManager.getMediaStatusModifier()
            .setMediaCommandSupported(MediaStatus.COMMAND_QUEUE_NEXT);

ซ่อนปุ่มที่ไม่รองรับ

หากแอป Android TV รองรับเฉพาะการควบคุมสื่อขั้นพื้นฐานแต่แอป Web Receiver รองรับการควบคุมขั้นสูงกว่า คุณควรตรวจสอบว่าแอปผู้ส่งทำงานได้อย่างถูกต้องเมื่อแคสต์ไปยังแอป Android TV เช่น หากแอป Android TV ไม่รองรับการเปลี่ยนแปลงอัตราการเล่นแต่แอป Web Receiver รองรับ คุณควรตั้งค่าการดำเนินการที่รองรับให้ถูกต้องในแต่ละแพลตฟอร์มและตรวจสอบว่าแอปผู้ส่งแสดง UI ได้อย่างถูกต้อง

การแก้ไข MediaStatus

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

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

วิธีสร้างและเผยแพร่ MediaStatus:

Kotlin

val mediaManager: MediaManager = castReceiverContext.getMediaManager()
val statusModifier: MediaStatusModifier = mediaManager.getMediaStatusModifier()

statusModifier
    .setLiveSeekableRange(seekableRange)
    .setAdBreakStatus(adBreakStatus)
    .setCustomData(customData)

mediaManager.broadcastMediaStatus()

Java

MediaManager mediaManager = castReceiverContext.getMediaManager();
MediaStatusModifier statusModifier = mediaManager.getMediaStatusModifier();

statusModifier
    .setLiveSeekableRange(seekableRange)
    .setAdBreakStatus(adBreakStatus)
    .setCustomData(customData);

mediaManager.broadcastMediaStatus();

ไลบรารีของไคลเอ็นต์ของเราจะได้รับ MediaStatus พื้นฐานจาก MediaSession แอป Android TV ของคุณจะระบุสถานะเพิ่มเติมและสถานะการลบล้างผ่านตัวปรับแต่ง MediaStatus ได้

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

หมายเหตุ: คุณต้องโทรหา 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.1 ขึ้นไป

คุณจะโทรหาได้ทุกเมื่อหลังจากตั้งค่าตัวเลือกแล้ว: 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());