Historial de llamadas unificado

Las aplicaciones de VoIP pueden integrar sus llamadas en el registro de llamadas del sistema. Esto permite que los usuarios vean su historial de llamadas VoIP de forma centralizada en la app de marcador del sistema y devuelvan llamadas directamente desde ella. En esta guía, se describen los cambios necesarios en las apps de llamadas VoIP, las apps de marcador del sistema y la administración de la configuración del historial de llamadas unificado.

Cambios en la app de llamadas

Para integrar tu app de VoIP en el registro de llamadas del sistema, sigue estos pasos.

Registra el filtro de intents de devolución de llamada

Registra el intent protegido por el sistema TelecomManager.ACTION_CALL_BACK.

Una vez que este filtro de intents se registre correctamente, el sistema registrará automáticamente todas las llamadas que agregue tu app con CallsManager.addCall o cualquier otra API de Telecom relacionada. El sistema usa este intent registrado para enviar más tarde una devolución de llamada a tu app cuando un usuario selecciona una entrada del registro de llamadas VoIP en el marcador para devolver la llamada.

<!-- 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 el registro de llamadas

Una vez que se registra la devolución de llamada, todas las llamadas se registran en el marcador del sistema. Para excluir llamadas de forma individual, establece el valor booleano isLogExcluded en true dentro de 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
        ),
)

Controla las devoluciones de llamada

Las llamadas agregadas a través de CallsManager.addCall obtienen un UUID único a través de 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)
        )
    )
}

Verifica las entradas del registro de llamadas

El registro de llamadas del sistema mantiene una cantidad finita de entradas y, finalmente, borra los registros de llamadas antiguos. Dado que la app almacena una asignación de objetos UUID a detalles de llamadas para el control de devoluciones de llamada, debe verificar periódicamente qué objetos UUID aún están presentes en el registro de llamadas del sistema. Si un UUID ya no está en el registro del sistema, el usuario no puede iniciar una devolución de llamada para esa llamada, y la app puede quitar de forma segura la asignación de su almacenamiento local. Esta práctica ayuda a optimizar el almacenamiento.

Para obtener la lista actual de UUIDs atribuidos a la app en el registro del sistema, usa CallLog.Calls.CONTENT_VOIP_URI.

Cambios en la app de Teléfono

Sigue estos pasos para permitir que la app del marcador muestre los registros de llamadas VoIP y que inicie devoluciones de llamadas a apps de VoIP.

Mostrar registros de llamadas de VoIP en la app de marcador

De forma predeterminada, los registros de llamadas de la app de VoIP no aparecen en la app de marcador. Para mostrar los registros de llamadas integrados en la app de marcador, haz lo siguiente:

  • En Android 16.1 (nivel de API 36.1), agrega el parámetro de consulta include_voip_calls al proveedor de contenido CallLog.Calls para mostrar los registros de llamadas de VoIP:

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

  • En Android 17 (nivel de API 37) y versiones posteriores, usa el siguiente proveedor de contenido y clave de parámetro formalizados:

Cómo iniciar devoluciones de llamada desde la app de Teléfono

Para iniciar una devolución de llamada desde un marcador, usa TelecomManager.placeCall. La plataforma usa el CallLog.Calls._ID único de la entrada del registro de llamadas para iniciar la app de VoIP correcta. Este inicio incluye un intent TelecomManager.ACTION_CALL_BACK, que es una acción definida por el sistema para iniciar una devolución de llamada. Este intent contiene el UUID de la llamada en el extra del intent TelecomManager.EXTRA_UUID, lo que permite que la app de VoIP identifique a qué llamada específica se está devolviendo la llamada.

// 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)

Administra la configuración del historial de llamadas unificado

A partir de Android 17 (nivel de API 37), los usuarios pueden ver y activar o desactivar el historial de llamadas unificado por app en la configuración del sistema (por lo general, en Configuración > Cuentas de llamadas > Registros de llamadas integrados o directamente en la app de marcado predeterminada). Tanto las apps de llamadas de terceros como las apps de marcador pueden interactuar con estos parámetros de configuración.

Para abrir la configuración del historial de llamadas unificado, inicia una actividad con la acción de intent TelecomManager.ACTION_CONFIGURE_CALL_LOG_INTEGRATION:

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

Cuando un usuario desactiva el historial de llamadas unificado para una app en la configuración del sistema, el sistema borra de forma inmediata y permanente todas las entradas existentes del registro de llamadas para ese paquete del proveedor nativo del registro de llamadas (CallLog.Calls). Las llamadas futuras iniciadas por esa app o recibidas para ella no se registrarán en el marcador del sistema.

Cómo escuchar los cambios de preferencias

Para mantener la sincronización cuando un usuario habilita o inhabilita el historial de llamadas unificado para tu app de llamadas en la configuración del sistema o el marcador, registra un receptor de transmisiones para la intención de transmisión 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
            )
        }
    }
}

Cuando el usuario activa o desactiva el botón de activación, la plataforma transmite esta intención a tu app, que contiene el estado booleano actualizado en el elemento adicional TelecomManager.EXTRA_VOIP_CALL_LOG_PREFERENCE_STATUS. En lugar de esperar la verificación periódica en CallLog.Calls, tu app puede escuchar esta transmisión. Cuando el historial de llamadas unificado está inhabilitado (en otras palabras, establecido en false), tu app puede actualizar su estado interno o realizar una limpieza, como borrar las asignaciones de llamadas almacenadas en caché de forma local que se usan para el control de devoluciones de llamada.