Historique des appels unifié

Les applications VoIP peuvent intégrer leurs appels au journal d'appels du système. Cela permet aux utilisateurs de consulter leur historique des appels VoIP de manière centralisée dans l'application Téléphone système et de rappeler des numéros directement depuis cette application. Ce guide décrit les modifications requises pour les applications d'appels VoIP, les applications Téléphone système et la gestion des paramètres de l'historique des appels unifié.

Modifications apportées à l'application d'appel

Pour intégrer votre application VoIP au journal des appels système, procédez comme suit.

Enregistrer le filtre d'intent de rappel

Enregistrez l'intent protégé par le système TelecomManager.ACTION_CALL_BACK.

Une fois ce filtre d'intent correctement enregistré, tous les appels que votre application ajoute à l'aide de CallsManager.addCall ou d'autres API Telecom associées seront automatiquement enregistrés par le système. Le système utilise cet intent enregistré pour envoyer ultérieurement un rappel à votre application lorsqu'un utilisateur sélectionne une entrée de journal d'appels VoIP dans le clavier de numérotation pour rappeler.

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

Exclure la journalisation des appels

Une fois le rappel enregistré, tous les appels sont consignés dans le composeur du système. Pour exclure des appels individuellement, définissez le booléen isLogExcluded sur true dans 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
        ),
)

Gérer les rappels

Les appels ajoutés via CallsManager.addCall reçoivent un UUID unique via 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)
        )
    )
}

Vérifier les entrées du journal des appels

Le journal des appels système conserve un nombre fini d'entrées et finit par supprimer les anciens enregistrements d'appels. Étant donné que l'application stocke un mappage des UUID aux détails des appels pour la gestion des rappels, elle doit vérifier régulièrement quels UUID sont toujours présents dans le journal des appels système. Si un UUID n'est plus dans le journal système, l'utilisateur ne peut pas lancer de rappel pour cet appel, et l'application peut supprimer en toute sécurité le mappage de son stockage local. Cette pratique permet d'optimiser le stockage.

Pour obtenir la liste actuelle des UUID attribués à l'application dans le journal système, utilisez CallLog.Calls.CONTENT_VOIP_URI.

Modifications apportées à l'application Téléphone

Pour permettre à l'application Téléphone d'afficher les journaux d'appels VoIP et d'initier des rappels vers les applications VoIP, procédez comme suit.

Afficher les journaux d'appels VoIP dans l'application de téléphone

Par défaut, les journaux d'appels des applications VoIP n'apparaissent pas dans l'application Téléphone. Pour afficher les journaux d'appels intégrés dans l'application Téléphone, procédez comme suit :

  • Sur Android 16.1 (niveau d'API 36.1), ajoutez le paramètre de requête include_voip_calls au fournisseur de contenu CallLog.Calls pour afficher les journaux d'appels VoIP :

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

  • Sur Android 17 (niveau d'API 37) et versions ultérieures, utilisez le fournisseur de contenu et la clé de paramètre formalisés suivants :

Initier des rappels depuis l'application Téléphone

Pour lancer un rappel à partir d'un outil de numérotation, utilisez TelecomManager.placeCall. La plate-forme utilise le CallLog.Calls._ID unique de l'entrée du journal d'appels pour lancer la bonne application VoIP. Ce lancement inclut un intent TelecomManager.ACTION_CALL_BACK, qui est une action définie par le système pour lancer un rappel. Cette intention contient le UUID de l'appel dans l'extra d'intention TelecomManager.EXTRA_UUID, ce qui permet à l'application VoIP d'identifier l'appel spécifique qui est rappelé.

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

Gérer les paramètres de l'historique des appels unifié

À partir d'Android 17 (niveau d'API 37), les utilisateurs peuvent afficher et activer/désactiver l'historique des appels unifié pour chaque application dans les paramètres système (généralement sous Paramètres > Comptes d'appel > Journaux d'appels intégrés ou directement dans leur application de téléphone par défaut). Les applications d'appel et les applications de numérotation tierces peuvent interagir avec ces paramètres.

Pour ouvrir les paramètres de l'historique des appels unifié, démarrez une activité avec l'action d'intent TelecomManager.ACTION_CONFIGURE_CALL_LOG_INTEGRATION :

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

Lorsqu'un utilisateur désactive l'historique des appels unifié pour une application dans les paramètres système, le système supprime immédiatement et définitivement toutes les entrées de l'historique des appels existantes pour ce package du fournisseur d'historique des appels natif (CallLog.Calls). Les futurs appels initiés par ou reçus pour cette application ne seront pas enregistrés dans le clavier de numérotation du système.

Écouter les changements de préférences

Pour rester synchronisé lorsqu'un utilisateur active ou désactive l'historique des appels unifié pour votre application d'appel dans les paramètres système ou le clavier de numérotation, enregistrez un récepteur de diffusion pour l'intention de diffusion 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
            )
        }
    }
}

Lorsque l'utilisateur active ou désactive le bouton, la plate-forme diffuse cette intention à votre application, qui contient l'état booléen mis à jour dans l'extra TelecomManager.EXTRA_VOIP_CALL_LOG_PREFERENCE_STATUS. Au lieu d'attendre une vérification périodique par rapport à CallLog.Calls, votre application peut écouter cette diffusion. Lorsque l'historique des appels unifié est désactivé (c'est-à-dire défini sur false), votre application peut mettre à jour son état interne ou effectuer un nettoyage, par exemple en effaçant les mappages d'appels mis en cache localement et utilisés pour la gestion des rappels.