Historique des appels unifié

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

Modifications pour l'application d'appel

Pour intégrer votre application VoIP au journal d'appels du 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 l'application Téléphone 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 l'enregistrement des appels

Une fois le rappel enregistré, tous les appels sont enregistrés dans l'application Téléphone du système. Pour exclure des appels individuellement, définissez le isLogExcluded booléen 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 d'appels

Le journal d'appels du système conserve un nombre limité d'entrées et finit par supprimer les anciens enregistrements d'appels. Étant donné que l'application stocke un mappage des UUID vers les 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 d'appels du système. Si un UUID ne figure plus dans le journal du 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 du système, utilisez CallLog.Calls.CONTENT_VOIP_URI.

Modifications pour l'application Téléphone

Procédez comme suit pour permettre à l'application Téléphone d'afficher les journaux d'appels VoIP et de lancer des rappels vers des applications VoIP.

Afficher les journaux d'appels VoIP dans l'application 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 :

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

Pour lancer un rappel depuis une application Téléphone, utilisez TelecomManager.placeCall. La plate-forme utilise le CallLog.Calls._ID unique de l'entrée de journal d'appels pour lancer l'application VoIP appropriée. Ce lancement inclut un TelecomManager.ACTION_CALL_BACK intent, qui est une action définie par le système pour lancer un rappel. Cet intent contient le UUID de l'appel dans l'extra d'intent 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 d'historique des appels unifié

À partir d'Android 17 (niveau d'API 37), les utilisateurs peuvent afficher et activer/désactiver l'historique d'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 Téléphone par défaut). Les applications d'appel tierces et les applications Téléphone peuvent interagir avec ces paramètres.

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

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

Lorsqu'un utilisateur désactive l'historique d'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 journal d'appels existantes pour ce package du fournisseur de journal d'appels natif (CallLog.Calls). Les futurs appels lancés par ou reçus pour cette application ne seront pas enregistrés dans l'application Téléphone 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 l'application Téléphone, enregistrez un broadcast receiver pour l'intent 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 cet intent à votre application, qui contient l'état booléen mis à jour dans l' TelecomManager.EXTRA_VOIP_CALL_LOG_PREFERENCE_STATUS extra. 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.