Serviços em primeiro plano

Os serviços em primeiro plano realizam operações que são perceptíveis pelo usuário.

Os serviços em primeiro plano mostram uma barra de status para informar aos usuários que seus está realizando uma tarefa em primeiro plano e consumindo recursos do sistema.

Exemplos de apps que usam serviços em primeiro plano incluem:

• Um app de reprodução de música que toca músicas em um serviço em primeiro plano. A notificação pode mostrar a música que está tocando no momento.
• Um app fitness registra a corrida de um usuário em um serviço em primeiro plano após recebendo permissão do usuário. A notificação pode mostrar a distância que o usuário percorreu durante a sessão de condicionamento físico atual.

Usar um serviço em primeiro plano apenas quando o app precisar realizar uma tarefa perceptível pelo usuário, mesmo quando ele não está interagindo diretamente com o app. Se a ação for de baixa importância o suficiente para que você queira usar um notificação de prioridade mínima, crie um plano de fundo tarefa.

Observação: para muitos casos de uso, há uma plataforma específica ou API Jetpack que que podem ser usadas para trabalhar em vez de um serviço em primeiro plano. Se houver um API, é quase sempre preferível usá-la em vez de um serviço em primeiro plano. Para mais informações, consulte Usar APIs de uso específico em vez de primeiro plano. e serviços.

Neste documento, descrevemos a permissão necessária para usar os serviços em primeiro plano. e como iniciar um serviço em primeiro plano e removê-lo do segundo plano. Ela também descreve como associar determinados casos de uso a tipos de serviço em primeiro plano; e as restrições de acesso que entram em vigor quando você inicia um serviço em primeiro plano de um app em execução em segundo plano.

O usuário pode dispensar a notificação por padrão

No Android 13 (nível 33 da API), os usuários podem dispensar a notificação associadas a um serviço em primeiro plano por padrão. Para isso, os usuários precisam deslizar na notificação. Tradicionalmente, a notificação não é dispensado, a menos que o serviço em primeiro plano seja interrompido ou removido em primeiro plano.

Se quiser que a notificação não seja dispensável pelo usuário, transmita true no setOngoing() ao criar sua notificação usando Notification.Builder.

Observação: dispositivos com o Android 12 (nível 31 da API) ou versões mais recentes oferecem para serviços em primeiro plano de curta duração. Nesses dispositivos, o sistema aguarda 10 segundos antes de mostrar a notificação associada a um primeiro plano serviço. Há algumas exceções, já que vários tipos de serviços sempre exibir uma notificação imediatamente.

Serviços que mostram uma notificação imediatamente

Se um serviço em primeiro plano tiver pelo menos uma das características a seguir, o sistema mostra a notificação associada imediatamente após o início do serviço, mesmo em dispositivos com o Android 12 ou mais recente:

• O serviço está associado a uma notificação que inclui botões de ação.
• O serviço tem um foregroundServiceType de mediaPlayback, mediaProjection ou phoneCall
• O serviço tem um caso de uso relacionado a chamadas telefônicas, navegação ou reprodução de mídia, conforme definido no atributo de categoria da notificação.
• O serviço desativou a mudança de comportamento transmitindo FOREGROUND_SERVICE_IMMEDIATE para o método setForegroundServiceBehavior() ao configurar a notificação.

No Android 13 (nível 33 da API) ou versões mais recentes, se o usuário negar a permissão para notificações, eles ainda veem avisos relacionados a serviços em primeiro plano no Gerenciador de tarefas mas não as veem na gaveta de notificações.

Declarar serviços em primeiro plano no manifesto

No manifesto do app, declare cada um dos serviços em primeiro plano dele com um <service> . Para cada serviço, use uma Atributo android:foregroundServiceType para declarar o tipo de trabalho que o serviço faz.

Importante: todas as declarações de serviços em primeiro plano precisam obedecer aos requisitos na política contra abuso de dispositivos e de rede do Google Play.

