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

يمكن لتطبيقات بروتوكول نقل الصوت عبر الإنترنت (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 ويخزّنها. عندما يختار المستخدم إدخال سجلّ مكالمات بروتوكول نقل الصوت عبر الإنترنت في برنامج الاتصال، يبدأ برنامج الاتصال في النظام معاودة اتصال باستخدام intent action TelecomManager.ACTION_CALL_BACK وإضافة intent extra 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 الفريد لإدخال في السجلّ المكالمات لتشغيل تطبيق بروتوكول الصوت على الإنترنت الصحيح. يتضمّن هذا التشغيل intent 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