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

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

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

التغييرات في تطبيق المكالمات

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

تسجيل فلتر هدف معاودة الاتصال

سجِّل الهدف المحمي من النظام 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.

**ملاحظة مهمة:** يجب أن يربط تطبيق بروتوكول نقل الصوت عبر الإنترنت الذي يجري المكالمة تفاصيل المكالمة بهذا UUID ويخزّنها. عندما يختار المستخدم إدخال سجلّ مكالمات بروتوكول نقل الصوت عبر الإنترنت في برنامج الاتصال، يبدأ برنامج الاتصال في النظام معاودة اتصال باستخدام إجراء الهدف TelecomManager.ACTION_CALL_BACK وإضافة الهدف TelecomManager.EXTRA_UUID. يستخدم تطبيق بروتوكول نقل الصوت عبر الإنترنت 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)
        )
    )
}VoipCallActivity.kt

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

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

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

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

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

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

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

على Android 16.1 (المستوى 36.1 من واجهة برمجة التطبيقات)، ألحِق مَعلمة طلب البحث include_voip_calls بمزوّد المحتوى CallLog.Calls لعرض سجلّات مكالمات بروتوكول نقل الصوت عبر الإنترنت:
```
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 الفريد لإدخال سجلّ المكالمات لتشغيل تطبيق بروتوكول نقل الصوت عبر الإنترنت الصحيح. يتضمّن هذا التشغيل هدف TelecomManager.ACTION_CALL_BACK، وهو إجراء محدّد من النظام لبدء مكالمة يتم إرجاعها. يحتوي هذا الهدف على UUID في إضافة الهدف TelecomManager.EXTRA_UUID، ما يسمح لتطبيق بروتوكول نقل الصوت عبر الإنترنت بتحديد المكالمة المحدّدة التي يتم إرجاعها.

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