Por exemplo, se o app criar um serviço em primeiro plano que toca música, você pode declarar o serviço assim:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
  <application ...>

    <service
        android:name=".MyMediaPlaybackService"
        android:foregroundServiceType="mediaPlayback"
        android:exported="false">
    </service>
  </application>
</manifest>

Caso os vários tipos se apliquem ao serviço, separe-os com |. usando um operador lógico. Por exemplo, um serviço que usa a câmera e o microfone da seguinte forma:

android:foregroundServiceType="camera|microphone"

Observação:dependendo do nível de API do app, você pode obrigatório para declarar os serviços em primeiro plano no app manifesto do app:

• API de nível 29 ou mais recente:é necessário declarar todas as instâncias serviços que usam informações de localização, usando o location tipo de serviço.
• Nível 30 da API ou mais recente:é necessário declarar todas as instâncias serviços que usam a câmera ou o microfone, usando o camera ou microphone tipo de serviço, respectivamente.
• Nível 34 da API ou mais recente:é necessário declarar todas as instâncias por tipos de serviço.

Se você tentar criar um serviço em primeiro plano e o tipo dele não for declarado no manifesto, o sistema gera uma MissingForegroundServiceTypeException ao chamar startForeground().

Mesmo quando não for obrigatório, é uma prática recomendada declarar todos os serviços em primeiro plano e forneça os tipos de serviço.

Solicitar as permissões de serviço em primeiro plano

Apps direcionados ao Android 9 (nível 28 da API) ou versões mais recentes que usam serviços em primeiro plano você precisa solicitar FOREGROUND_SERVICE no manifesto do app, conforme mostrado no snippet de código a seguir. Esta é uma regra normal permissão para que o sistema a concede automaticamente ao app solicitante.

Além disso, se o aplicativo segmenta o nível de API 34 ou superior, ele deve solicitar o permissão apropriada para o tipo de trabalho que o serviço em primeiro plano vai fazer fazendo. Cada tipo de serviço em primeiro plano tem um tipo de permissão correspondente. Por exemplo, se um app inicia uma serviço em primeiro plano que usa a câmera, é necessário solicitar o FOREGROUND_SERVICE e FOREGROUND_SERVICE_CAMERA permissões. Todas essas permissões são normais, então o sistema as concede automaticamente se estiverem listados no manifesto.

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>

    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA"/>

    <application ...>
        ...
    </application>
</manifest>

Observação :se um app destinado ao nível 28 da API ou mais recente tentar criar uma serviço em primeiro plano sem solicitar a permissão FOREGROUND_SERVICE, o o sistema gera uma SecurityException. Da mesma forma, se um aplicativo segmenta o nível de API 34 ou superior e não solicita a a permissão específica adequada, o sistema vai gerar SecurityException.

Pré-requisitos de serviço em primeiro plano

A partir do Android 14 (nível 34 da API), ao iniciar um serviço em primeiro plano, o sistema verifica os pré-requisitos específicos com base no tipo de serviço. Por exemplo: se você tentar iniciar um serviço em primeiro plano do tipo location, o sistema vai verificar para verificar se o app já tem a ACCESS_COARSE_LOCATION ou ACCESS_FINE_LOCATION. Caso contrário, o sistema gera SecurityException

Por isso, você precisa confirmar que os pré-requisitos necessários foram atendidos. antes de iniciar um serviço em primeiro plano. O serviço em primeiro plano type. lista os pré-requisitos para cada tipo de serviço em primeiro plano.

Iniciar um serviço em primeiro plano

Antes de solicitar que o sistema execute um serviço como um serviço em primeiro plano, comece o serviço em si:

Kotlin

val intent = Intent(...) // Build the intent for the service
context.startForegroundService(intent)

Java

Context context = getApplicationContext();
Intent intent = new Intent(...); // Build the intent for the service
context.startForegroundService(intent);

