سابقه تماس یکپارچه

برنامه‌های VoIP می‌توانند تماس‌هایشان را در گزارش تماس سیستم ادغام کنند. این ویژگی به کاربران امکان می‌دهد سابقه تماس VoIP خود را به‌صورت مرکزی در برنامه شماره‌گیر سیستم ببینند و مستقیماً از برنامه شماره‌گیر تماس بگیرند. این راهنما تغییرات لازم برای برنامه‌های تماس VoIP، برنامه‌های شماره‌گیر سیستم، و مدیریت تنظیمات سابقه تماس یکپارچه را شرح می‌دهد.

تغییرات برنامه تماس

برای ادغام کردن برنامه VoIP با گزارش تماس سیستم، این مراحل را دنبال کنید.

ثبت فیلتر هدف پاسخ تماس

هدف محافظت‌شده سیستم TelecomManager.ACTION_CALL_BACK را ثبت کنید.

پس‌از اینکه این فیلتر هدف به‌درستی ثبت شد، هر تماسی که برنامه‌تان بااستفاده از 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 بولی را در CallAttributesCompat روی 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
        ),
)
VoipCallActivity.kt

رسیدگی به پاسخ‌های تماس

تماس‌های اضافه‌شده ازطریق 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)
        )
    )
}
VoipCallActivity.kt

درستی‌سنجی ورودی‌های گزارش تماس

گزارش تماس سیستم تعداد محدودی ورودی را حفظ می‌کند و درنهایت سوابق تماس قدیمی را پاک می‌کند. ازآنجایی‌که برنامه نگاشت UUID به جزئیات تماس را برای مدیریت تماس برگشتی ذخیره می‌کند، باید به‌طور دوره‌ای بررسی کند که کدام UUID هنوز در گزارش تماس سیستم وجود دارد. اگر UUID دیگر در گزارش سیستم وجود نداشته باشد، کاربر نمی‌تواند برای آن تماس درخواست تماس برگشتی کند و برنامه می‌تواند با اطمینان نگاشت را از فضای ذخیره‌سازی محلی خود بردارد. این تمرین به بهینه‌سازی فضای ذخیره‌سازی کمک می‌کند.

برای دریافت فهرست فعلی UUID منسوب به برنامه در گزارش سیستم، از CallLog.Calls.CONTENT_VOIP_URI استفاده کنید.

تغییرات برنامه شماره‌گیر

برای فعال کردن برنامه شماره‌گیر برای نمایش گزارش‌های تماس VoIP و شروع کردن تماس برگشتی به برنامه‌های VoIP، این مراحل را دنبال کنید.

نمایش گزارش‌های تماس VoIP در برنامه شماره‌گیر

به‌طور پیش‌فرض، گزارش‌های تماس برنامه VoIP در برنامه شماره‌گیر نشان داده نمی‌شود. برای نمایش گزارش‌های تماس یکپارچه در برنامه شماره‌گیر، این کارها را انجام دهید:

• در Android 16.1 (سطح API 36.1)، پارامتر پُرسمان include_voip_calls را به CallLog.Calls ارائه‌دهنده محتوا برای نمایش گزارش‌های تماس VoIP پیوست کنید:

  CallLog.Calls.CONTENT_URI.buildUpon()
      .appendQueryParameter("include_voip_calls", "true")
      .build()
  DialerActivity.kt

• در Android 17 (میانای برنامه کاربردی سطح ۳۷) و بالاتر، از ارائه‌دهنده محتوا و کلید پارامتر رسمی زیر استفاده کنید:

  • 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 (سطح API 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 تنظیم شده باشد)، برنامه شما می‌تواند وضعیت داخلی‌اش را به‌روز کند یا پاک‌سازی‌هایی مثل پاک کردن نگاشت‌های تماس ذخیره‌شده محلی را که برای مدیریت تماس برگشتی استفاده می‌شود انجام دهد.