Visão geral da biblioteca Telecom

O framework do Android Telecom, também conhecido apenas como "Telecomunicações", gerencia chamadas de áudio e vídeo em um dispositivo Android. Isso inclui chamadas baseadas em chip, como as que usam o framework de telefonia, e chamadas VoIP que implementam a API ConnectionService.

Os principais componentes que a empresa de telecomunicações gerencia são ConnectionService e InCallService.

Uma implementação de ConnectionService usa tecnologias como VoIP para conectar chamadas a outras partes. A implementação de ConnectionService mais comum em um smartphone é a ConnectionService de telefonia. Conecta-se às chamadas pela operadora.

Uma implementação de InCallService fornece uma interface do usuário para chamadas gerenciadas por telecomunicações e permite que o usuário controle e interaja com essas chamadas. A implementação mais comum de um InCallService é o app para smartphones que acompanha um dispositivo.

A telecomunicação funciona como uma central telefônica. Ele encaminha chamadas que as implementações de ConnectionService fornecem para as interfaces de usuário de chamada fornecidas pelas implementações de InCallService.

Convém implementar as APIs Telecom pelos seguintes motivos:

Criar um app telefone substituto

Para criar um substituto para o app para smartphones padrão em um dispositivo Android, implemente a API InCallService. A implementação precisa atender aos seguintes requisitos:

  • Ela não pode ter nenhum recurso de chamada e precisa consistir apenas na interface do usuário para chamadas.
  • Ele precisa processar todas as chamadas de que o framework de telecomunicações está ciente e não fazer suposições sobre a natureza delas. Por exemplo, ele não pode presumir que as chamadas sejam de telefonia baseada em chip nem implementar restrições de chamada baseadas em qualquer ConnectionService, como a aplicação de restrições de telefonia para videochamadas.

Para saber mais, consulte InCallService.

Integrar uma solução de chamada

Para integrar sua solução de chamada ao Android, você tem as seguintes opções:

  • Implemente a API ConnectionService autogerenciada:essa opção é ideal para desenvolvedores de apps de chamadas independentes que não querem mostrar as chamadas no app de telefone padrão nem mostrar outras chamadas na interface do usuário.

    Ao usar uma ConnectionService autogerenciada, você ajuda o app a interoperar não apenas com as chamadas de telefonia nativas no dispositivo, mas também com outros apps de chamada autônomos que implementam essa API. A API ConnectionService autogerenciada também gerencia o roteamento e a seleção de áudio. Para saber mais, consulte Criar um app de chamadas.

  • Implementar a API ConnectionService gerenciado: essa opção facilita o desenvolvimento de uma solução de chamada que depende do aplicativo de telefone do dispositivo atual para fornecer a interface do usuário para chamadas. Os exemplos incluem uma implementação de terceiros de serviços de chamada SIP e voIP. Para ver mais detalhes, consulte getDefaultDialerPackage().

    Uma ConnectionService fornece apenas os meios de conectar chamadas. Ele não tem uma interface do usuário associada.

  • Implementar as APIs InCallService e ConnectionService: essa opção é ideal se você quer criar sua própria solução de chamadas baseada em ConnectionService, completa com uma interface do usuário própria, além de mostrar todas as outras chamadas do Android na mesma interface do usuário. Ao usar essa abordagem, sua implementação de InCallService não pode fazer suposições sobre as origens das chamadas exibidas. Além disso, sua implementação de ConnectionService precisa continuar funcionando sem que o app para smartphones padrão esteja definido como sua InCallService personalizada.

Filtrar chamadas

Dispositivos com o Android 10 (nível 29 da API) ou versões mais recentes permitem que o app identifique chamadas de números que não estão no catálogo de endereços do usuário como possíveis chamadas de spam. Os usuários podem rejeitar chamadas de spam silenciosamente. Para oferecer maior transparência aos usuários quando eles perdem chamadas, as informações sobre essas chamadas bloqueadas são registradas no registro de chamadas. O uso da API do Android 10 elimina a necessidade de receber a permissão READ_CALL_LOG do usuário para fornecer os recursos de filtro de ligações e identificador de chamadas.

