בדף הזה יש קטעי קוד ותיאורים של התכונות שזמינות להתאמה אישית של אפליקציית מקלט Android TV.
הגדרת ספריות
כדי להפוך את ממשקי ה-API של Cast Connect לזמינים באפליקציית Android TV:
-
פותחים את הקובץ
build.gradle
בתוך ספריית מודול האפליקציה. -
מוודאים ש-
google()
נכלל ברשימה שלrepositories
.repositories { google() }
-
בהתאם לסוג מכשיר היעד של האפליקציה, מוסיפים את הגרסאות האחרונות של הספריות לתלות:
-
באפליקציית Android Receiver:
dependencies { implementation 'com.google.android.gms:play-services-cast-tv:21.1.1' implementation 'com.google.android.gms:play-services-cast:22.1.0' }
-
באפליקציית השולט ל-Android:
dependencies { implementation 'com.google.android.gms:play-services-cast:21.1.1' implementation 'com.google.android.gms:play-services-cast-framework:22.1.0' }
-
באפליקציית Android Receiver:
-
שומרים את השינויים ולוחצים על
Sync Project with Gradle Files
בסרגל הכלים.
-
מוודאים ש-
Podfile
מטרגט ל-google-cast-sdk
4.8.3 או לגרסה מתקדמת יותר -
טרגוט ל-iOS מגרסה 14 ואילך. פרטים נוספים זמינים בהערות המוצר.
platform: ios, '14' def target_pods pod 'google-cast-sdk', '~>4.8.3' end
- נדרשת גרסה M87 ואילך של דפדפן Chromium.
-
הוספה של ספריית Web Sender API לפרויקט
<script src="//www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
דרישות AndroidX
בגרסאות חדשות של Google Play Services, כדי להשתמש במרחב השמות androidx
, צריך לעדכן את האפליקציה. פועלים לפי ההוראות למיגרציה ל-AndroidX.
אפליקציה ל-Android TV – דרישות מוקדמות
כדי לתמוך ב-Cast Connect באפליקציית Android TV, צריך ליצור אירועים ממסגרת זמן של מדיה ולתמוך בהם. הנתונים שמתקבלים מהסשן של המדיה מספקים את המידע הבסיסי – לדוגמה, מיקום, מצב הפעלה וכו' – לגבי סטטוס המדיה. ספריית Cast Connect משתמשת גם בסשן המדיה כדי לסמן מתי היא קיבלה הודעות מסוימות משולח, כמו השהיה.
מידע נוסף על סשן מדיה ועל אופן ההפעלה של סשן מדיה זמין במדריך לעבודה עם סשן מדיה.
מחזור החיים של סשן מדיה
האפליקציה צריכה ליצור סשן מדיה כשההפעלה מתחילה ולשחרר אותו כשאי אפשר יותר לשלוט בהפעלה. לדוגמה, אם האפליקציה היא אפליקציית סרטונים, צריך להפסיק את ההפעלה של הסשן כשהמשתמש יוצא מפעילות ההפעלה – או על ידי בחירה באפשרות 'הקודם' כדי לעיין בתוכן אחר או על ידי העברת האפליקציה לרקע. אם האפליקציה היא אפליקציית מוזיקה, צריך להפסיק את ההפעלה של הסשן כשהאפליקציה לא מפעילה יותר מדיה.
מתבצע עדכון של סטטוס הסשן
הנתונים בסשן המדיה צריכים להיות מעודכנים בהתאם לסטטוס של נגן המדיה. לדוגמה, כשמשהים את ההפעלה, צריך לעדכן גם את מצב ההפעלה וגם את הפעולות הנתמכות. בטבלאות הבאות מפורטים המצבים שאתם אחראים לעדכן.
MediaMetadataCompat
שדה מטא-נתונים | תיאור |
---|---|
METADATA_KEY_TITLE (חובה) | כותרת המדיה. |
METADATA_KEY_DISPLAY_SUBTITLE | כותרת המשנה. |
METADATA_KEY_DISPLAY_ICON_URI | כתובת ה-URL של הסמל. |
METADATA_KEY_DURATION (חובה) | משך המדיה. |
METADATA_KEY_MEDIA_URI | מזהה התוכן. |
METADATA_KEY_ARTIST | האומן. |
METADATA_KEY_ALBUM | האלבום. |
PlaybackStateCompat
שיטה נדרשת | תיאור |
---|---|
setActions() | מגדירה פקודות מדיה נתמכות. |
setState() | מגדירים את מצב ההפעלה ואת המיקום הנוכחי. |
MediaSessionCompat
שיטה נדרשת | תיאור |
---|---|
setRepeatMode() | הגדרת מצב חזרה. |
setShuffleMode() | הגדרת מצב השמעה אקראית. |
setMetadata() | הגדרת מטא-נתונים של מדיה. |
setPlaybackState() | הגדרת מצב ההפעלה. |
private fun updateMediaSession() { val metadata = MediaMetadataCompat.Builder() .putString(MediaMetadataCompat.METADATA_KEY_TITLE, "title") .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "subtitle") .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_ICON_URI, mMovie.getCardImageUrl()) .build() val playbackState = PlaybackStateCompat.Builder() .setState( PlaybackStateCompat.STATE_PLAYING, player.getPosition(), player.getPlaybackSpeed(), System.currentTimeMillis() ) .build() mediaSession.setMetadata(metadata) mediaSession.setPlaybackState(playbackState) }
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() | הפסקת המדיה הנוכחית |
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() );
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
כשבקשת הפעלה נשלחת מאפליקציה ששולחת בקשות, נוצרת כוונה עם מרחב שמות של אפליקציה. האפליקציה שלכם אחראית לטפל בזה וליצור מופע של אובייקט CastReceiverContext
כשמפעילים את אפליקציית הטלוויזיה. נדרש אובייקט CastReceiverContext
כדי לקיים אינטראקציה עם Cast בזמן שאפליקציית הטלוויזיה פועלת. האובייקט הזה מאפשר לאפליקציית הטלוויזיה לקבל הודעות מדיה של Cast מכל השולחים המחוברים.
הגדרת Android TV
הוספת מסנן כוונות להפעלת האפליקציה
מוסיפים מסנן Intent חדש לפעילות שרוצים שתטפל ב-Intent להפעלת האפליקציה מאפליקציית השולח:
<activity android:name="com.example.activity">
<intent-filter>
<action android:name="com.google.android.gms.cast.tv.action.LAUNCH" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
ציון ספק של אפשרויות לנמען
צריך להטמיע את
ReceiverOptionsProvider
כדי לספק את
CastReceiverOptions
:
class MyReceiverOptionsProvider : ReceiverOptionsProvider { override fun getOptions(context: Context?): CastReceiverOptions { return CastReceiverOptions.Builder(context) .setStatusText("My App") .build() } }
public class MyReceiverOptionsProvider implements ReceiverOptionsProvider { @Override public CastReceiverOptions getOptions(Context context) { return new CastReceiverOptions.Builder(context) .setStatusText("My App") .build(); } }
לאחר מכן מציינים את ספק האפשרויות ב-AndroidManifest
:
<meta-data
android:name="com.google.android.gms.cast.tv.RECEIVER_OPTIONS_PROVIDER_CLASS_NAME"
android:value="com.example.mysimpleatvapplication.MyReceiverOptionsProvider" />
המאפיין ReceiverOptionsProvider
משמש להעברת CastReceiverOptions
כשמאתחלים את CastReceiverContext
.
ההקשר של מקלט Cast
מאתחלים את
CastReceiverContext
כשיוצרים את האפליקציה:
override fun onCreate() { CastReceiverContext.initInstance(this) ... }
@Override public void onCreate() { CastReceiverContext.initInstance(this); ... }
הפעלת CastReceiverContext
כשהאפליקציה עוברת לחזית:
CastReceiverContext.getInstance().start()
CastReceiverContext.getInstance().start();
התקשר
stop()
אל
CastReceiverContext
אחרי שהאפליקציה עוברת לרקע באפליקציות של סרטונים או באפליקציות שלא תומכות
בהפעלה ברקע:
// Player has stopped. CastReceiverContext.getInstance().stop()
// Player has stopped. CastReceiverContext.getInstance().stop();
בנוסף, אם האפליקציה תומכת בהפעלה ברקע, צריך להפעיל את stop()
ב-CastReceiverContext
כשההפעלה ברקע נפסקת.
מומלץ מאוד להשתמש ב-LifecycleObserver מהספרייה androidx.lifecycle
כדי לנהל את הקריאה ל-CastReceiverContext.start()
ול-CastReceiverContext.stop()
, במיוחד אם לאפליקציה המקורית יש כמה פעילויות. כך נמנעים מצבי מירוץ כשקוראים ל-start()
ול-stop()
מפעילויות שונות.
// Create a LifecycleObserver class. class MyLifecycleObserver : DefaultLifecycleObserver { override fun onStart(owner: LifecycleOwner) { // App prepares to enter foreground. CastReceiverContext.getInstance().start() } override fun onStop(owner: LifecycleOwner) { // App has moved to the background or has terminated. CastReceiverContext.getInstance().stop() } } // Add the observer when your application is being created. class MyApplication : Application() { fun onCreate() { super.onCreate() // Initialize CastReceiverContext. CastReceiverContext.initInstance(this /* android.content.Context */) // Register LifecycleObserver ProcessLifecycleOwner.get().lifecycle.addObserver( MyLifecycleObserver()) } }
// 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
, צריך גם לספק את הטוקן הנוכחי ל-CastReceiverContext
כדי שהמערכת תדע לאן לשלוח את הפקודות ולאחזר את מצב הפעלת המדיה:MediaSession
val mediaManager: MediaManager = receiverContext.getMediaManager() mediaManager.setSessionCompatToken(currentMediaSession.getSessionToken())
MediaManager mediaManager = receiverContext.getMediaManager(); mediaManager.setSessionCompatToken(currentMediaSession.getSessionToken());
כשמפסיקים את השידור של MediaSession
בגלל חוסר פעילות, צריך להגדיר אסימון null ב-MediaManager
:
myPlayer.stop() mediaSession.release() mediaManager.setSessionCompatToken(null)
myPlayer.stop(); mediaSession.release(); mediaManager.setSessionCompatToken(null);
אם האפליקציה תומכת בהפעלת מדיה כשהיא ברקע, במקום להפעיל את CastReceiverContext.stop()
כשהאפליקציה עוברת לרקע, צריך להפעיל אותה רק כשהאפליקציה ברקע והמדיה לא מופעלת יותר. לדוגמה:
class MyLifecycleObserver : DefaultLifecycleObserver { ... // App has moved to the background. override fun onPause(owner: LifecycleOwner) { mIsBackground = true myStopCastReceiverContextIfNeeded() } } // Stop playback on the player. private fun myStopPlayback() { myPlayer.stop() myStopCastReceiverContextIfNeeded() } // Stop the CastReceiverContext when both the player has // stopped and the app has moved to the background. private fun myStopCastReceiverContextIfNeeded() { if (mIsBackground && myPlayer.isStopped()) { CastReceiverContext.getInstance().stop() } }
public class MyLifecycleObserver implements DefaultLifecycleObserver { ... // App has moved to the background. @Override public void onPause(LifecycleOwner owner) { mIsBackground = true; myStopCastReceiverContextIfNeeded(); } } // Stop playback on the player. private void myStopPlayback() { myPlayer.stop(); myStopCastReceiverContextIfNeeded(); } // Stop the CastReceiverContext when both the player has // stopped and the app has moved to the background. private void myStopCastReceiverContextIfNeeded() { if (mIsBackground && myPlayer.isStopped()) { CastReceiverContext.getInstance().stop(); } }
שימוש ב-ExoPlayer עם Cast Connect
אם אתם משתמשים ב-Exoplayer
, אתם יכולים להשתמש ב-MediaSessionConnector
כדי לשמור באופן אוטומטי את הסשן ואת כל המידע שקשור אליו, כולל מצב ההפעלה, במקום לעקוב אחרי השינויים באופן ידני.
אפשר להשתמש ב-MediaSessionConnector.MediaButtonEventHandler
כדי לטפל באירועים של MediaButton על ידי קריאה ל-setMediaButtonEventHandler(MediaButtonEventHandler)
, שאחרת מטופלים על ידי MediaSessionCompat.Callback
כברירת מחדל.
כדי לשלב את
MediaSessionConnector
באפליקציה, מוסיפים את הקוד הבא למחלקה של פעילות הנגן או למיקום שבו מנהלים את סשן המדיה:
class PlayerActivity : Activity() { private var mMediaSession: MediaSessionCompat? = null private var mMediaSessionConnector: MediaSessionConnector? = null private var mMediaManager: MediaManager? = null override fun onCreate(savedInstanceState: Bundle?) { ... mMediaSession = MediaSessionCompat(this, LOG_TAG) mMediaSessionConnector = MediaSessionConnector(mMediaSession!!) ... } override fun onStart() { ... mMediaManager = receiverContext.getMediaManager() mMediaManager!!.setSessionCompatToken(currentMediaSession.getSessionToken()) mMediaSessionConnector!!.setPlayer(mExoPlayer) mMediaSessionConnector!!.setMediaMetadataProvider(mMediaMetadataProvider) mMediaSession!!.isActive = true ... } override fun onStop() { ... mMediaSessionConnector!!.setPlayer(null) mMediaSession!!.release() mMediaManager!!.setSessionCompatToken(null) ... } }
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
כ-true.
נדרשת גרסה play-services-cast-framework
19.0.0
ומעלה.
הדגל androidReceiverCompatible
מוגדר ב-LaunchOptions
(שהוא חלק מ-CastOptions
):
class CastOptionsProvider : OptionsProvider { override fun getCastOptions(context: Context?): CastOptions { val launchOptions: LaunchOptions = Builder() .setAndroidReceiverCompatible(true) .build() return CastOptions.Builder() .setLaunchOptions(launchOptions) ... .build() } }
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(); } }
נדרשת גרסה 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)
נדרשת גרסה M87
ומעלה של דפדפן Chromium.
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.
מטעמי אבטחה, בלי הרשמה, Cast Connect יפעל רק באפליקציות שהותקנו מחנות Google Play.
מידע נוסף על רישום מכשיר Cast או Android TV לפיתוח Cast זמין בדף הרישום.
המדיה בטעינה
אם כבר הטמעתם תמיכה בקישורי עומק באפליקציית Android TV, אמורה להיות לכם הגדרה דומה במניפסט של 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>
טעינה לפי ישות אצל השולח
בצד השולח, אפשר להעביר את קישור העומק על ידי הגדרת entity
בפרטי המדיה של בקשת הטעינה:
val mediaToLoad = MediaInfo.Builder("some-id") .setEntity("https://example.com/watch/some-id") ... .build() val loadRequest = MediaLoadRequestData.Builder() .setMediaInfo(mediaToLoad) .setCredentials("user-credentials") ... .build() remoteMediaClient.load(loadRequest)
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);
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)
נדרשת גרסה M87
ומעלה של דפדפן Chromium.
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 עם הקישור העמוק ושם החבילה שהגדרתם ב-Play Console.
הגדרת פרטי כניסה של ATV בשולח
יכול להיות שאפליקציית Web Receiver ואפליקציית Android TV תומכות בקישורים עמוקים שונים וב-credentials
(למשל, אם אתם מטפלים באימות באופן שונה בשתי הפלטפורמות). כדי לטפל בבעיה, אפשר לספק חלופות לentity
וcredentials
ל-Android TV:
val mediaToLoad = MediaInfo.Builder("some-id") .setEntity("https://example.com/watch/some-id") .setAtvEntity("myscheme://example.com/atv/some-id") ... .build() val loadRequest = MediaLoadRequestData.Builder() .setMediaInfo(mediaToLoad) .setCredentials("user-credentials") .setAtvCredentials("atv-user-credentials") ... .build() remoteMediaClient.load(loadRequest)
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);
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)
נדרשת גרסה M87
ומעלה של דפדפן Chromium.
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 או ב-Content URL ב-Media Information או ב-Media Load Request Data המפורט יותר, אתם צריכים להוסיף את מסנן הכוונות המוגדר מראש הבא באפליקציית Android TV:
<activity android:name="com.example.activity">
<intent-filter>
<action android:name="com.google.android.gms.cast.tv.action.LOAD"/>
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
בצד השולח, בדומה לטעינה לפי ישות, אפשר ליצור בקשת טעינה עם פרטי התוכן שלכם ולהתקשר אל load()
.
val mediaToLoad = MediaInfo.Builder("some-id").build() val loadRequest = MediaLoadRequestData.Builder() .setMediaInfo(mediaToLoad) .setCredentials("user-credentials") ... .build() remoteMediaClient.load(loadRequest)
MediaInfo mediaToLoad = new MediaInfo.Builder("some-id").build(); MediaLoadRequestData loadRequest = new MediaLoadRequestData.Builder() .setMediaInfo(mediaToLoad) .setCredentials("user-credentials") ... .build(); remoteMediaClient.load(loadRequest);
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)
נדרשת גרסה M87
ומעלה של דפדפן Chromium.
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);
טיפול בבקשות טעינה
כדי לטפל בבקשות הטעינה האלה בפעילות, צריך לטפל ב-intents בקריאות החוזרות (callbacks) של מחזור החיים של הפעילות:
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. ... } }
public class MyActivity extends Activity { @Override protected void onStart() { super.onStart(); MediaManager mediaManager = CastReceiverContext.getInstance().getMediaManager(); // Pass the intent to the SDK. You can also do this in onCreate(). if (mediaManager.onNewIntent(getIntent())) { // If the SDK recognizes the intent, you should early return. return; } // If the SDK doesn't recognize the intent, you can handle the intent with // your own logic. ... } // For some cases, a new load intent triggers onNewIntent() instead of // onStart(). @Override protected void onNewIntent(Intent intent) { MediaManager mediaManager = CastReceiverContext.getInstance().getMediaManager(); // Pass the intent to the SDK. You can also do this in onCreate(). if (mediaManager.onNewIntent(intent)) { // If the SDK recognizes the intent, you should early return. return; } // If the SDK doesn't recognize the intent, you can handle the intent with // your own logic. ... } }
אם MediaManager
מזהה שהכוונה היא כוונה של טעינה, הוא מחלץ אובייקט MediaLoadRequestData
מהכוונה ומפעיל את MediaLoadCommandCallback.onLoad()
.
צריך לבטל את השיטה הזו כדי לטפל בבקשת הטעינה. צריך לרשום את הקריאה החוזרת לפני שמבצעים קריאה ל-MediaManager.onNewIntent()
(מומלץ להשתמש בשיטה Activity או Application onCreate()
).
class MyActivity : Activity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val mediaManager = CastReceiverContext.getInstance().getMediaManager() mediaManager.setMediaLoadCommandCallback(MyMediaLoadCommandCallback()) } } class MyMediaLoadCommandCallback : MediaLoadCommandCallback() { override fun onLoad( senderId: String?, loadRequestData: MediaLoadRequestData ): Task{ return Tasks.call { // Resolve the entity into your data structure and load media. val mediaInfo = loadRequestData.getMediaInfo() if (!checkMediaInfoSupported(mediaInfo)) { // Throw MediaException to indicate load failure. throw MediaException( MediaError.Builder() .setDetailedErrorCode(DetailedErrorCode.LOAD_FAILED) .setReason(MediaError.ERROR_REASON_INVALID_REQUEST) .build() ) } myFillMediaInfo(MediaInfoWriter(mediaInfo)) myPlayerLoad(mediaInfo.getContentUrl()) // Update media metadata and state (this clears all previous status // overrides). castReceiverContext.getMediaManager() .setDataFromLoad(loadRequestData) ... castReceiverContext.getMediaManager().broadcastMediaStatus() // Return the resolved MediaLoadRequestData to indicate load success. return loadRequestData } } private fun myPlayerLoad(contentURL: String) { myPlayer.load(contentURL) // Update the MediaSession state. val playbackState: PlaybackStateCompat = Builder() .setState( player.getState(), player.getPosition(), System.currentTimeMillis() ) ... .build() mediaSession.setPlaybackState(playbackState) }
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 TaskonLoad(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) של סשן המדיה. כדי לתמוך בזה, צריך לרשום קריאה חוזרת לסשן המדיה (יכול להיות שאתם כבר עושים את זה).
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())
private class MyMediaSessionCallback extends MediaSessionCompat.Callback { @Override public void onPause() { // Pause the player and update the play state. myPlayer.pause(); } @Override public void onPlay() { // Resume the player and update the play state. myPlayer.play(); } @Override public void onSeekTo(long pos) { // Seek and update the play state. myPlayer.seekTo(pos); } ... } mediaSession.setCallback(new MyMediaSessionCallback());
תמיכה בפקודות שליטה ב-Cast
יש פקודות Cast שלא זמינות ב-MediaSession
, כמו skipAd()
או setActiveMediaTracks()
.
בנוסף, צריך להטמיע כאן כמה פקודות של תור, כי תור ההפעלה של Cast לא תואם באופן מלא לתור של MediaSession
.
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())
public class MyMediaCommandCallback extends MediaCommandCallback { @Override public TaskonSkipAd(RequestData requestData) { // Skip your ad ... return Tasks.forResult(null); } } MediaManager mediaManager = CastReceiverContext.getInstance().getMediaManager(); mediaManager.setMediaCommandCallback(new MyMediaCommandCallback());
הגדרת פקודות מדיה נתמכות
בדומה למקלט Cast, באפליקציית Android TV צריך לציין אילו פקודות נתמכות, כדי שהשולחים יוכלו להפעיל או להשבית אמצעי בקרה מסוימים בממשק המשתמש. לפקודות שכלולות בMediaSession
, מציינים את הפקודות בPlaybackStateCompat
.
פקודות נוספות צריך לציין בתג MediaStatusModifier
.
// Set media session supported commands val playbackState: PlaybackStateCompat = PlaybackStateCompat.Builder() .setActions(PlaybackStateCompat.ACTION_PLAY or PlaybackStateCompat.ACTION_PAUSE) .setState(PlaybackStateCompat.STATE_PLAYING) .build() mediaSession.setPlaybackState(playbackState) // Set additional commands in MediaStatusModifier val mediaManager = CastReceiverContext.getInstance().getMediaManager() mediaManager.getMediaStatusModifier() .setMediaCommandSupported(MediaStatus.COMMAND_QUEUE_NEXT)
// 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 תומכת בשליטה מתקדמת יותר, צריך לוודא שאפליקציית השולח מתנהגת בצורה תקינה כשמפעילים Cast לאפליקציית Android TV. לדוגמה, אם אפליקציית Android TV לא תומכת בשינוי מהירות ההפעלה, אבל אפליקציית Web Receiver כן תומכת, צריך להגדיר את הפעולות הנתמכות בצורה נכונה בכל פלטפורמה ולוודא שאפליקציית השולח מעבדת את ממשק המשתמש בצורה תקינה.
שינוי של MediaStatus
כדי לתמוך בתכונות מתקדמות כמו טראקים, מודעות, שידורים חיים והוספה לתור, אפליקציית Android TV צריכה לספק מידע נוסף שלא ניתן להשיג באמצעות MediaSession
.
לשם כך, אנחנו מספקים את המחלקה MediaStatusModifier
. MediaStatusModifier
תמיד יפעל על MediaSession
שהגדרתם בCastReceiverContext
.
כדי ליצור ולשדר
MediaStatus
:
val mediaManager: MediaManager = castReceiverContext.getMediaManager() val statusModifier: MediaStatusModifier = mediaManager.getMediaStatusModifier() statusModifier .setLiveSeekableRange(seekableRange) .setAdBreakStatus(adBreakStatus) .setCustomData(customData) mediaManager.broadcastMediaStatus()
MediaManager mediaManager = castReceiverContext.getMediaManager(); MediaStatusModifier statusModifier = mediaManager.getMediaStatusModifier(); statusModifier .setLiveSeekableRange(seekableRange) .setAdBreakStatus(adBreakStatus) .setCustomData(customData); mediaManager.broadcastMediaStatus();
ספריית הלקוח שלנו תקבל את בסיס MediaStatus
מ-MediaSession
, ואפליקציית Android TV שלכם יכולה לציין סטטוס נוסף ולשנות את הסטטוס באמצעות משנה MediaStatus
.
אפשר להגדיר חלק מהסטטוסים והמטא-נתונים גם ב-MediaSession
וגם ב-MediaStatusModifier
. מומלץ מאוד להגדיר אותם רק ב-MediaSession
. עדיין אפשר להשתמש במחרוזת לשינוי כדי לשנות את המצבים ב-MediaSession
– לא מומלץ לעשות את זה כי למצב במחרוזת לשינוי תמיד יש עדיפות גבוהה יותר מהערכים שסופקו על ידי MediaSession
.
יירוט של MediaStatus לפני השליחה
בדומה ל-Web Receiver SDK, אם רוצים לבצע שינויים אחרונים לפני השליחה, אפשר לציין MediaStatusInterceptor
כדי לעבד את MediaStatus
שיישלח. אנחנו מעבירים את MediaStatusWriter
כדי לשנות את MediaStatus
לפני שהוא נשלח.
mediaManager.setMediaStatusInterceptor(object : MediaStatusInterceptor { override fun intercept(mediaStatusWriter: MediaStatusWriter) { // Perform customization. mediaStatusWriter.setCustomData(JSONObject("{data: \"my Hello\"}")) } })
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()
.
נדרשת גרסה play-services-cast-framework
19.0.0
ומעלה.
CastContext.getSharedInstance().setLaunchCredentialsData( CredentialsData.Builder() .setCredentials("{\"userId\": \"abc\"}") .build() )
CastContext.getSharedInstance().setLaunchCredentialsData( new CredentialsData.Builder() .setCredentials("{\"userId\": \"abc\"}") .build());
נדרשת גרסה google-cast-sdk
v4.8.3
ומעלה.
אפשר להתקשר בכל שלב אחרי הגדרת האפשרויות:
GCKCastContext.setSharedInstanceWith(options)
.
GCKCastContext.sharedInstance().setLaunch( GCKCredentialsData(credentials: "{\"userId\": \"abc\"}")
נדרשת גרסה M87
ומעלה של דפדפן Chromium.
אפשר לקרוא לפונקציה הזו בכל שלב אחרי שהאפשרויות מוגדרות:
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
:
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. }
public class MyLaunchRequestChecker implements CastReceiverOptions.LaunchRequestChecker { @Override public TaskcheckLaunchRequestSupported(CastLaunchRequest launchRequest) { return Tasks.call(() -> myCheckLaunchRequest(launchRequest)); } } private boolean myCheckLaunchRequest(CastLaunchRequest launchRequest) { CredentialsData credentialsData = launchRequest.getCredentialsData(); if (credentialsData == null) { return false; // or true if you allow anonymous users to join. } // The request comes from a mobile device, e.g. checking user match. if (credentialsData.getCredentialsType().equals(CredentialsData.CREDENTIALS_TYPE_ANDROID)) { return myCheckMobileCredentialsAllowed(credentialsData.getCredentials()); } // Unrecognized credentials type. return false; }
לאחר מכן מגדירים אותו בReceiverOptionsProvider
:
class MyReceiverOptionsProvider : ReceiverOptionsProvider { override fun getOptions(context: Context?): CastReceiverOptions { return CastReceiverOptions.Builder(context) ... .setLaunchRequestChecker(MyLaunchRequestChecker()) .build() } }
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
, צריך לרשום מרחב שמות (ערוץ) לפני שמפעילים את CastReceiverContext
.
Android TV – ציון מרחב שמות מותאם אישית
במהלך ההגדרה, צריך לציין את מרחבי השמות הנתמכים בקובץ CastReceiverOptions
:
class MyReceiverOptionsProvider : ReceiverOptionsProvider { override fun getOptions(context: Context?): CastReceiverOptions { return CastReceiverOptions.Builder(context) .setCustomNamespaces( Arrays.asList("urn:x-cast:com.example.cast.mynamespace") ) .build() } }
public class MyReceiverOptionsProvider implements ReceiverOptionsProvider { @Override public CastReceiverOptions getOptions(Context context) { return new CastReceiverOptions.Builder(context) .setCustomNamespaces( Arrays.asList("urn:x-cast:com.example.cast.mynamespace")) .build(); } }
Android TV – שליחת הודעות
// If senderId is null, then the message is broadcasted to all senders. CastReceiverContext.getInstance().sendMessage( "urn:x-cast:com.example.cast.mynamespace", senderId, customString)
// If senderId is null, then the message is broadcasted to all senders. CastReceiverContext.getInstance().sendMessage( "urn:x-cast:com.example.cast.mynamespace", senderId, customString);
Android TV – קבלת הודעות של מרחב שמות מותאם אישית
class MyCustomMessageListener : MessageReceivedListener { override fun onMessageReceived( namespace: String, senderId: String?, message: String ) { ... } } CastReceiverContext.getInstance().setMessageReceivedListener( "urn:x-cast:com.example.cast.mynamespace", new MyCustomMessageListener());
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());