Единый журнал звонков

Приложения VoIP могут добавлять свои звонки в системный список вызовов. Это позволяет пользователям просматривать журнал звонков VoIP в системном приложении для набора номера и перезванивать прямо из него. В этом руководстве описаны необходимые изменения для приложений для звонков VoIP, системных приложений для набора номера и управления настройками единого журнала звонков.

Изменения в приложении для звонков

Чтобы интегрировать VoIP-приложение с системным журналом вызовов, выполните следующие действия:

Как зарегистрировать фильтр интентов обратного вызова

Зарегистрируйте системное намерение TelecomManager.ACTION_CALL_BACK.

После того как фильтр интентов будет зарегистрирован, все звонки, добавленные приложением с помощью CallsManager.addCall или других связанных API Telecom, будут автоматически регистрироваться системой. Система использует зарегистрированный интент, чтобы позже отправить обратный вызов в ваше приложение, когда пользователь выберет запись в журнале звонков VoIP в приложении для набора номера, чтобы перезвонить.

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

Как проверить записи в журнале вызовов

В журнале вызовов системы хранится ограниченное количество записей, и старые записи удаляются. Поскольку приложение хранит сопоставление 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 (уровень API 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 (уровень API 37) и более поздних версиях пользователи могут просматривать и включать/отключать единый журнал звонков для каждого приложения в системных настройках (обычно в разделе Настройки > Аккаунты для звонков > Интегрированные журналы звонков или непосредственно в приложении для звонков, установленном по умолчанию). Эти настройки могут использоваться как сторонними приложениями для звонков, так и приложениями для набора номера.

Как перенаправлять пользователей в настройки

Чтобы открыть настройки единого журнала звонков, запустите Activity с действием интента 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), ваше приложение может обновить свое внутреннее состояние или выполнить очистку, например удалить локально кешированные сопоставления звонков, используемые для обработки обратных вызовов.