Histórico de ligações unificado

Os aplicativos VoIP podem integrar as chamadas ao registro de chamadas do sistema. Isso permite que os usuários vejam o histórico de ligações VoIP centralmente no app Telefone do sistema e retornem chamadas diretamente do app Telefone. Este guia descreve as mudanças necessárias em apps de chamadas VoIP, apps Telefone do sistema e gerenciamento de configurações de histórico de ligações unificado.

Mudanças no app de ligações

Para integrar seu app VoIP ao registro de chamadas do sistema, siga estas etapas.

Registrar filtro de intent de callback

Registre a intent protegida pelo sistema TelecomManager.ACTION_CALL_BACK.

Depois que esse filtro de intent for registrado corretamente, todas as chamadas que seu app adicionar usando CallsManager.addCall ou outras APIs Telecom relacionadas serão registradas automaticamente pelo sistema. O sistema usa essa intent registrada para enviar um callback ao seu app quando um usuário seleciona uma entrada de registro de chamadas VoIP no discador para retornar a ligação.

<!-- Activity to handle the callback intent from the system dialer -->
<activity
    android:name=".VoipCallActivity"
    android:exported="true">

    <!-- Register callback intent -->
    <intent-filter>
        <action android:name="android.telecom.action.CALL_BACK" />
    </intent-filter>
</activity>

Excluir geração de registros de chamadas

Depois que o callback é registrado, todas as chamadas são registradas no discador do sistema. Para excluir chamadas individualmente, defina o booleano isLogExcluded como true em CallAttributesCompat.

CallAttributesCompat(
    displayName = displayName,
    address = address,
    isLogExcluded = excludeCallLogging, // to exclude call from logging
    direction = if (isIncoming) {
        CallAttributesCompat.DIRECTION_INCOMING
    } else {
        CallAttributesCompat.DIRECTION_OUTGOING
    },
    callType = CallAttributesCompat.CALL_TYPE_AUDIO_CALL,
    callCapabilities = (
        CallAttributesCompat.SUPPORTS_SET_INACTIVE
            or CallAttributesCompat.SUPPORTS_STREAM
            or CallAttributesCompat.SUPPORTS_TRANSFER
        ),
)

Processar callbacks

As chamadas adicionadas por CallsManager.addCall recebem um UUID exclusivo por CallControlScope.getCallId.

// check the intent action for CALL_BACK
if (intent.action == TelecomManager.ACTION_CALL_BACK) {
    launchCall(
        // fetching stored call details for the UUID to initiate callback
        callDetails = getCallDetails(
            uuid = intent.getStringExtra(TelecomManager.EXTRA_UUID)
        )
    )
}

Verificar entradas de registro de chamadas

O registro de chamadas do sistema mantém um número finito de entradas e, eventualmente, exclui registros de chamadas antigos. Como o app armazena um mapeamento de UUIDs para detalhes de chamada para processamento de callback, ele precisa verificar periodicamente quais UUIDs ainda estão presentes no registro de chamadas do sistema. Se um UUID não estiver mais no registro do sistema, o usuário não poderá iniciar um callback para essa chamada, e o app poderá remover o mapeamento do armazenamento local com segurança. Essa prática ajuda a otimizar o armazenamento.

Para receber a lista atual de UUIDs atribuídos ao app no registro do sistema, use CallLog.Calls.CONTENT_VOIP_URI.

Mudanças no app Telefone

Siga estas etapas para permitir que o app discador mostre registros de chamadas VoIP e inicie retornos de chamada para apps VoIP.

Mostrar registros de chamadas VoIP no app discador

Por padrão, os registros de chamadas de apps VoIP não aparecem no app discador. Para mostrar os registros de chamadas integrados no app discador, faça o seguinte:

  • No Android 16.1 (nível 36.1 da API), adicione o parâmetro de consulta include_voip_calls ao provedor de conteúdo CallLog.Calls para mostrar os registros de chamadas VoIP:

    CallLog.Calls.CONTENT_URI.buildUpon()
    .appendQueryParameter("include_voip_calls", "true")
    .build()

  • No Android 17 (nível 37 da API) e versões mais recentes, use o seguinte provedor de conteúdo e chave de parâmetro formalizados:

Iniciar retornos de chamada no app Telefone

Para iniciar um retorno de chamada de um discador, use TelecomManager.placeCall. A plataforma usa o CallLog.Calls._ID exclusivo da entrada de registro de chamadas para iniciar o app VoIP correto. Esse início inclui uma intent TelecomManager.ACTION_CALL_BACK, que é uma ação definida pelo sistema para iniciar uma ligação de retorno. Essa intent contém o UUID da chamada no extra da intent TelecomManager.EXTRA_UUID, permitindo que o app VoIP identifique qual chamada específica está sendo retornada.

// Uri generated with unique ID of the call log entry to launch the respective VoIP app for callback
val address = ContentUris.withAppendedId(CallLog.Calls.CONTENT_URI, callId)

// extra information required to initiate callback
val extras = Bundle()

telecomManager.placeCall(address, extras)

Gerenciar as configurações do histórico de ligações unificado

A partir do Android 17 (nível 37 da API), os usuários podem ver e ativar/desativar o histórico de chamadas unificado por app nas configurações do sistema (geralmente em Configurações > Contas de chamadas > Registros de chamadas integrados ou diretamente no app de discagem padrão). Tanto os apps de terceiros para ligações quanto os discadores podem interagir com essas configurações.

Para abrir as configurações do histórico de ligações unificado, inicie uma Activity com a ação da intent TelecomManager.ACTION_CONFIGURE_CALL_LOG_INTEGRATION:

val intent = Intent(TelecomManager.ACTION_CONFIGURE_CALL_LOG_INTEGRATION)
startActivity(intent)

Quando um usuário desativa o histórico unificado de chamadas de um app nas configurações do sistema, o sistema exclui imediatamente e permanentemente todas as entradas de registro de chamadas desse pacote do provedor de registro de chamadas nativo (CallLog.Calls). As chamadas futuras iniciadas ou recebidas para esse app não serão registradas no discador do sistema.

Detectar mudanças de preferências

Para manter a sincronização quando um usuário ativa ou desativa o histórico de ligações unificado no app de chamadas nas configurações do sistema ou no discador, registre um broadcast receiver para a intent de transmissão TelecomManager.ACTION_VOIP_CALL_LOG_PREFERENCE (android.telecom.action.VOIP_CALL_LOG_PREFERENCE):

val receiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        if (intent.action == TelecomManager.ACTION_VOIP_CALL_LOG_PREFERENCE) {
            // Status of the Unified Call History of the app
            val isEnabled = intent.getBooleanExtra(
                TelecomManager.EXTRA_VOIP_CALL_LOG_PREFERENCE_STATUS,
                true
            )
        }
    }
}

Quando o usuário muda a chave, a plataforma transmite essa intent para seu app, que contém o estado booleano atualizado no extra TelecomManager.EXTRA_VOIP_CALL_LOG_PREFERENCE_STATUS. Em vez de esperar a verificação periódica em relação a CallLog.Calls, o app pode ficar aguardando essa transmissão. Quando o histórico unificado de chamadas está desativado (ou seja, definido como false), seu app pode atualizar o estado interno ou realizar uma limpeza, como remover os mapeamentos de chamadas armazenados em cache localmente usados para o processamento de callbacks.