Utilizzare la libreria Jetpack Picture in picture

La libreria Jetpack Picture in picture (PIP) offre una soluzione semplificata e robusta per gli sviluppatori di app per Android per implementare la funzionalità PIP, in particolare per app di riproduzione multimediale, comunicazione video e navigazione. Fornendo un'API unificata, la libreria contribuisce a eliminare il codice boilerplate, i bug comuni in-app e a migliorare la qualità complessiva dell'esperienza utente PiP.

La libreria Jetpack PiP facilita l'utilizzo delle API PiP esistenti risolvendo diversi problemi e incongruenze chiave nell'ecosistema Android:

  • Frammentazione del sistema operativo: la libreria gestisce automaticamente le differenze nelle chiamate API PiP tra le varie versioni di Android, ad esempio utilizzando enterPictureInPictureMode prima di Android 12 e isAutoEnterEnabled dopo, in modo che gli sviluppatori non debbano gestire le differenze di versione.
  • Parametri PIP errati: fornisce una soluzione unificata per impostare correttamente i parametri PIP, ad esempio setSourceRectHint, per creare animazioni fluide e di alta qualità durante la riproduzione dei contenuti multimediali.
  • Callback unificati dello stato PiP: consolida onPictureInPictureModeChanged e onPictureInPictureUiStateChanged in un'unica interfaccia di callback unificata (PictureInPictureDelegate.OnPictureInPictureEventListener) per la gestione semplificata dello stato e della UI.
  • Riduzione del codice boilerplate: la libreria riduce la quantità di codice boilerplate ripetitivo offrendo set predefiniti di RemoteActions per casi d'uso comuni, come controlli di riproduzione e azioni di videochiamata.
  • A prova di futuro: altre funzionalità PIP vengono fornite tramite la libreria Jetpack, consentendo agli utenti di accedere a funzionalità aggiuntive con uno sforzo minimo o nullo.

Workflow di migrazione

Identifica la categoria del caso d'uso dell'app e la logica PiP legacy:

Categorie: Riproduzione video, Navigazione o Videochiamata.

Logica PiP legacy da identificare:

  • onUserLeaveHint
  • setAutoEnterEnabled
  • onPictureInPictureModeChanged
  • onPictureInPictureUiStateChanged
  • setPictureInPictureParams.

2. Configurazione di AndroidManifest

Assicurati che l'attività che entra in modalità PIP dichiari il supporto in AndroidManifest.xml con l'configChanges necessario per evitare riavvii non necessari:

<activity
android:name="VideoActivity" android:supportsPictureInPicture="true"
android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation">
</activity>

3. Configurazione dell'ambiente

Aggiungi le dipendenze richieste a build.gradle:

dependencies {
implementation("androidx.core:core:1.18.0")
implementation("androidx.activity:activity:1.13.0")
implementation("androidx.core:core-pip:1.0.0-alpha02") }

Utilizza le librerie AndroidX più recenti per le dipendenze e consulta la pagina Release per queste informazioni.

4. Selezione e inizializzazione del modello

Scegli il modello di implementazione più adatto al caso d'uso dell'app:

  • Navigazione e videochiamata: BasicPictureInPicture; il ridimensionamento continuo in genere non è supportato e non è necessario un suggerimento per il rettangolo di origine.
  • Riproduzione video: VideoPlaybackPictureInPicture; monitora automaticamente i limiti di visualizzazione del player per il suggerimento del rettangolo di origine e consente il ridimensionamento senza problemi per impostazione predefinita.

Per adottare la libreria Jetpack, sostituisci l'implementazione personalizzata della funzionalità PIP esistente con le API della libreria Jetpack. La complessità e il costo dell'adozione varieranno in base all'implementazione attuale dell'app.

Le sezioni seguenti descrivono alcuni dei casi d'uso tipici di PIP e i passaggi di implementazione necessari:

L'app comunica alla libreria lo stato attivo o inattivo della navigazione e imposta le proporzioni. La libreria Jetpack gestisce il resto.