Dentro do serviço, geralmente em onStartCommand(), é possível solicitar que o serviço é executado em primeiro plano. Para isso, chame ServiceCompat.startForeground() (disponível no androidx-core 1.12 e mais recentes). Esse método recebe o seguinte parâmetros:

• O serviço
• Um número inteiro positivo que identifica exclusivamente a notificação na barra de status.
• O próprio objeto Notification
• Os tipos de serviço em primeiro plano identificando o trabalho feito pelo serviço

Esses tipos podem ser um subconjunto dos tipos declarados no manifesto, dependendo do caso de uso específico. Em seguida, se for preciso adicionar mais tipos de serviço, você pode chamar startForeground() novamente.

Observação: se você transmitir um tipo de serviço em primeiro plano para startForeground que não declarou no manifesto, o sistema gera uma IllegalArgumentException.

Por exemplo, suponha que um aplicativo de condicionamento físico execute um serviço de tracker de corrida que sempre precisa de informações de location, mas pode ou não precisar abrir mídia. Você seria necessário declarar location e mediaPlayback no manifesto. Se um um usuário iniciar uma corrida e só quiser que a localização dele seja rastreada, seu aplicativo deverá chamar startForeground() e transmita apenas a permissão ACCESS_FINE_LOCATION. Depois, Se o usuário quiser começar a tocar áudio, chame startForeground() novamente e transmitir a combinação bit a bit de todos os tipos de serviço em primeiro plano (neste caso, ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK).

Observação: a notificação na barra de status precisa ter uma prioridade de PRIORITY_LOW ou superior. Caso seu app tente usar uma notificação com prioridade mais baixa, o sistema adiciona uma mensagem à gaveta de notificações, alertando o usuário sobre o uso de um serviço em primeiro plano por um app.

Confira um exemplo que inicia um serviço de câmera em primeiro plano:

Kotlin

class MyCameraService: Service() {

  private fun startForeground() {
    // Before starting the service as foreground check that the app has the
    // appropriate runtime permissions. In this case, verify that the user has
    // granted the CAMERA permission.
    val cameraPermission =
            PermissionChecker.checkSelfPermission(this, Manifest.permission.CAMERA)
    if (cameraPermission != PermissionChecker.PERMISSION_GRANTED) {
        // Without camera permissions the service cannot run in the foreground
        // Consider informing user or updating your app UI if visible.
        stopSelf()
        return
    }

    try {
        val notification = NotificationCompat.Builder(this, "CHANNEL_ID")
            // Create the notification to display while the service is running
            .build()
        ServiceCompat.startForeground(
            /* service = */ this,
            /* id = */ 100, // Cannot be 0
            /* notification = */ notification,
            /* foregroundServiceType = */
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA
            } else {
                0
            },
        )
    } catch (e: Exception) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
                && e is ForegroundServiceStartNotAllowedException) {
            // App not in a valid state to start foreground service
            // (e.g. started from bg)
        }
        // ...
    }
  }
}

Java

public class MyCameraService extends Service {

    private void startForeground() {
        // Before starting the service as foreground check that the app has the
        // appropriate runtime permissions. In this case, verify that the user
        // has granted the CAMERA permission.
        int cameraPermission =
            ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA);
        if (cameraPermission == PackageManager.PERMISSION_DENIED) {
            // Without camera permissions the service cannot run in the
            // foreground. Consider informing user or updating your app UI if
            // visible.
            stopSelf();
            return;
        }

        try {
            Notification notification =
                new NotificationCompat.Builder(this, "CHANNEL_ID")
                    // Create the notification to display while the service
                    // is running
                    .build();
            int type = 0;
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                type = ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA;
            }
            ServiceCompat.startForeground(
                    /* service = */ this,
                    /* id = */ 100, // Cannot be 0
                    /* notification = */ notification,
                    /* foregroundServiceType = */ type
            );
        } catch (Exception e) {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S &&
                    e instanceof ForegroundServiceStartNotAllowedException
            ) {
                // App not in a valid state to start foreground service
                // (e.g started from bg)
            }
            // ...
        }
    }

    //...
}

