تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

سجلّ المكالمات الموحّد

يمكن لتطبيقات بروتوكول نقل الصوت عبر الإنترنت (VoIP) دمج مكالماتها في سجلّ المكالمات في النظام. يتيح ذلك للمستخدمين الاطّلاع على سجلّ مكالمات VoIP بشكل مركزي في تطبيق "طلب الرقم" بالنظام وإجراء مكالمات مباشرةً من تطبيق "طلب الرقم". يوضّح هذا الدليل التغييرات المطلوبة في تطبيقات مكالمات VoIP وتطبيقات طلب الرقم بالنظام وإدارة إعدادات سجلّ المكالمات الموحّد.

تغييرات على تطبيق الاتصال

لدمج تطبيق VoIP مع سجلّ المكالمات في النظام، اتّبِع الخطوات التالية.

تسجيل intent filter معاودة الاتصال

سجِّل الغرض المحمي من النظام TelecomManager.ACTION_CALL_BACK.

بعد تسجيل intent filter هذا بشكل صحيح، سيسجّل النظام تلقائيًا أي مكالمات يضيفها تطبيقك باستخدام CallsManager.addCall أو واجهات برمجة التطبيقات الأخرى ذات الصلة في Telecom. يستخدم النظام هذا الغرض المسجَّل لإرسال دالة ردّ اتصال إلى تطبيقك لاحقًا عندما يختار المستخدم إدخالاً في سجلّ مكالمات عبر بروتوكول الإنترنت في تطبيق الاتصال لإعادة الاتصال.

<!-- 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>AndroidManifest.xml

استبعاد تسجيل المكالمات

بعد تسجيل دالة ردّ الاتصال، يتم تسجيل جميع المكالمات في تطبيق الاتصال بالنظام. لاستبعاد المكالمات على أساس كل مكالمة على حدة، اضبط قيمة isLogExcluded المنطقية على true ضمن 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
        ),
)VoipCallActivity.kt

التعامل مع عمليات معاودة الاتصال

تحصل المكالمات التي تتم إضافتها من خلال CallsManager.addCall على UUID فريد من خلال 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)
        )
    )
}VoipCallActivity.kt

التحقّق من إدخالات سجلّ المكالمات

يحتفظ سجلّ مكالمات النظام بعدد محدود من الإدخالات، ويتم في النهاية محو سجلّات المكالمات القديمة. بما أنّ التطبيق يخزّن عملية ربط بين UUIDs وتفاصيل المكالمات للتعامل مع عمليات معاودة الاتصال، عليه التحقّق بشكل دوري من UUIDs التي لا تزال متوفّرة في سجلّ مكالمات النظام. إذا لم يعُد UUID في سجلّ النظام، لن يتمكّن المستخدم من بدء معاودة الاتصال لهذا الاتصال، ويمكن للتطبيق إزالة عملية الربط بأمان من مساحة التخزين المحلية. يساعد هذا الإجراء في تحسين مساحة التخزين.

للحصول على القائمة الحالية لعمليات UUID المنسوبة إلى التطبيق في سجل النظام، استخدِم CallLog.Calls.CONTENT_VOIP_URI.

التغييرات في تطبيق "برنامج الاتصال"

اتّبِع الخطوات التالية للسماح لتطبيق "لوحة الاتصال" بعرض سجلّات مكالمات عبر بروتوكول الإنترنت (VoIP) وبدء عمليات معاودة الاتصال بتطبيقات VoIP.

عرض سجلّات مكالمات بروتوكول الصوت عبر الإنترنت في تطبيق "برنامج الاتصال"

لا تظهر سجلات المكالمات التي يتم إجراؤها عبر تطبيقات بروتوكول نقل الصوت عبر الإنترنت (VoIP) في تطبيق برنامج الاتصال تلقائيًا. لعرض سجلات المكالمات المدمجة في تطبيق برنامج الاتصال، اتّبِع الخطوات التالية:

في نظام التشغيل Android 16.1 (مستوى واجهة برمجة التطبيقات 36.1)، ألحِق مَعلمات طلب البحث include_voip_calls بموفّر المحتوى CallLog.Calls لعرض سجلّات مكالمات VoIP:
```
CallLog.Calls.CONTENT_URI.buildUpon()
    .appendQueryParameter("include_voip_calls", "true")
    .build()DialerActivity.kt
```
على الإصدار Android 17 (المستوى 37 من واجهة برمجة التطبيقات) والإصدارات الأحدث، استخدِم موفّر المحتوى ومفتاح المَعلمة التاليَين:
- CallLog.Calls.CONTENT_URI_WITH_VOIP_CALLS
- CallLog.Calls.INCLUDE_VOIP_CALLS_PARAM_KEY

بدء عمليات معاودة الاتصال من تطبيق "برنامج الاتصال"

لبدء معاودة الاتصال من أداة الاتصال، استخدِم TelecomManager.placeCall. يستخدم النظام الأساسي CallLog.Calls._ID الفريد لإدخال سجلّ المكالمات لتشغيل تطبيق VoIP الصحيح. يتضمّن هذا التشغيل الغرض TelecomManager.ACTION_CALL_BACK، وهو إجراء محدّد من النظام لبدء مكالمة ردّ. يحتوي هذا الغرض على UUID في إضافات الغرض TelecomManager.EXTRA_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)DialerActivity.kt

إدارة إعدادات سجلّ المكالمات الموحّد

بدءًا من Android 17 (المستوى 37 من واجهة برمجة التطبيقات)، يمكن للمستخدمين عرض سجلّ المكالمات الموحّد وتفعيله أو إيقافه على مستوى كل تطبيق في إعدادات النظام (عادةً ضمن الإعدادات > حسابات الاتصال > سجلّات المكالمات المدمَجة أو مباشرةً في تطبيق الاتصال التلقائي). يمكن لكلّ من تطبيقات الاتصال التابعة لجهات خارجية وتطبيقات لوحة الاتصال التفاعل مع هذه الإعدادات.

توجيه المستخدمين إلى الإعدادات

لفتح إعدادات سجلّ المكالمات الموحّد، ابدأ نشاطًا باستخدام إجراء الهدف TelecomManager.ACTION_CONFIGURE_CALL_LOG_INTEGRATION:

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

عندما يوقف المستخدم سجلّ المكالمات الموحّد لأحد التطبيقات في إعدادات النظام، يمحو النظام على الفور وبشكل دائم جميع إدخالات سجلّ المكالمات الحالية لهذه الحزمة من موفّر سجلّ المكالمات الأصلي (CallLog.Calls). ولن يتم تسجيل المكالمات المستقبلية التي يجريها التطبيق أو يتلقّاها في تطبيق الاتصال التابع للنظام.

الاستماع إلى تغييرات الإعدادات المفضّلة

لإبقاء السجلّ متزامنًا عندما يفعّل المستخدم سجلّ المكالمات الموحّد أو يوقفه لتطبيق الاتصال في إعدادات النظام أو تطبيق "لوحة الاتصال"، عليك تسجيل أداة استقبال البث 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
            )
        }
    }
}VoipCallActivity.kt

عندما ينقر المستخدم على زر التبديل، تبث المنصة هذا الغرض إلى تطبيقك الذي يحتوي على حالة القيمة المنطقية المعدَّلة في الإضافة TelecomManager.EXTRA_VOIP_CALL_LOG_PREFERENCE_STATUS. بدلاً من انتظار عملية التحقّق الدورية من CallLog.Calls، يمكن لتطبيقك الاستماع إلى عملية البث هذه. عند إيقاف سجلّ المكالمات الموحّد (أي ضبطه على false)، يمكن لتطبيقك تعديل حالته الداخلية أو إجراء عمليات تنظيف، مثل محو عمليات ربط المكالمات المخزّنة مؤقتًا على الجهاز والمستخدَمة في معالجة معاودة الاتصال.