Differenze principali:

  1. Non è necessario distinguere l'inserimento automatico dall'inserimento legacy lato app.
  2. Interfacce di callback consolidate.
  3. Nuovo generatore PictureInPictureParams per la compatibilità con le versioni precedenti.

Videochiamata

L'app comunica alla libreria lo stato attivo o non attivo della chiamata e imposta le proporzioni.

Differenze principali:

  1. Non è necessario distinguere l'inserimento automatico dall'inserimento legacy lato app.
  2. Interfacce di callback consolidate.
  3. Nuovo generatore PictureInPictureParams per la compatibilità con le versioni precedenti.
  4. Icone di azione standardizzate per le videochiamate.

5. Migrazione del codice

  • Entry Logic:sostituisci la logica specifica dell'API, ad esempio setAutoEnterEnabled per Android 12 e versioni successive o onUserLeaveHint per Android 11 e versioni precedenti con setEnabled. Attiva questo evento ogni volta che lo stato di idoneità PIP cambia.
  • Callback:consolida onPictureInPictureModeChanged (attivazione/disattivazione del layout) e onPictureInPictureUiStateChanged (animazione/stati) in un callback unificato basato sugli eventi onPictureInPictureEvent.
  • Azioni e parametri:aggiorna i parametri utilizzando setActions e setAspectRatio nell'istanza del modello ogni volta che cambiano.

Pattern di implementazione di riferimento

Esempi di implementazioni.

Navigazione e videochiamata

class NavOrVideoCallJpipActivity : ComponentActivity(), PictureInPictureDelegate.OnPictureInPictureEventListener {
    private lateinit var pictureInPictureImpl: BasicPictureInPicture
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        pictureInPictureImpl = BasicPictureInPicture(this)
        // BasicPictureInPicture is ideal for Navigation and Video call use cases.
        pictureInPictureImpl.addOnPictureInPictureEventListener(
            ContextCompat.getMainExecutor(this),
            this
        )
        setContent {
        }
    }
    override fun onPictureInPictureEvent(
        event: PictureInPictureDelegate.Event,
        config: Configuration?
    ) {
        when (event) {
            PictureInPictureDelegate.Event.ENTERED -> { /* Toggle to PiP layout */ }
            PictureInPictureDelegate.Event.EXITED -> { /* Toggle to Full-screen layout */ }
            PictureInPictureDelegate.Event.STASHED -> { /* Optional: PiP is stashed */ }
            PictureInPictureDelegate.Event.UNSTASHED -> { /* Optional: PiP is unstashed */ }
        }
    }
}

Riproduzione video

class VideoPlaybackJpipActivity : ComponentActivity(), PictureInPictureDelegate.OnPictureInPictureEventListener {
    private lateinit var pictureInPictureImpl: VideoPlaybackPictureInPicture
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        pictureInPictureImpl = VideoPlaybackPictureInPicture(this)
        pictureInPictureImpl.addOnPictureInPictureEventListener(
            ContextCompat.getMainExecutor(this),
            this
        )
        setContent {
            ContentScreen(pictureInPictureImpl)
        }
    }
    override fun onPictureInPictureEvent(
        event: PictureInPictureDelegate.Event,
        config: Configuration?
    ) {
        when (event) {
            PictureInPictureDelegate.Event.ENTER_ANIMATION_START -> { /* Hide overlays */ }
            PictureInPictureDelegate.Event.ENTER_ANIMATION_END -> { /* Animation finished */ }
            PictureInPictureDelegate.Event.ENTERED -> { /* Switch to PiP layout */ }
            PictureInPictureDelegate.Event.STASHED -> { /* PiP stashed */ }
            PictureInPictureDelegate.Event.UNSTASHED -> { /* PiP unstashed */ }
            PictureInPictureDelegate.Event.EXITED -> { /* Return to full-screen */ }
        }
    }

    @Composable
    fun ContentScreen(pipController: VideoPlaybackPictureInPicture) {
        DisposableEffect(pipController) {
            onDispose {
                pipController.close()
            }
        }
    }
}

Indietro
Aggiungere azioni da remoto a PiP
Avanti
Informazioni sul gesto Indietro predittivo