统一的通话记录

VoIP 应用可以将通话记录集成到系统通话记录中。这样一来，用户便可在系统拨号器应用中集中查看 VoIP 通话记录，并直接从拨号器应用回拨电话。本指南介绍了对 VoIP 通话应用、系统拨号器应用以及管理统一通话记录设置的必要更改。

通话应用的更改

如需将 VoIP 应用与系统通话记录集成，请按以下步骤操作。

注册回调 intent 过滤器

注册受系统保护的 intent TelecomManager.ACTION_CALL_BACK。

正确注册此 intent 过滤器后，您的应用使用 CallsManager.addCall或其他相关 Telecom API 添加的任何通话都将由系统自动 记录。当用户在拨号器中选择 VoIP 通话记录条目以回拨电话时，系统会使用此注册的 intent 向您的应用发送回调。

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

排除通话记录

注册回调后，所有通话都会记录到系统拨号器中。如需按通话排除通话，请在 CallAttributesCompat 中将 isLogExcluded 布尔值设置为 true。

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

处理回调

通过 CallsManager.addCall 添加的通话会通过 CallControlScope.getCallId 获得唯一的 UUID。

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

验证通话记录条目

系统通话记录会保留有限数量的条目，并最终清除旧的通话记录。由于应用会存储 UUID 到通话详情的映射以进行回调处理，因此应定期检查系统通话记录中仍存在哪些 UUID。如果 UUID 不再位于系统日志中，用户将无法针对该通话发起回调，并且应用可以安全地从本地存储空间中移除该映射。这种做法有助于优化存储空间。

如需获取系统 日志中归因于应用的当前 UUID 列表，请使用 CallLog.Calls.CONTENT_VOIP_URI。

拨号器应用的更改

请按照以下步骤操作，使拨号器应用能够显示 VoIP 通话记录并向 VoIP 应用发起回调。

在拨号器应用中显示 VoIP 通话记录

默认情况下，VoIP 应用通话记录不会显示在拨号器应用中。如需在拨号器应用中显示集成的通话记录，请执行以下操作：

从拨号器应用发起回调

如需从拨号器发起回调，请使用 TelecomManager.placeCall。平台使用通话记录条目的唯一 CallLog.Calls._ID 来启动正确的 VoIP 应用。此启动包含 TelecomManager.ACTION_CALL_BACK intent，这是用于发起回拨的系统定义的操作。此 intent 在 intent extra TelecomManager.EXTRA_UUID 中包含通话的 UUID，从而让 VoIP 应用能够识别 要回拨的特定通话。

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

管理统一通话记录设置

从 Android 17（API 级别 37）开始，用户可以在系统设置中（通常位于设置 > 通话账号 > 集成通话记录 下）或直接在其默认拨号器应用中按应用查看和切换统一通话记录。第三方通话应用和拨号器应用都可以与这些设置互动。

如需打开统一通话记录设置，请使用 TelecomManager.ACTION_CONFIGURE_CALL_LOG_INTEGRATION intent 操作启动 activity：

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

当用户在系统设置中关闭应用的统一通话记录时，系统会立即永久清除该软件包的所有现有通话记录条目（来自原生通话记录提供程序 [CallLog.Calls]）。由该应用发起或为该应用接收的未来通话将不会记录在系统拨号器中。

监听偏好设置更改

如需在用户在系统设置或拨号器中为 您的通话应用启用或停用统一通话记录时保持同步，请为 TelecomManager.ACTION_VOIP_CALL_LOG_PREFERENCE (android.telecom.action.VOIP_CALL_LOG_PREFERENCE) 广播 intent 注册广播接收器：

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

当用户切换开关时，平台会将此 intent 广播到您的 应用，其中包含 TelecomManager.EXTRA_VOIP_CALL_LOG_PREFERENCE_STATUS extra 中的更新后的布尔值状态。您的应用可以监听此广播，而不是等待针对 CallLog.Calls 进行定期验证。当统一通话记录被停用（也就是说，设置为 false）时，您的应用可以更新其内部状态或执行清理操作，例如清除用于回调处理的本地缓存的通话映射。