Ujednolicona historia połączeń

Aplikacje VoIP mogą integrować swoje połączenia z systemowym rejestrem połączeń. Dzięki temu użytkownicy mogą wyświetlać historię połączeń VoIP w aplikacji Telefon i oddzwaniać bezpośrednio z tej aplikacji. W tym przewodniku opisujemy wymagane zmiany w aplikacjach do połączeń VoIP, aplikacjach Telefon i zarządzaniu ustawieniami ujednoliconej historii połączeń.

Zmiany w aplikacji do połączeń

Aby zintegrować aplikację VoIP z systemowym rejestrem połączeń, wykonaj te czynności.

Zarejestruj filtr intencji wywołania zwrotnego

Zarejestruj chronioną przez system intencję TelecomManager.ACTION_CALL_BACK.

Gdy ten filtr intencji zostanie prawidłowo zarejestrowany, wszystkie połączenia dodawane przez aplikację za pomocą CallsManager.addCall lub innych powiązanych interfejsów API Telecom będą automatycznie rejestrowane przez system. System używa tej zarejestrowanej intencji, aby później wysłać wywołanie zwrotne do aplikacji, gdy użytkownik wybierze w aplikacji Telefon wpis w rejestrze połączeń VoIP, aby oddzwonić.

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

Wyklucz rejestrowanie połączeń

Po zarejestrowaniu wywołania zwrotnego wszystkie połączenia są rejestrowane w aplikacji Telefon. Aby wykluczyć połączenia na podstawie poszczególnych połączeń, ustaw wartość isLogExcluded logiczną na true w 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

Obsługa wywołań zwrotnych

Połączenia dodane za pomocą CallsManager.addCall otrzymują unikalny identyfikator UUID za pomocą 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

Weryfikowanie wpisów w rejestrze połączeń

Systemowy rejestr połączeń przechowuje ograniczoną liczbę wpisów i ostatecznie usuwa stare rekordy połączeń. Ponieważ aplikacja przechowuje mapowanie identyfikatorów UUID na szczegóły połączeń na potrzeby obsługi wywołań zwrotnych, powinna okresowo sprawdzać, które identyfikatory UUID są nadal obecne w systemowym rejestrze połączeń. Jeśli identyfikator UUID nie znajduje się już w dzienniku systemowym, użytkownik nie może zainicjować wywołania zwrotnego dla tego połączenia, a aplikacja może bezpiecznie usunąć mapowanie z pamięci lokalnej. Ta praktyka pomaga zoptymalizować wykorzystanie pamięci.

Aby uzyskać bieżącą listę UUID przypisanych do aplikacji w dzienniku systemowym, użyj CallLog.Calls.CONTENT_VOIP_URI.

Zmiany w aplikacji Telefon

Aby umożliwić aplikacji Telefon wyświetlanie rejestrów połączeń VoIP i inicjowanie wywołań zwrotnych do aplikacji VoIP, wykonaj te czynności.

Wyświetlanie rejestrów połączeń VoIP w aplikacji Telefon

Domyślnie rejestry połączeń aplikacji VoIP nie są wyświetlane w aplikacji Telefon. Aby wyświetlać zintegrowane rejestry połączeń w aplikacji Telefon:

• W Androidzie 16.1 (poziom interfejsu API 36.1) dołącz parametr zapytania include_voip_calls do mechanizmu dostarczania treści CallLog.Calls, aby wyświetlać rejestry połączeń VoIP:

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

• W Androidzie 17 (poziom interfejsu API 37) i nowszym użyj tych sformalizowanych dostawców treści i kluczy parametrów:

  • CallLog.Calls.CONTENT_URI_WITH_VOIP_CALLS
  • CallLog.Calls.INCLUDE_VOIP_CALLS_PARAM_KEY

Inicjowanie wywołań zwrotnych z aplikacji Telefon

Aby zainicjować wywołanie zwrotne z aplikacji Telefon, użyj TelecomManager.placeCall. Platforma używa unikalnego CallLog.Calls._ID wpisu logu w rejestrze połączeń, aby uruchomić prawidłową aplikację VoIP. Uruchomienie obejmuje intencję TelecomManager.ACTION_CALL_BACK, która jest zdefiniowanym przez system działaniem służącym do inicjowania połączenia zwrotnego. Ta intencja zawiera identyfikator UUID połączenia w dodatkowej intencji TelecomManager.EXTRA_UUID, co umożliwia aplikacji VoIP określenie do którego połączenia ma nastąpić wywołanie zwrotne.

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

Zarządzanie ustawieniami ujednoliconej historii połączeń

Od Androida 17 (poziom interfejsu API 37) użytkownicy mogą wyświetlać i przełączać ujednoliconą historię połączeń w ustawieniach systemu (zwykle w sekcji Ustawienia > Konta połączeń > Zintegrowane rejestry połączeń lub bezpośrednio w domyślnej aplikacji Telefon). Z tymi ustawieniami mogą wchodzić w interakcję zarówno aplikacje do połączeń innych firm, jak i aplikacje Telefon.

Przekierowywanie użytkowników do ustawień

Aby otworzyć ustawienia ujednoliconej historii połączeń, uruchom działanie z intencją TelecomManager.ACTION_CONFIGURE_CALL_LOG_INTEGRATION:

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

Gdy użytkownik wyłączy ujednoliconą historię połączeń w ustawieniach systemu, system natychmiast i trwale usunie wszystkie dotychczasowe wpisy w rejestrze połączeń dla tego pakietu z natywnego dostawcy rejestru połączeń (CallLog.Calls). Przyszłe połączenia zainicjowane przez tę aplikację lub odebrane przez nią nie będą rejestrowane w aplikacji Telefon.

Nasłuchiwanie zmian ustawień

Aby zachować synchronizację, gdy użytkownik włączy lub wyłączy ujednoliconą historię połączeń dla Twojej aplikacji do połączeń w ustawieniach systemu lub aplikacji Telefon, zarejestruj odbiornik transmisji dla intencji transmisji 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

Gdy użytkownik przełączy przełącznik, platforma wyśle tę intencję do Twojej aplikacji, zawierającą zaktualizowany stan logiczny w dodatkowej intencji TelecomManager.EXTRA_VOIP_CALL_LOG_PREFERENCE_STATUS. Zamiast czekać na okresową weryfikację w CallLog.Calls, aplikacja może nasłuchiwać tej transmisji. Gdy ujednolicona historia połączeń jest wyłączona (czyli ustawiona na false), aplikacja może zaktualizować swój stan wewnętrzny lub przeprowadzić czyszczenie, np. usunąć lokalnie zapisane w pamięci podręcznej mapowania połączeń używane do obsługi wywołań zwrotnych.