Remover um serviço do primeiro plano

Para remover o serviço do primeiro plano, chame stopForeground() Esse método usa um booleano, que indica se a barra de status será removida a notificação automática. Observe que o serviço continua em execução.

Se você interromper o serviço enquanto estiver em execução em primeiro plano, a notificação é removido.

Processar a interrupção iniciada pelo usuário de apps que executam serviços em primeiro plano

Figura 1. do Gerenciador de tarefas nos dispositivos que executam o Android 13 ou mais recente.

No Android 13 (nível 33 da API), os usuários podem concluir um fluxo de trabalho do gaveta de notificações interromper um app que tenha serviços em primeiro plano em andamento, independentemente da versão do SDK de destino. Essa affordance, chamada de Gerenciador de tarefas, mostra uma lista de apps que estão que estão executando um serviço em primeiro plano.

A lista é identificada como Apps ativos. Ao lado de cada app há um botão Stop. A Figura 1 ilustra o Fluxo de trabalho do gerenciador de tarefas em um dispositivo executado Android 13:

Quando o usuário pressiona o botão Stop ao lado do seu app na Gerenciador de tarefas, as seguintes ações vão ocorrer:

• O sistema remove o app da memória. Assim, todo o app é interrompido, não apenas o serviço em primeiro plano em execução.
• O sistema remove a backstack de atividades do app.
• A reprodução de mídia é interrompida.
• A notificação associada ao serviço em primeiro plano é removida.
• Seu app continua no histórico.
• Os jobs programados são executados no horário programado.
• Os alarmes disparam no horário programado ou na janela de tempo.

.

Observação: o sistema não envia callbacks ao app quando o usuário toca no Botão Parar. Quando o app for reiniciado, vale a pena verificar se há REASON_USER_REQUESTED que faz parte da API ApplicationExitInfo.

Para testar se o app se comporta conforme esperado enquanto e após o usuário interromper a execução. app, execute o seguinte comando ADB em uma janela de terminal:

adb shell cmd activity stop-app PACKAGE_NAME

Isenções

O sistema oferece vários níveis de isenção para determinados tipos de apps, apresentados nas seções abaixo.

As isenções são aplicadas por app, e não por processo. Se o sistema isentar um processo em um app, todos os outros processos nesse app também vão ser isentos.

Observação: alguns apps pré-instalados configurados pelo fabricante também podem ser isento.

Isenções de exibição no gerenciador de tarefas

Os seguintes apps podem executar um serviço em primeiro plano e não aparecem na Gerenciador de tarefas:

• Apps do sistema
• Apps de segurança: ou seja, apps que têm o papel ROLE_EMERGENCY
• Apps em dispositivos no modo de demonstração

Isenções para que o app não possa ser interrompido pelo usuário

Quando os seguintes tipos de apps executam um serviço em primeiro plano, eles aparecem na do Gerenciador de Tarefas, mas não há um botão Stop ao lado do nome do app para o usuário tocar:

• Apps do proprietário do dispositivo
• Apps do proprietário do perfil
• Apps persistentes
• Apps que têm o papel ROLE_DIALER

Use APIs de uso específico em vez de serviços em primeiro plano

Para muitos casos de uso, existem APIs de plataforma ou Jetpack que você pode usar para trabalhar em que um serviço em primeiro plano poderia ser usado. Se houver um específica, use-a quase sempre em vez de uma em primeiro plano serviço. As APIs criadas para fins específicos muitas vezes oferecem mais instruções específicas para cada caso de uso recursos que você teria que desenvolver por conta própria. Por exemplo: a API Bubbles lida com a lógica complexa da IU para: aplicativos de mensagens que precisam implementar recursos de balão de chat.

