O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Compatibilidade com o modo picture-in-picture

O Android 8.0 (API de nível 26) permite iniciar atividades no modo picture-in-picture (PIP). PIP é um tipo especial de modo de várias janelas usado principalmente para reprodução de vídeos. Ele permite que o usuário assista a um vídeo em uma janela pequena fixada em um canto da tela enquanto navega entre apps ou pelo conteúdo na tela principal.

O modo PIP aproveita as APIs de várias janelas disponíveis no Android 7.0 para fornecer a janela fixa de sobreposição de vídeo. Para adicionar o modo PIP ao seu app, você precisa registrar suas atividades compatíveis com esse modo, alternar sua atividade para ele conforme necessário e verificar se os elementos da IU estão ocultos e se a reprodução continua quando a atividade está no modo PIP.

A janela do modo PIP é exibida na camada superior da tela, em um canto definido pelo sistema. É possível arrastar a janela do modo PIP para outro local. Quando você toca nessa janela, dois controles especiais aparecem: um botão de alternância de tela cheia (no centro da janela) e um botão para fechar (um “X” no canto superior direito).

Seu app controla quando a atividade atual entra no modo PIP. Veja alguns exemplos:

  • Uma atividade pode entrar no modo PIP quando o usuário toca nos botões "Início" ou "Recentes" para escolher outro app. É assim que o Google Maps continua exibindo rotas enquanto o usuário executa outra atividade ao mesmo tempo.
  • Seu app pode colocar um vídeo no modo PIP quando o usuário sai do vídeo para procurar outro conteúdo.
  • O app pode alternar um vídeo para o modo PIP enquanto um usuário assiste o final de um episódio de conteúdo. A tela principal exibe informações promocionais ou resumidas sobre o próximo episódio da série.
  • Seu app pode oferecer uma forma de os usuários colocarem outros conteúdos em fila enquanto assistem um vídeo. O vídeo continuará sendo reproduzido no modo PIP enquanto a tela principal exibe uma atividade de seleção de conteúdo.

Como declarar compatibilidade com o modo picture-in-picture

Por padrão, o sistema não é automaticamente compatível com o modo PIP para apps. Se você quiser a oferecer compatibilidade com o modo PIP no seu app, registre a atividade de vídeo no seu manifesto configurando android:supportsPictureInPicture como true. Especifique também que sua atividade gerencia as mudanças de configuração de layout para que ela não seja reiniciada quando essas mudanças ocorrerem durante as transições do modo PIP.

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

Como alternar sua atividade para o modo picture-in-picture

Para entrar no modo picture-in-picture, as atividades precisam chamar enterPictureInPictureMode(). Por exemplo, o código a seguir alterna uma atividade para o modo PIP quando o usuário clica em um botão dedicado a isso na IU do app.

Kotlin

override fun onActionClicked(action: Action) {
    if (action.id.toInt() == R.id.lb_control_picture_in_picture) {
        activity?.enterPictureInPictureMode()
        return
    }
}

Java

@Override
public void onActionClicked(Action action) {
    if (action.getId() == R.id.lb_control_picture_in_picture) {
        getActivity().enterPictureInPictureMode();
        return;
    }
    ...
}

Recomendamos que você inclua uma lógica que alterna uma atividade para o modo PIP em vez de colocá-la em segundo plano. Por exemplo, o Google Maps alterna para o modo PIP se o usuário pressiona o botão "Início" ou "Recentes" enquanto o app está navegando. Use esse caso modificando onUserLeaveHint():

Kotlin

override fun onUserLeaveHint() {
    if (iWantToBeInPipModeNow()) {
        enterPictureInPictureMode()
    }
}

Java

@Override
public void onUserLeaveHint () {
    if (iWantToBeInPipModeNow()) {
        enterPictureInPictureMode();
    }
}

Como gerenciar a IU no modo picture-in-picture

Quando a atividade entra ou sai do modo picture-in-picture, o sistema chama Activity.onPictureInPictureModeChanged() ou Fragment.onPictureInPictureModeChanged().

Modifique esses callbacks para redesenhar os elementos de IU da atividade. Lembre-se de que sua atividade é exibida em uma pequena janela no modo PIP. Os usuários não podem interagir com os elementos da IU quando estiverem no modo PIP, e a visualização dos detalhes de elementos pequenos pode ser difícil. As atividades de reprodução de vídeo com IU mínima proporcionam a melhor experiência do usuário. A atividade precisará mostrar apenas os controles de reprodução. Remova outros elementos da IU antes de sua atividade entrar no modo PIP e restaure-os quando ela voltar à tela cheia:

Kotlin

override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean,
                                           newConfig: Configuration) {
    if (isInPictureInPictureMode) {
        // Hide the full-screen UI (controls, etc.) while in picture-in-picture mode.
    } else {
        // Restore the full-screen UI.
    }
}

Java

@Override
public void onPictureInPictureModeChanged (boolean isInPictureInPictureMode, Configuration newConfig) {
    if (isInPictureInPictureMode) {
        // Hide the full-screen UI (controls, etc.) while in picture-in-picture mode.
    } else {
        // Restore the full-screen UI.
        ...
    }
}

Como adicionar controles

A janela do modo PIP pode exibir controles quando o usuário abre o menu da janela, tocando nela em um dispositivo móvel ou selecionando o menu no controle remoto da TV.

