1. Panoramica
Questo codelab ti insegnerà a modificare un'app Android TV esistente per supportare la trasmissione e la comunicazione dalle app Trasmetti mittenti esistenti.
Che cos'è Google Cast e Cast Connect?
Google Cast consente agli utenti di trasmettere contenuti da un dispositivo mobile a una TV. Una tipica sessione di Google Cast è costituita da due componenti: un'applicazione mittente e un'applicazione ricevitore. Le applicazioni mittente, come un'app per dispositivi mobili o un sito web come YouTube.com, avviano e controllano la riproduzione di un'applicazione ricevitore di trasmissione. Le applicazioni ricevitore di trasmissione sono app HTML 5 eseguibili su dispositivi Chromecast e Android TV.
Quasi tutto lo stato di una sessione di trasmissione viene memorizzato nell'applicazione del ricevitore. Quando lo stato viene aggiornato, ad esempio se viene caricato un nuovo elemento multimediale, a tutti i mittenti viene trasmesso uno stato dei contenuti multimediali. Queste trasmissioni contengono lo stato corrente della sessione di trasmissione. Le applicazioni dei mittenti utilizzano questo stato multimediale per visualizzare le informazioni sulla riproduzione nell'interfaccia utente.
Cast Connect si basa su questa infrastruttura, in cui la tua app Android TV funge da ricevitore. La libreria di Cast Connect consente alla tua app Android TV di ricevere messaggi e trasmettere lo stato dei contenuti multimediali come se fosse un'applicazione ricevitore di trasmissione.
Cosa realizzeremo
Una volta completato questo codelab, potrai utilizzare le app del mittente di trasmissione per trasmettere video a un'app Android TV. L'app Android TV può comunicare anche con le app del mittente tramite il protocollo Cast.
Obiettivi didattici
- Come aggiungere la raccolta Cast Connect a un'app ATV di esempio.
- Come connettere un mittente di trasmissione e avviare l'app ATV.
- Come avviare la riproduzione di contenuti multimediali nell'app ATV da un'app mittente di trasmissione.
- Come inviare lo stato dei contenuti multimediali dall'app ATV alle app del mittente di trasmissione.
Che cosa ti serve
- L'SDK Android più recente.
- La versione più recente di Android Studio. In particolare,
Chipmunk | 2021.2.1o versioni successive. - Un dispositivo Android TV su cui sono attive le opzioni sviluppatore e il debug USB.
- Uno smartphone Android con le opzioni sviluppatore e il debug USB.
- Un cavo dati USB per collegare il tuo telefono Android e i dispositivi Android TV al computer di sviluppo.
- Conoscenza di base dello sviluppo di app per Android tramite Kotlin.
2. Recupera il codice campione
Puoi scaricare tutto il codice campione sul tuo computer...
e decomprimere il file ZIP scaricato.
3. Esegui l'app di esempio
Innanzitutto, vediamo l'aspetto dell'app di esempio completata. L'app Android TV utilizza l'interfaccia utente di Leanback e un video player di base. L'utente può selezionare un video da un elenco che, se selezionato, viene riprodotto sulla TV. Con l'app mobile del mittente, un utente può anche trasmettere un video all'app Android TV.
Registra i dispositivi degli sviluppatori
Per poter attivare le funzionalità di Cast Connect per lo sviluppo di applicazioni, devi registrare il numero di serie del Chromecast integrato nel dispositivo Android TV che utilizzerai nella Console per gli sviluppatori di Google Cast. Puoi trovare il numero di serie in Impostazioni > Preferenze del dispositivo > Chromecast integrato > Numero di serie sulla tua Android TV. Tieni presente che è diverso dal numero di serie del dispositivo fisico e deve essere ottenuto con il metodo descritto sopra.
Senza registrazione, Cast Connect funziona solo per le app installate dal Google Play Store per motivi di sicurezza. Dopo 15 minuti dall'avvio del processo di registrazione, riavvia il dispositivo.
Installare l'app mittente Android
Per testare le richieste di invio da un dispositivo mobile, abbiamo fornito una semplice applicazione mittente chiamata Trasmetti video come file mobile-sender-0629.apk nel codice sorgente del download del codice postale. Useremo ADB per installare l'APK. Se hai già installato una versione diversa di Video Cast, disinstalla quella versione da tutti i profili presenti sul dispositivo prima di continuare.
- Attiva le opzioni sviluppatore e il debug USB sul tuo telefono Android.
- Collega un cavo dati USB per collegare lo smartphone Android al computer di sviluppo.
- Installa
mobile-sender-0629.apksul tuo telefono Android.
- Puoi trovare l'app del mittente Trasmetti video sul tuo telefono Android.
Installa l'app Android TV
Le istruzioni seguenti spiegano come aprire ed eseguire l'app di esempio completata in Android Studio:
- Seleziona Importa progetto nella schermata di benvenuto o le opzioni di menu File > Nuovo > Importa progetto....
- Seleziona la directory
app-donedalla cartella del codice di esempio e fai clic su OK. - Fai clic su File >
Sincronizza progetto con file Gradle. - Attiva le opzioni sviluppatore e il debug USB sul tuo dispositivo Android TV.
- ADB si connette al dispositivo Android TV, il dispositivo dovrebbe essere visualizzato in Android Studio.
- Fai clic sul pulsante
Esegui. Dopo qualche secondo dovresti vedere l'app ATV chiamata Cast Connect Codelab.
Giochiamo a Cast Connect con l'app ATV
- Vai alla schermata Home di Android TV.
- Apri l'app del mittente Trasmetti video dal tuo telefono Android. Fai clic sul pulsante Trasmetti
e seleziona il tuo dispositivo ATV. - L'app Codelab ATV Cast Connect verrà avviata sull'ATV e il pulsante Trasmetti nel mittente indicherà che è connesso
. - Seleziona un video dall'app ATV per avviare la riproduzione del video.
- Sul tuo cellulare, ora è visibile un mini controller nella parte inferiore dell'app del mittente. Puoi utilizzare il pulsante di riproduzione/pausa per controllare la riproduzione.
- Seleziona un video dal cellulare e riproduci. Il video inizierà a essere riprodotto sull'ATV e il controller espanso verrà visualizzato sul mittente del dispositivo mobile.
- Blocca il telefono. Quando lo sblocchi, dovresti visualizzare una notifica nella schermata di blocco per controllare la riproduzione dei contenuti multimediali o interrompere la trasmissione.
4. Prepara il progetto di avvio
Ora che abbiamo verificato l'integrazione di Cast Connect dell'app completata, dobbiamo aggiungere il supporto di Cast Connect all'app iniziale che hai scaricato. Ora è tutto pronto per creare sulla base del progetto iniziale utilizzando Android Studio:
- Seleziona Importa progetto nella schermata di benvenuto o le opzioni di menu File > Nuovo > Importa progetto....
- Seleziona la directory
app-startdalla cartella del codice di esempio e fai clic su OK. - Fai clic su File > Sincronizza progetto con file Gradle.
- Seleziona il dispositivo ATV e fai clic sul pulsante Esegui per eseguire l'app ed esplorare l'interfaccia utente.
Progettazione di app
L'app fornisce all'utente un elenco di video da sfogliare. Gli utenti possono selezionare un video da riprodurre su Android TV. L'app è costituita da due attività principali: MainActivity e PlaybackActivity.
MainActivity
Questa attività contiene un frammento (MainFragment). L'elenco dei video e i metadati associati sono configurati nella classe MovieList e il metodo setupMovies() viene chiamato per creare un elenco di oggetti Movie.
Un oggetto Movie rappresenta un'entità video con titolo, descrizione, miniature immagine e URL del video. Ogni oggetto Movie è associato a un CardPresenter per presentare la miniatura del video con titolo e studio cinematografico e passato al ArrayObjectAdapter.
Quando viene selezionato un elemento, l'oggetto Movie corrispondente viene passato a PlaybackActivity.
PlaybackActivity
Questa attività contiene un frammento (PlaybackVideoFragment) che ospita un VideoView con ExoPlayer, alcuni controlli multimediali e un'area di testo per mostrare la descrizione del video selezionato e consentire all'utente di riprodurlo su Android TV. L'utente può utilizzare il telecomando per riprodurre/mettere in pausa i video o per cercare la riproduzione dei video.
Prerequisiti di Cast Connect
Cast Connect utilizza nuove versioni di Google Play Services che richiedono l'aggiornamento dell'app ATV per l'utilizzo dello spazio dei nomi AndroidX.
Per supportare Cast Connect nella tua app Android TV, devi creare e supportare eventi da una sessione multimediale. La raccolta di Cast Connect genera lo stato dei contenuti multimediali in base allo stato della sessione multimediale. La sessione multimediale viene utilizzata anche dalla raccolta di Cast Connect per segnalare la ricezione di determinati messaggi da un mittente, ad esempio la pausa.
5. Configurare il supporto della trasmissione
Dipendenze
Aggiorna il file build.gradle dell'app in modo che includa le dipendenze di libreria necessarie:
dependencies {
....
// Cast Connect libraries
implementation 'com.google.android.gms:play-services-cast-tv:20.0.0'
implementation 'com.google.android.gms:play-services-cast:21.1.0'
}
Sincronizza il progetto per confermare che le build del progetto non presenti errori.
Inizializzazione
CastReceiverContext è un oggetto singleton per coordinare tutte le interazioni con la trasmissione. Devi implementare l'interfaccia ReceiverOptionsProvider per fornire CastReceiverOptions all'inizializzazione di CastReceiverContext.
Crea il file CastReceiverOptionsProvider.kt e aggiungi la classe seguente al progetto:
package com.google.sample.cast.castconnect
import android.content.Context
import com.google.android.gms.cast.tv.ReceiverOptionsProvider
import com.google.android.gms.cast.tv.CastReceiverOptions
class CastReceiverOptionsProvider : ReceiverOptionsProvider {
override fun getOptions(context: Context): CastReceiverOptions {
return CastReceiverOptions.Builder(context)
.setStatusText("Cast Connect Codelab")
.build()
}
}
Quindi specifica il fornitore delle opzioni per il destinatario nel tag <application> del file AndroidManifest.xml dell'app:
<application>
...
<meta-data
android:name="com.google.android.gms.cast.tv.RECEIVER_OPTIONS_PROVIDER_CLASS_NAME"
android:value="com.google.sample.cast.castconnect.CastReceiverOptionsProvider" />
</application>
Per connetterti con la tua app ATV dal mittente di trasmissione, seleziona un'attività che vuoi avviare. In questo codelab, lanceremo il MainActivity dell'app all'avvio di una sessione di trasmissione. Nel file AndroidManifest.xml, aggiungi il filtro per intent di lancio in MainActivity.
<activity android:name=".MainActivity">
...
<intent-filter>
<action android:name="com.google.android.gms.cast.tv.action.LAUNCH" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
Ciclo di vita del contesto ricevitore di trasmissione
Devi avviare CastReceiverContext all'avvio dell'app e interrompere CastReceiverContext quando l'app viene spostata in background. Ti consigliamo di usare il LifecycleObserver della libreria androidx.lifecycle per gestire le chiamate a CastReceiverContext.start() e CastReceiverContext.stop()
Apri il file MyApplication.kt, inizializza il contesto di trasmissione chiamando initInstance() nel metodo onCreate dell'applicazione. Nella classe AppLifeCycleObserver start() la CastReceiverContext quando l'applicazione viene ripristinata e stop() quando l'applicazione viene messa in pausa:
package com.google.sample.cast.castconnect
import com.google.android.gms.cast.tv.CastReceiverContext
...
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
CastReceiverContext.initInstance(this)
ProcessLifecycleOwner.get().lifecycle.addObserver(AppLifecycleObserver())
}
class AppLifecycleObserver : DefaultLifecycleObserver {
override fun onResume(owner: LifecycleOwner) {
Log.d(LOG_TAG, "onResume")
CastReceiverContext.getInstance().start()
}
override fun onPause(owner: LifecycleOwner) {
Log.d(LOG_TAG, "onPause")
CastReceiverContext.getInstance().stop()
}
}
}
Connessione MediaSession a MediaManager
MediaManager è una proprietà del singleton CastReceiverContext, gestisce lo stato dei contenuti multimediali, gestisce l'intent di caricamento, traduce i messaggi dello spazio dei nomi multimediale inviati dai mittenti in comandi multimediali e invia di nuovo lo stato dei contenuti multimediali ai mittenti.
Quando crei un MediaSession, devi anche fornire l'attuale token MediaSession a MediaManager in modo che sappia dove inviare i comandi e recuperare lo stato di riproduzione dei contenuti multimediali. Nel file PlaybackVideoFragment.kt, assicurati che MediaSession sia inizializzato prima di impostare il token su MediaManager.
import com.google.android.gms.cast.tv.CastReceiverContext
import com.google.android.gms.cast.tv.media.MediaManager
...
class PlaybackVideoFragment : VideoSupportFragment() {
private var castReceiverContext: CastReceiverContext? = null
...
private fun initializePlayer() {
if (mPlayer == null) {
...
mMediaSession = MediaSessionCompat(getContext(), LOG_TAG)
...
castReceiverContext = CastReceiverContext.getInstance()
if (castReceiverContext != null) {
val mediaManager: MediaManager = castReceiverContext!!.getMediaManager()
mediaManager.setSessionCompatToken(mMediaSession!!.getSessionToken())
}
}
}
}
Quando rilasci il tuo MediaSession a causa della riproduzione inattiva, devi impostare un token null su MediaManager:
private fun releasePlayer() {
mMediaSession?.release()
castReceiverContext?.mediaManager?.setSessionCompatToken(null)
...
}
Eseguiamo l'app di esempio
Fai clic sul pulsante Esegui per implementare l'app sul tuo dispositivo ATV, chiudi l'app e torna alla schermata Home di ATV. Dal mittente, fai clic sul pulsante Trasmetti e seleziona il tuo dispositivo ATV. Vedrai l'app ATV avviata sul dispositivo ATV e lo stato del pulsante Trasmetti è connesso.
6. Caricamento dei contenuti multimediali
Il comando di caricamento viene inviato tramite un intent con il nome del pacchetto definito nella console per gli sviluppatori. Devi aggiungere il seguente filtro per intent predefinito nell'app Android TV per specificare l'attività target che riceverà questo intent. Nel file AndroidManifest.xml, aggiungi il filtro per intent di caricamento a PlayerActivity:
<activity android:name="com.google.sample.cast.castconnect.PlaybackActivity"
android:launchMode="singleTask"
android:exported="true">
<intent-filter>
<action android:name="com.google.android.gms.cast.tv.action.LOAD"/>
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
Gestione delle richieste di carico su Android TV
Ora che l'attività è configurata per ricevere questo intent contenente una richiesta di caricamento, dovremo gestirlo.
All'inizio dell'attività, l'app chiama un metodo privato denominato processIntent. Questo metodo contiene la logica per l'elaborazione degli intent in entrata. Per gestire una richiesta di carico, modificheremo questo metodo e invieremo l'intent da elaborare ulteriormente chiamando il metodo onNewIntent dell'istanza MediaManager. Se MediaManager rileva che l'intent è una richiesta di caricamento, estrae l'oggetto MediaLoadRequestData dall'intent e richiama MediaLoadCommandCallback.onLoad(). Modifica il metodo processIntent nel file PlaybackVideoFragment.kt per gestire l'intent contenente la richiesta di caricamento:
fun processIntent(intent: Intent?) {
val mediaManager: MediaManager = CastReceiverContext.getInstance().getMediaManager()
// Pass intent to Cast SDK
if (mediaManager.onNewIntent(intent)) {
return
}
// Clears all overrides in the modifier.
mediaManager.getMediaStatusModifier().clear()
// If the SDK doesn't recognize the intent, handle the intent with your own logic.
...
}
In seguito, estenderemo la classe astratta MediaLoadCommandCallback, che sostituirà il metodo onLoad() chiamato da MediaManager. Questo metodo riceve i dati della richiesta di caricamento e li converte in un oggetto Movie. Una volta convertito, il filmato viene riprodotto dal player locale. L'elemento MediaManager viene quindi aggiornato con MediaLoadRequest e trasmette MediaStatus ai mittenti connessi. Crea una classe privata nidificata denominata MyMediaLoadCommandCallback nel file PlaybackVideoFragment.kt:
import com.google.android.gms.cast.MediaLoadRequestData
import com.google.android.gms.cast.MediaInfo
import com.google.android.gms.cast.MediaMetadata
import com.google.android.gms.cast.MediaError
import com.google.android.gms.cast.tv.media.MediaException
import com.google.android.gms.cast.tv.media.MediaCommandCallback
import com.google.android.gms.cast.tv.media.QueueUpdateRequestData
import com.google.android.gms.cast.tv.media.MediaLoadCommandCallback
import com.google.android.gms.tasks.Task
import com.google.android.gms.tasks.Tasks
import android.widget.Toast
...
private inner class MyMediaLoadCommandCallback : MediaLoadCommandCallback() {
override fun onLoad(
senderId: String?, mediaLoadRequestData: MediaLoadRequestData): Task<MediaLoadRequestData> {
Toast.makeText(activity, "onLoad()", Toast.LENGTH_SHORT).show()
return if (mediaLoadRequestData == null) {
// Throw MediaException to indicate load failure.
Tasks.forException(MediaException(
MediaError.Builder()
.setDetailedErrorCode(MediaError.DetailedErrorCode.LOAD_FAILED)
.setReason(MediaError.ERROR_REASON_INVALID_REQUEST)
.build()))
} else Tasks.call {
play(convertLoadRequestToMovie(mediaLoadRequestData)!!)
// Update media metadata and state
val mediaManager = castReceiverContext!!.mediaManager
mediaManager.setDataFromLoad(mediaLoadRequestData)
mediaLoadRequestData
}
}
}
private fun convertLoadRequestToMovie(mediaLoadRequestData: MediaLoadRequestData?): Movie? {
if (mediaLoadRequestData == null) {
return null
}
val mediaInfo: MediaInfo = mediaLoadRequestData.getMediaInfo() ?: return null
var videoUrl: String = mediaInfo.getContentId()
if (mediaInfo.getContentUrl() != null) {
videoUrl = mediaInfo.getContentUrl()
}
val metadata: MediaMetadata = mediaInfo.getMetadata()
val movie = Movie()
movie.videoUrl = videoUrl
movie.title = metadata?.getString(MediaMetadata.KEY_TITLE)
movie.description = metadata?.getString(MediaMetadata.KEY_SUBTITLE)
if(metadata?.hasImages() == true) {
movie.cardImageUrl = metadata.images[0].url.toString()
}
return movie
}
Ora che è stato definito il callback, dobbiamo registrarlo nel MediaManager. Il callback deve essere registrato prima della chiamata di MediaManager.onNewIntent(). Aggiungi setMediaLoadCommandCallback all'inizializzazione del player:
private fun initializePlayer() {
if (mPlayer == null) {
...
mMediaSession = MediaSessionCompat(getContext(), LOG_TAG)
...
castReceiverContext = CastReceiverContext.getInstance()
if (castReceiverContext != null) {
val mediaManager: MediaManager = castReceiverContext.getMediaManager()
mediaManager.setSessionCompatToken(mMediaSession.getSessionToken())
mediaManager.setMediaLoadCommandCallback(MyMediaLoadCommandCallback())
}
}
}
Eseguiamo l'app di esempio
Fai clic sul pulsante Esegui per eseguire il deployment dell'app sul tuo dispositivo ATV. Dal mittente, fai clic sul pulsante Trasmetti e seleziona il tuo dispositivo ATV. L'app ATV verrà avviata sul dispositivo ATV. Seleziona un video da dispositivo mobile, il video verrà riprodotto sull'ATV. Controlla se ricevi una notifica sullo smartphone in cui sono disponibili i controlli di riproduzione. Prova a usare i comandi, ad esempio "Metti in pausa" e il video sul dispositivo ATV deve essere messo in pausa.
7. Supporto dei comandi di controllo della trasmissione
L'applicazione corrente ora supporta i comandi di base compatibili con una sessione multimediale, come riproduzione, pausa e ricerca. Tuttavia, esistono alcuni comandi di controllo della trasmissione che non sono disponibili nelle sessioni multimediali. Devi registrare un MediaCommandCallback per supportare i comandi di controllo della trasmissione.
Aggiungi MyMediaCommandCallback all'istanza MediaManager utilizzando setMediaCommandCallback quando il player viene inizializzato:
private fun initializePlayer() {
...
castReceiverContext = CastReceiverContext.getInstance()
if (castReceiverContext != null) {
val mediaManager = castReceiverContext!!.mediaManager
...
mediaManager.setMediaCommandCallback(MyMediaCommandCallback())
}
}
Crea la classe MyMediaCommandCallback per eseguire l'override dei metodi, ad esempio onQueueUpdate() per supportare i comandi di controllo della trasmissione:
private inner class MyMediaCommandCallback : MediaCommandCallback() {
override fun onQueueUpdate(
senderId: String?,
queueUpdateRequestData: QueueUpdateRequestData
): Task<Void> {
Toast.makeText(getActivity(), "onQueueUpdate()", Toast.LENGTH_SHORT).show()
// Queue Prev / Next
if (queueUpdateRequestData.getJump() != null) {
Toast.makeText(
getActivity(),
"onQueueUpdate(): Jump = " + queueUpdateRequestData.getJump(),
Toast.LENGTH_SHORT
).show()
}
return super.onQueueUpdate(senderId, queueUpdateRequestData)
}
}
8. Utilizzo dello stato dei contenuti multimediali
Modifica dello stato dei contenuti multimediali
Cast Connect ottiene lo stato dei contenuti multimediali di base dalla sessione multimediale. Per supportare le funzionalità avanzate, l'app Android TV può specificare e sostituire ulteriori proprietà di stato tramite un MediaStatusModifier. MediaStatusModifier funzionerà sempre sul MediaSession che hai impostato in CastReceiverContext.
Ad esempio, per specificare setMediaCommandSupported quando viene attivato il callback onLoad:
import com.google.android.gms.cast.MediaStatus
...
private class MyMediaLoadCommandCallback : MediaLoadCommandCallback() {
fun onLoad(
senderId: String?,
mediaLoadRequestData: MediaLoadRequestData
): Task<MediaLoadRequestData> {
Toast.makeText(getActivity(), "onLoad()", Toast.LENGTH_SHORT).show()
...
return Tasks.call({
play(convertLoadRequestToMovie(mediaLoadRequestData)!!)
...
// Use MediaStatusModifier to provide additional information for Cast senders.
mediaManager.getMediaStatusModifier()
.setMediaCommandSupported(MediaStatus.COMMAND_QUEUE_NEXT, true)
.setIsPlayingAd(false)
mediaManager.broadcastMediaStatus()
// Return the resolved MediaLoadRequestData to indicate load success.
mediaLoadRequestData
})
}
}
Intercettazione di MediaStatus prima dell'invio
Analogamente a MessageInterceptor dell'SDK del ricevitore web, puoi specificare un MediaStatusWriter nel tuo MediaManager per apportare ulteriori modifiche a MediaStatus prima che venga trasmesso ai mittenti connessi.
Ad esempio, puoi impostare i dati personalizzati in MediaStatus prima di inviarli ai mittenti di dispositivi mobili:
import com.google.android.gms.cast.tv.media.MediaManager.MediaStatusInterceptor
import com.google.android.gms.cast.tv.media.MediaStatusWriter
import org.json.JSONObject
import org.json.JSONException
...
private fun initializePlayer() {
if (mPlayer == null) {
...
if (castReceiverContext != null) {
...
val mediaManager: MediaManager = castReceiverContext.getMediaManager()
...
// Use MediaStatusInterceptor to process the MediaStatus before sending out.
mediaManager.setMediaStatusInterceptor(
MediaStatusInterceptor { mediaStatusWriter: MediaStatusWriter ->
try {
mediaStatusWriter.setCustomData(JSONObject("{myData: 'CustomData'}"))
} catch (e: JSONException) {
Log.e(LOG_TAG,e.message,e);
}
})
}
}
}
9. Congratulazioni
Ora sai come attivare la trasmissione di un'app Android TV utilizzando la raccolta di Cast Connect.
Per ulteriori dettagli, consulta la guida per gli sviluppatori: /cast/docs/android_tv_receiver.