A documentação das listas de tipos de serviço em primeiro plano e boas alternativas para usar em vez dos serviços em primeiro plano.

Restrições para iniciar um serviço em primeiro plano em segundo plano

Apps direcionados ao Android 12 ou versões mais recentes não podem iniciar em primeiro plano serviços enquanto o aplicativo está em execução em segundo plano, com exceção de algumas casos de uso diferentes. Se um app tentar iniciar serviço em primeiro plano enquanto o app é executado em segundo plano e em primeiro plano serviço não atender a um dos casos excepcionais, o sistema lança uma ForegroundServiceStartNotAllowedException

Observação: se um app chamar Context.startForegroundService() para iniciar uma serviço em primeiro plano que pertence a outro app, essas restrições se aplicam somente se os dois apps são direcionados ao Android 12 ou versões mais recentes.

Além disso, se um app quiser lançar um serviço em primeiro plano que precisa permissões durante o uso (por exemplo, sensor corporal, câmera, microfone ou localização permissões), ele não poderá criar o serviço enquanto o aplicativo estiver em segundo plano. mesmo que o app se enquadre em uma das isenções de inicialização em segundo plano restrições. O motivo é explicado na seção Restrições relativas a iniciar serviços em primeiro plano que precisam estar em uso do Google Cloud.

Isenções de restrições de início em segundo plano

Nas situações a seguir, o app pode iniciar serviços em primeiro plano mesmo enquanto seu app for executado em segundo plano:

• O app estava em um estado visível para o usuário, como uma atividade.
• O app pode iniciar uma atividade do segundo plano, exceto quando o app tem uma atividade na backstack para uma tarefa existente.

• Seu app recebe uma mensagem de alta prioridade usando o Firebase Cloud Mensagens.

  Observação:o sistema pode fazer downgrade de itens de alta prioridade prioridade normal se o app não estiver usando as mensagens de alta prioridade para exibir conteúdo sensível ao tempo para o usuário. Se a prioridade da mensagem for sofreu downgrade, o app não pode iniciar um serviço em primeiro plano e tentar iniciá-lo uma delas resulta em um ForegroundServiceStartNotAllowedException

  Por isso, é recomendável verificar o resultado RemoteMessage.getPriority() e confirmar PRIORITY_HIGH() antes de tentar iniciar um serviço em primeiro plano. Para orientações sobre alta prioridade e quando usá-las, consulte FCM's documentation

• O usuário realiza uma ação em um elemento da IU relacionado ao app. Por exemplo, o usuário pode interagir com um balão, uma notificação, um widget ou uma atividade.

• Seu app invoca um alarme exato para para concluir uma ação solicitada pelo usuário.

• Seu aplicativo é a entrada atual do dispositivo método.

• O app recebe um evento relacionado à fronteira geográfica virtual ou à transição de reconhecimento de atividade.

• Após o dispositivo ser reiniciado e receber a ação da intent ACTION_BOOT_COMPLETED, ACTION_LOCKED_BOOT_COMPLETED ou ACTION_MY_PACKAGE_REPLACED em um broadcast receiver.

• O app recebe a ação da intent ACTION_TIMEZONE_CHANGED, ACTION_TIME_CHANGED ou ACTION_LOCALE_CHANGED em um broadcast receiver.

• Seu app recebe ACTION_TRANSACTION_DETECTED evento de NfcService.

• Apps com determinados papéis ou permissões do sistema, como proprietários de dispositivo e proprietários de perfil.

• O app usa o Gerenciador de dispositivos complementar e declara a REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND ou a REQUEST_COMPANION_RUN_IN_BACKGROUND permissão. Sempre que possível, use REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND:

• Seu app tem o SYSTEM_ALERT_WINDOW permissão.

• o usuário desativar as otimizações de bateria do app.

