Cronologia chiamate unificata

Le applicazioni VoIP possono integrare le proprie chiamate nel registro chiamate di sistema. In questo modo, gli utenti possono visualizzare la cronologia chiamate VoIP in modo centralizzato nell'app Telefono del sistema e richiamare direttamente dall'app Telefono. Questa guida descrive le modifiche richieste alle app di chiamate VoIP, alle app Telefono del sistema e alla gestione delle impostazioni della cronologia chiamate unificata.

Modifiche all'app di chiamate

Per integrare l'app VoIP con il registro chiamate del sistema, segui questi passaggi.

Registra filtro per l'intent di callback

Registra l'intent protetto dal sistema TelecomManager.ACTION_CALL_BACK.

Una volta registrato correttamente questo filtro per intent, tutte le chiamate aggiunte dall'app utilizzando CallsManager.addCall o altre API Telecom correlate verranno registrate automaticamente dal sistema. Il sistema utilizza questo intent registrato per inviare in un secondo momento un callback alla tua app quando un utente seleziona una voce di log delle chiamate VoIP nel dialer per richiamare.

<!-- 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>

Escludere la registrazione delle chiamate

Una volta registrata la richiamata, tutte le chiamate vengono registrate nel dialer di sistema. Per escludere le chiamate in base alla chiamata, imposta il valore booleano isLogExcluded su true all'interno di 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
        ),
)

Gestire i callback

Le chiamate aggiunte tramite CallsManager.addCall ricevono un UUID univoco tramite 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)
        )
    )
}

Verificare le voci del registro chiamate

Il registro chiamate del sistema mantiene un numero finito di voci ed elimina i vecchi record delle chiamate. Poiché l'app memorizza una mappatura di UUID alle informazioni dettagliate per la gestione dei callback, deve controllare periodicamente quali UUID sono ancora presenti nel log delle chiamate di sistema. Se un UUID non è più nel log di sistema, l'utente non può avviare un callback per quella chiamata e l'app può rimuovere in sicurezza la mappatura dallo spazio di archiviazione locale. Questa pratica aiuta a ottimizzare lo spazio di archiviazione.

Per ottenere l'elenco attuale di UUID attribuiti all'app all'interno del log di sistema, utilizza CallLog.Calls.CONTENT_VOIP_URI.

Modifiche all'app Telefono

Segui questi passaggi per consentire all'app Telefono di visualizzare i registri delle chiamate VoIP e avviare i richiami alle app VoIP.

Visualizzare i log delle chiamate VoIP nell'app Telefono

Per impostazione predefinita, i log delle chiamate delle app VoIP non vengono visualizzati nell'app Telefono. Per visualizzare i log delle chiamate integrati nell'app Telefono, procedi nel seguente modo:

  • Su Android 16.1 (livello API 36.1), aggiungi il parametro di query include_voip_calls al provider di contenuti CallLog.Calls per visualizzare i log delle chiamate VoIP:

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

  • Su Android 17 (livello API 37) e versioni successive, utilizza il seguente content provider e la seguente chiave di parametro formalizzati:

Avviare i richiami dall'app Telefono

Per avviare un richiamo da un dialer, utilizza TelecomManager.placeCall. La piattaforma utilizza l'CallLog.Calls._ID univoco della voce di log del registro chiamate per avviare l'app VoIP corretta. Questo avvio include un intent TelecomManager.ACTION_CALL_BACK, ovvero un'azione definita dal sistema per avviare una richiamata. Questo intent contiene l'UUID della chiamata nell'extra dell'intent TelecomManager.EXTRA_UUID, consentendo all'app VoIP di identificare a quale chiamata specifica si sta richiamando.

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

Gestire le impostazioni della cronologia chiamate unificata

A partire da Android 17 (livello API 37), gli utenti possono visualizzare e attivare/disattivare la cronologia delle chiamate unificata per ogni app nelle impostazioni di sistema (in genere in Impostazioni > Account chiamate > Registri chiamate integrati o direttamente nell'app Telefono predefinita). Sia le app di chiamata di terze parti sia le app di composizione possono interagire con queste impostazioni.

Per aprire le impostazioni della cronologia chiamate unificata, avvia un'attività con l'azione intent TelecomManager.ACTION_CONFIGURE_CALL_LOG_INTEGRATION:

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

Quando un utente disattiva la cronologia chiamate unificata per un'app nelle impostazioni di sistema, il sistema elimina immediatamente e definitivamente tutte le voci del registro chiamate esistenti per quel pacchetto dal fornitore del registro chiamate nativo (CallLog.Calls). Le chiamate future avviate da o ricevute per quell'app non verranno registrate nel dialer di sistema.

Ascoltare le modifiche alle preferenze

Per mantenere la sincronizzazione quando un utente attiva o disattiva la cronologia chiamate unificata per l'app di chiamate nelle impostazioni di sistema o nel tastierino, registra un broadcast receiver per l'intent di trasmissione 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 l'utente attiva/disattiva il pulsante, la piattaforma trasmette questo intent alla tua app contenente lo stato booleano aggiornato nell'extra TelecomManager.EXTRA_VOIP_CALL_LOG_PREFERENCE_STATUS. Anziché attendere la verifica periodica rispetto a CallLog.Calls, la tua app può ascoltare questa trasmissione. Quando la cronologia chiamate unificata è disattivata (ovvero impostata su false), la tua app può aggiornare il suo stato interno o eseguire la pulizia, ad esempio cancellare i mapping delle chiamate memorizzati nella cache locale utilizzati per la gestione dei callback.