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 systemowej do wybierania numerów i oddzwaniać bezpośrednio z niej. W tym przewodniku opisujemy wymagane zmiany w aplikacjach do połączeń VoIP, aplikacjach systemowych do wybierania numerów i zarządzaniu ustawieniami ujednoliconej historii połączeń.

Zmiany w aplikacji do połączeń

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

Rejestrowanie filtra intencji wywołania zwrotnego

Zarejestruj intencję chronioną przez system TelecomManager.ACTION_CALL_BACK.

Gdy ten filtr intencji zostanie prawidłowo zarejestrowany, wszystkie połączenia dodane przez aplikację za pomocą interfejsów CallsManager.addCall lub innych powiązanych interfejsów Telecom API 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 do wybierania numerów wpis logu 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

Wykluczanie rejestrowania połączeń

Gdy wywołanie zwrotne zostanie zarejestrowane, wszystkie połączenia będą rejestrowane w systemowym dialerze. Aby wykluczyć połączenia pojedynczo, ustaw wartość logiczną isLogExcluded na true w ramach 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 przez 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

Sprawdzanie wpisów w historii połączeń

Rejestr połączeń systemowych zawiera ograniczoną liczbę wpisów i ostatecznie usuwa stare rekordy połączeń. Aplikacja przechowuje mapowanie UUID na szczegóły połączenia w celu obsługi połączeń zwrotnych, dlatego powinna okresowo sprawdzać, które UUID nadal znajdują się w dzienniku połączeń systemowych. Jeśli UUID nie ma już w dzienniku systemowym, użytkownik nie może zainicjować oddzwonienia w przypadku tego połączenia, a aplikacja może bezpiecznie usunąć mapowanie z pamięci lokalnej. Pomaga to optymalizować miejsce na dane.

Aby uzyskać aktualną listę UUID przypisanych do aplikacji w ramach dziennika systemowego, użyj CallLog.Calls.CONTENT_VOIP_URI.

Zmiany w aplikacji Telefon

Aby włączyć wyświetlanie dzienników połączeń VoIP w aplikacji do wybierania numerów i inicjowanie połączeń zwrotnych do aplikacji VoIP, wykonaj te czynności.

Wyświetlanie logów połączeń VoIP w aplikacji telefonu

Domyślnie dzienniki połączeń z aplikacji VoIP nie są wyświetlane w aplikacji telefonu. Aby wyświetlić zintegrowane dzienniki połączeń w aplikacji telefonu, wykonaj te czynności:

• W Androidzie 16.1 (interfejs API na poziomie 36.1) dołącz parametr zapytania include_voip_calls do dostawcy treści CallLog.Calls, aby wyświetlać logi połączeń VoIP:

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

• Na Androidzie 17 (poziom interfejsu API 37) i nowszym użyj tego sformalizowanego dostawcy treści i klucza parametru:

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

Inicjowanie połączeń zwrotnych z aplikacji Telefon

Aby zainicjować oddzwonienie z dialera, użyj ikony TelecomManager.placeCall. Platforma używa unikalnego CallLog.Calls._ID wpisu logu rejestru połączeń, aby uruchomić odpowiednią 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. Ten zamiar zawiera dodatkowy parametr UUID in intent TelecomManager.EXTRA_UUID, który umożliwia aplikacji VoIP określenie, do której konkretnie rozmowy ma nastąpić oddzwonienie.

// 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 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 dzienniki połączeń lub bezpośrednio w domyślnej aplikacji do wybierania numerów). Z tymi ustawieniami mogą współpracować zarówno aplikacje do nawiązywania połączeń innych firm, jak i aplikacje do wybierania numerów.

Przekierowywanie użytkowników do ustawień

Aby otworzyć ustawienia ujednoliconej historii połączeń, rozpocznij działanie z użyciem działania intencji 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ń dla aplikacji w ustawieniach systemu, system natychmiast i trwale usunie wszystkie istniejące wpisy w rejestrze połączeń dla tego pakietu od natywnego dostawcy rejestru połączeń (CallLog.Calls). Przyszłe połączenia zainicjowane przez tę aplikację lub odebrane w jej ramach nie będą rejestrowane w systemowym dialerze.

Nasłuchiwanie zmian preferencji

Aby zachować synchronizację, gdy użytkownik włączy lub wyłączy ujednoliconą historię połączeń w aplikacji do dzwonienia w ustawieniach systemu lub w aplikacji do wybierania numerów, 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 przycisk, platforma wyśle do Twojej aplikacji intencję zawierającą zaktualizowany stan logiczny w dodatku 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 buforowane mapowania połączeń używane do obsługi wywołań zwrotnych.