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

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

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

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

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

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

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

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

iOS

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

     platform: ios, '16'
   
     def target_pods
        pod 'google-cast-sdk', '~>4.8.6'
     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());

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

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

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 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 และใช้ Content ID หรือ URL ของเนื้อหาในข้อมูลสื่อ หรือใช้ข้อมูลคำขอโหลดสื่อที่มีรายละเอียดมากขึ้น คุณต้องเพิ่มตัวกรอง Intent ที่กำหนดไว้ล่วงหน้าต่อไปนี้ในแอป Android TV

<activity android:name="com.example.activity">
  <intent-filter>
     <action android:name="com.google.android.gms.cast.tv.action.LOAD"/>
     <category android:name="android.intent.category.DEFAULT" />
  </intent-filter>
</activity>

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

Android

Kotlin

val mediaToLoad = MediaInfo.Builder("some-id").build()
val loadRequest = MediaLoadRequestData.Builder()
    .setMediaInfo(mediaToLoad)
    .setCredentials("user-credentials")
    ...
    .build()
remoteMediaClient.load(loadRequest)

Java

MediaInfo mediaToLoad =
    new MediaInfo.Builder("some-id").build();
MediaLoadRequestData loadRequest =
    new MediaLoadRequestData.Builder()
        .setMediaInfo(mediaToLoad)
        .setCredentials("user-credentials")
        ...
        .build();
remoteMediaClient.load(loadRequest);

iOS

let mediaInfoBuilder = GCKMediaInformationBuilder(contentId: "some-id")
...
mediaInformation = mediaInfoBuilder.build()

let mediaLoadRequestDataBuilder = GCKMediaLoadRequestDataBuilder()
mediaLoadRequestDataBuilder.mediaInformation = mediaInformation
mediaLoadRequestDataBuilder.credentials = "user-credentials"
...
let mediaLoadRequestData = mediaLoadRequestDataBuilder.build()

remoteMediaClient?.loadMedia(with: mediaLoadRequestData)

เว็บ

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

let mediaInfo = new chrome.cast.media.MediaInfo('some-id"', 'video/mp4');
...

let request = new chrome.cast.media.LoadRequest(mediaInfo);
...

cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request);

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

ในกิจกรรม คุณต้องจัดการ Intent ใน 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() คุณต้องลบล้างเมธอดนี้เพื่อจัดการคำขอโหลด ต้องลงทะเบียน 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);
}

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

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

คำสั่ง Cast บางคำสั่งไม่พร้อมใช้งานในภาษาMediaSession เช่น skipAd() หรือ setActiveMediaTracks() นอกจากนี้ คุณต้องใช้คำสั่งคิวบางคำสั่งที่นี่เนื่องจากคิว Cast ไม่สามารถใช้งานร่วมกับคิว MediaSession ได้อย่างสมบูรณ์

Kotlin

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

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

Java

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

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

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

เช่นเดียวกับตัวรับ Cast แอป Android TV ควรระบุคำสั่งที่รองรับ เพื่อให้ผู้ส่งเปิดหรือปิดใช้ตัวควบคุม UI บางอย่างได้ สำหรับคำสั่งที่เป็นส่วนหนึ่งของ MediaSession ให้ระบุคำสั่งใน PlaybackStateCompat คุณควรระบุคำสั่งเพิ่มเติมใน MediaStatusModifier

Kotlin

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

mediaSession.setPlaybackState(playbackState)

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

Java

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

mediaSession.setPlaybackState(playbackState);

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

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

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

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

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