היסטוריית שיחות מאוחדת

אפליקציות VoIP יכולות לשלב את השיחות שלהן ביומן של המערכת. האפשרות הזו מאפשרת למשתמשים לראות את היסטוריית השיחות שלהם ב-VoIP באופן מרכזי באפליקציית חייגן המערכת, ולהחזיר שיחות ישירות מאפליקציית החייגן. במדריך הזה מוסבר על השינויים הנדרשים באפליקציות לשיחות VoIP, באפליקציות חייגן המערכת ובהגדרות לניהול היסטוריית שיחות מאוחדת.

שינויים באפליקציה לשיחות

כדי לשלב את אפליקציית ה-VoIP עם יומן השיחות של המערכת, פועלים לפי השלבים הבאים.

רישום מסנן intent להתקשרות חזרה

רושמים את כוונת המשתמש המוגנת על ידי המערכת TelecomManager.ACTION_CALL_BACK.

אחרי שמסנן Intent הזה נרשם בצורה תקינה, כל השיחות שהאפליקציה מוסיפה באמצעות CallsManager.addCall או ממשקי API אחרים שקשורים ל-Telecom, יתועדו אוטומטית על ידי המערכת. המערכת משתמשת ב-Intent הרשום הזה כדי לשלוח בהמשך קריאה חוזרת (callback) לאפליקציה שלכם כשמשתמש בוחר רשומה של שיחת 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 כבר לא מופיע ביומן המערכת, המשתמש לא יכול ליזום קריאה חוזרת לשיחה הזו, והאפליקציה יכולה להסיר בבטחה את המיפוי מהאחסון המקומי שלה. השיטה הזו עוזרת לבצע אופטימיזציה של האחסון.

כדי לקבל את הרשימה הנוכחית של UUIDs שמשויכים לאפליקציה ביומן המערכת, משתמשים ב-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 הנכונה. ההפעלה הזו כוללת כוונה (intent) של 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 באמצעות פעולת Intent: TelecomManager.ACTION_CONFIGURE_CALL_LOG_INTEGRATION

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

כשמשתמש משבית את היסטוריית השיחות המאוחדת עבור אפליקציה בהגדרות המערכת, המערכת מוחקת באופן מיידי וקבוע את כל הרשומות הקיימות ביומן השיחות עבור החבילה הזו מספק יומן השיחות המקורי (CallLog.Calls). שיחות עתידיות שהתחילו באפליקציה הזו או שהתקבלו בה לא יתועדו בחייגן של המערכת.

האזנה לשינויים בהעדפות

כדי לשמור על סנכרון כשמשתמש מפעיל או משבית את היסטוריית השיחות המאוחדת באפליקציית השיחות שלכם בהגדרות המערכת או בחייגן, צריך לרשום מקלט שידור לשידור (broadcast) של 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), האפליקציה יכולה לעדכן את ערך דינמי הפנימי שלה או לבצע ניקוי נתונים, כמו ניקוי מיפוי השיחות ששמור במטמון המקומי ומשמש לטיפול בקריאה חוזרת (callback).