Use uma implementação de CallScreeningService para filtrar chamadas. Chame a função onScreenCall() para todas as novas chamadas recebidas ou realizadas quando o número não estiver na lista de contatos do usuário. Você pode verificar o objeto Call.Details para ver informações sobre a chamada. Especificamente, a função getCallerNumberVerificationStatus() inclui informações da provedora de rede sobre o outro número. Se o status de verificação falhou, essa é uma boa indicação de que a chamada é de um número inválido ou uma possível chamada de spam.

Kotlin

class ScreeningService : CallScreeningService() {
    // This function is called when an ingoing or outgoing call
    // is from a number not in the user's contacts list
    override fun onScreenCall(callDetails: Call.Details) {
        // Can check the direction of the call
        val isIncoming = callDetails.callDirection == Call.Details.DIRECTION_INCOMING

        if (isIncoming) {
            // the handle (e.g. phone number) that the Call is currently connected to
            val handle: Uri = callDetails.handle

            // determine if you want to allow or reject the call
            when (callDetails.callerNumberVerificationStatus) {
                Connection.VERIFICATION_STATUS_FAILED -> {
                    // Network verification failed, likely an invalid/spam call.
                }
                Connection.VERIFICATION_STATUS_PASSED -> {
                    // Network verification passed, likely a valid call.
                }
                else -> {
                    // Network could not perform verification.
                    // This branch matches Connection.VERIFICATION_STATUS_NOT_VERIFIED.
                }
            }
        }
    }
}

Java

class ScreeningService extends CallScreeningService {
    @Override
    public void onScreenCall(@NonNull Call.Details callDetails) {
        boolean isIncoming = callDetails.getCallDirection() == Call.Details.DIRECTION_INCOMING;

        if (isIncoming) {
            Uri handle = callDetails.getHandle();

            switch (callDetails.getCallerNumberVerificationStatus()) {
                case Connection.VERIFICATION_STATUS_FAILED:
                    // Network verification failed, likely an invalid/spam call.
                    break;
                case Connection.VERIFICATION_STATUS_PASSED:
                    // Network verification passed, likely a valid call.
                    break;
                default:
                    // Network could not perform verification.
                    // This branch matches Connection.VERIFICATION_STATUS_NOT_VERIFIED
            }
        }
    }
}

Defina a função onScreenCall() para chamar respondToCall() e informar ao sistema como responder à nova chamada. Essa função recebe um parâmetro CallResponse que pode ser usado para instruir o sistema a bloquear a chamada, rejeitá-la como se o usuário tivesse feito isso ou silenciá-la. Também é possível dizer ao sistema para pular completamente a adição dessa chamada ao registro de chamadas do dispositivo.

Kotlin

// Tell the system how to respond to the incoming call
// and if it should notify the user of the call.
val response = CallResponse.Builder()
    // Sets whether the incoming call should be blocked.
    .setDisallowCall(false)
    // Sets whether the incoming call should be rejected as if the user did so manually.
    .setRejectCall(false)
    // Sets whether ringing should be silenced for the incoming call.
    .setSilenceCall(false)
    // Sets whether the incoming call should not be displayed in the call log.
    .setSkipCallLog(false)
    // Sets whether a missed call notification should not be shown for the incoming call.
    .setSkipNotification(false)
    .build()

// Call this function to provide your screening response.
respondToCall(callDetails, response)

Java

// Tell the system how to respond to the incoming call
// and if it should notify the user of the call.
CallResponse.Builder response = new CallResponse.Builder();
// Sets whether the incoming call should be blocked.
response.setDisallowCall(false);
// Sets whether the incoming call should be rejected as if the user did so manually.
response.setRejectCall(false);
// Sets whether ringing should be silenced for the incoming call.
response.setSilenceCall(false);
// Sets whether the incoming call should not be displayed in the call log.
response.setSkipCallLog(false);
// Sets whether a missed call notification should not be shown for the incoming call.
response.setSkipNotification(false);

// Call this function to provide your screening response.
respondToCall(callDetails, response.build());

É necessário registrar a implementação CallScreeningService no arquivo de manifesto com o filtro de intent e a permissão adequados para que o sistema possa acioná-lo corretamente.

<service
    android:name=".ScreeningService"
    android:permission="android.permission.BIND_SCREENING_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.CallScreeningService" />
    </intent-filter>
</service>

Redirecionar uma chamada