Se um app tiver uma sessão de mídia ativa, os controles de tocar, pausar, próxima e anterior serão exibidos.

Também é possível especificar ações personalizadas de forma explícita criando PictureInPictureParams com PictureInPictureParams.Builder.setActions() antes de entrar no modo PIP, além de transmitir os parâmetros ao entrar nesse modo usando enterPictureInPictureMode(android.app.PictureInPictureParams) ou setPictureInPictureParams(android.app.PictureInPictureParams). Tenha cuidado. Se você tentar adicionar mais do que getMaxNumPictureInPictureActions(), conseguirá apenas o número máximo.

Como continuar a reprodução de vídeo no modo picture-in-picture

Quando sua atividade alterna para o modo PIP, o sistema coloca a atividade no estado pausado e chama o método onPause() da atividade. A reprodução do vídeo não será pausada e continuará se a atividade for pausada no modo PIP.

No Android 7.0 e versões mais recentes, pause e retome a reprodução do vídeo quando o sistema chamar o onStop() e onStart() da atividade. Ao fazer isso, você evita a necessidade de verificar se o app está no modo PIP em onPause() e continua a reprodução de forma explícita.

Se você tiver que pausar a reprodução na sua implementação de onPause(), verifique o modo PIP chamando isInPictureInPictureMode() e gerencie a reprodução adequadamente, por exemplo:

Kotlin

override fun onPause() {
    super.onPause()
    // If called while in PIP mode, do not pause playback
    if (isInPictureInPictureMode) {
        // Continue playback
    } else {
        // Use existing playback logic for paused Activity behavior.
    }
}

Java

@Override
public void onPause() {
    // If called while in PIP mode, do not pause playback
    if (isInPictureInPictureMode()) {
        // Continue playback
        ...
    } else {
        // Use existing playback logic for paused Activity behavior.
        ...
    }
}

Quando a atividade sai do modo PIP e volta ao modo de tela cheia, o sistema retoma sua atividade e chama seu método onResume().

Como usar uma única atividade de reprodução para o picture-in-picture

No seu app, um usuário pode selecionar um novo vídeo ao navegar pelo conteúdo na tela principal, enquanto uma atividade de reprodução de vídeo estiver no modo PIP. Abra o novo vídeo na atividade de reprodução já existente no modo de tela cheia em vez de iniciar uma nova atividade que poderia confundir o usuário.

Para garantir que uma única atividade seja usada para solicitações de reprodução de vídeo e ativada ou desativada no modo PIP, defina o android:launchMode da atividade como singleTask no seu manifesto:

<activity android:name="VideoActivity"
    ...
    android:supportsPictureInPicture="true"
    android:launchMode="singleTask"
    ...

Na sua atividade, substitua onNewIntent() e gerencie o novo vídeo, interrompendo qualquer reprodução de vídeo já existente, se necessário.

Práticas recomendadas

O modo PIP pode ser desativado em dispositivos com pouca RAM. Antes que seu app use o modo PIP, confira se ele está disponível chamando hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE).

O PIP é destinado a atividades que exibem vídeos em tela cheia. Ao mudar sua atividade para o modo PIP, evite exibir conteúdo que não seja de vídeo. Rastreie quando sua atividade entra no modo PIP e oculte elementos da IU, conforme descrito em Como gerenciar a IU no modo picture-in-picture.

Considerando que a janela do modo PIP é mostrada como uma janela flutuante no canto da tela, evite mostrar informações importantes na tela principal em qualquer área que possa ser obstruída pela janela do PIP.

Quando uma atividade está no modo PIP, por padrão, ela não recebe o foco de entrada. Para receber eventos de entrada no modo PIP, use MediaSession.setCallback(). Para ver mais informações sobre o uso de setCallback(), consulte Exibir um card "Tocando agora".

Quando seu app estiver no modo PIP, a reprodução de vídeo na janela do PIP poderá causar interferência de áudio com outro app, como um de player de música ou de pesquisa por voz. Para evitar isso, solicite a seleção de áudio quando iniciar o vídeo e gerencie as notificações para mudança de seleção de áudio, como descrito em Como gerenciar a seleção de áudio. Se você receber uma notificação sobre perda de seleção de áudio quando estiver no modo PIP, pause ou pare a reprodução do vídeo.

Quando seu app estiver prestes a entrar no PIP, apenas a atividade superior entrará nesse modo. Em algumas situações, como em dispositivos com várias janelas, é possível que a atividade abaixo seja exibida e se torne visível novamente junto com a atividade do modo PIP. Gerencie esse caso adequadamente, incluindo a atividade abaixo, que recebe um callback onResume() ou onPause(). Também é possível que o usuário interaja com a atividade. Por exemplo, se uma atividade de lista de vídeos estiver sendo exibida, e a atividade de reprodução de vídeo estiver no modo PIP, o usuário poderá selecionar um novo vídeo da lista, e essa atividade será atualizada de acordo.

Outro exemplo de código

Para fazer o download de um app de exemplo criado no Android, consulte a Amostra picture-in-picture (link em inglês). Para fazer o download de um app de amostra criado em Kotlin, consulte Amostra PictureInPicture do Android (Kotlin) (link em inglês).