Restrições para a inicialização de serviços em primeiro plano que precisam de permissões durante o uso

No Android 14 (nível 34 da API) ou versões mais recentes, há situações especiais se você estiver iniciando um serviço em primeiro plano que precisa de permissões durante o uso.

Caso o app seja destinado ao Android 14 ou versões mais recentes, o sistema operacional quando você cria um serviço em primeiro plano, para conferir se o app tem as permissões apropriadas para esse tipo de serviço. Por exemplo, quando você cria serviço em primeiro plano do tipo microphone, o sistema o sistema verifica se o app tem RECORD_AUDIO permissão. Se você não tiver essa permissão, o sistema gerará uma SecurityException

Para permissões em uso, isso causa um possível problema. Se o app tiver um durante o uso, ele só tem essa permissão enquanto está no primeiro plano. Isso significa que, se seu app estiver em segundo plano e tentar criar um serviço em primeiro plano do tipo câmera, localização ou microfone, o sistema vê de que o app não no momento tem as permissões necessárias e uma SecurityException

Da mesma forma, se seu app estiver em segundo plano e criar um serviço de saúde que precisa da permissão BODY_SENSORS_BACKGROUND, o app não possui essa permissão no momento e o sistema gerará uma exceção. Isso não se aplica a serviços de saúde que precisam de permissões diferentes. como ACTIVITY_RECOGNITION. Ligar PermissionChecker.checkSelfPermission() não evita esse problema. Se o app tiver uma permissão durante o uso. ele chamará checkSelfPermission() para verificar se tem essa permissão, o método retorna PERMISSION_GRANTED mesmo que o app esteja em segundo plano. Quando o retorna PERMISSION_GRANTED, "seu app tem essa permissão" enquanto o app está em uso".

Observação: em versões anteriores ao Android 14, se você tentei criar uma serviço em primeiro plano que precisava de permissões durante o uso do app em segundo plano, o sistema permitiria que você criasse o serviço, mas ele não teriam acesso aos recursos necessários e, se tentassem usá-los, conseguir uma exceção. No Android 14 ou em versões mais recentes, o app recebe a assim que ele tenta criar o serviço em primeiro plano.

Por esse motivo, se o serviço em primeiro plano precisar de uma permissão durante o uso, precisa chamar Context.startForegroundService() ou Context.bindService() enquanto seu app tiver uma atividade visível, a menos que o serviço se enquadre em um dos isenções definidas.

Isenções de restrições de permissões em uso

Em algumas situações, mesmo que um serviço em primeiro plano seja iniciado enquanto o app executa em segundo plano, ele ainda poderá acessar a localização, informações da câmera e do microfone enquanto o app é executado em primeiro plano ("durante o uso").

Nessas mesmas situações, se o serviço declarar um tipo de serviço em primeiro plano de location e iniciado por um app que tem o ACCESS_BACKGROUND_LOCATION permissão, esse serviço pode acessar informações de localização o tempo todo, mesmo quando que o app seja executado em segundo plano.

A lista a seguir contém essas situações:

• Um componente do sistema inicia o serviço.
• O serviço começa interagindo com o app widgets.
• O serviço começa interagindo com uma notificação.
• O serviço começa como um PendingIntent, que é enviado por um diferente e visível.
• O serviço é iniciado por um app que é uma política de dispositivo controlador que é executado no modo de proprietário do dispositivo.
• O serviço é iniciado por um app que fornece o VoiceInteractionService.
• O serviço é iniciado por um app que tem a Permissão privilegiada START_ACTIVITIES_FROM_BACKGROUND.

Determinar quais serviços são afetados no seu app

Ao testar seu app, inicie os serviços em primeiro plano. Se um serviço iniciado tiver acesso restrito à localização, ao microfone e à câmera, a seguinte mensagem será exibida no Logcat:

Foreground service started from background can not have \
location/camera/microphone access: service SERVICE_NAME