Dispositivos com o Android 10 ou versões mais recentes gerenciam as intents de chamada de forma diferente dos dispositivos com o Android 9 ou versões anteriores. No Android 10 e versões mais recentes, a transmissão ACTION_NEW_OUTGOING_CALL foi descontinuada e substituída pela API CallRedirectionService. O CallRedirectionService fornece interfaces para você usar para modificar chamadas realizadas pela plataforma Android. Por exemplo, apps de terceiros podem cancelar chamadas e redirecioná-las por VoIP.

Kotlin

class RedirectionService : CallRedirectionService() {
    override fun onPlaceCall(
        handle: Uri,
        initialPhoneAccount: PhoneAccountHandle,
        allowInteractiveResponse: Boolean
    ) {
        // Determine if the call should proceed, be redirected, or cancelled.
        val callShouldProceed = true
        val callShouldRedirect = false
        when {
            callShouldProceed -> {
                placeCallUnmodified()
            }
            callShouldRedirect -> {
                // Update the URI to point to a different phone number or modify the
                // PhoneAccountHandle and redirect.
                redirectCall(handle, initialPhoneAccount, true)
            }
            else -> {
                cancelCall()
            }
        }
    }
}

Java

class RedirectionService extends CallRedirectionService {
    @Override
    public void onPlaceCall(
            @NonNull Uri handle,
            @NonNull PhoneAccountHandle initialPhoneAccount,
            boolean allowInteractiveResponse
    ) {
        // Determine if the call should proceed, be redirected, or cancelled.
        // Your app should implement this logic to determine the redirection.
        boolean callShouldProceed = true;
        boolean callShouldRedirect = false;
        if (callShouldProceed) {
            placeCallUnmodified();
        } else if (callShouldRedirect) {
            // Update the URI to point to a different phone number or modify the
            // PhoneAccountHandle and redirect.
            redirectCall(handle, initialPhoneAccount, true);
        } else {
            cancelCall();
        }
    }
}

Você precisa registrar esse serviço no manifesto para que o sistema possa iniciá-lo corretamente.

<service
    android:name=".RedirectionService"
    android:permission="android.permission.BIND_CALL_REDIRECTION_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.CallRedirectionService"/>
    </intent-filter>
</service>

Para usar um serviço de redirecionamento, seu app precisa solicitar o papel de redirecionamento de chamadas do RoleManager. Isso vai perguntar ao usuário se ele quer permitir que seu app processe redirecionamentos de chamada. Se o app não receber esse papel, o serviço de redirecionamento não será usado.

É necessário verificar se o app tem esse papel quando o usuário o inicia para que você possa solicitá-lo conforme necessário. Inicie uma intent criada pelo RoleManager. Portanto, substitua a função onActivityResult() para processar a seleção do usuário.

Kotlin

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Tell the system that you want your app to handle call redirects. This
        // is done by using the RoleManager to register your app to handle redirects.
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.Q) {
            val roleManager = getSystemService(Context.ROLE_SERVICE) as RoleManager
            // Check if the app needs to register call redirection role.
            val shouldRequestRole = roleManager.isRoleAvailable(RoleManager.ROLE_CALL_REDIRECTION) &&
                    !roleManager.isRoleHeld(RoleManager.ROLE_CALL_REDIRECTION)
            if (shouldRequestRole) {
                val intent = roleManager.createRequestRoleIntent(RoleManager.ROLE_CALL_REDIRECTION)
                startActivityForResult(intent, REDIRECT_ROLE_REQUEST_CODE)
            }
        }
    }

    companion object {
        private const val REDIRECT_ROLE_REQUEST_CODE = 1
    }
}

Java

class MainActivity extends AppCompatActivity {
    private static final int REDIRECT_ROLE_REQUEST_CODE = 0;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Tell the system that you want your app to handle call redirects. This
        // is done by using the RoleManager to register your app to handle redirects.
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.Q) {
            RoleManager roleManager = (RoleManager) getSystemService(Context.ROLE_SERVICE);
            // Check if the app needs to register call redirection role.
            boolean shouldRequestRole = roleManager.isRoleAvailable(RoleManager.ROLE_CALL_REDIRECTION) &&
                    !roleManager.isRoleHeld(RoleManager.ROLE_CALL_REDIRECTION);
            if (shouldRequestRole) {
                Intent intent = roleManager.createRequestRoleIntent(RoleManager.ROLE_CALL_REDIRECTION);
                startActivityForResult(intent, REDIRECT_ROLE_REQUEST_CODE);
            }
        }
    }
}