ประวัติการโทรแบบรวม

แอปพลิเคชัน VoIP สามารถผสานรวมการโทรเข้ากับบันทึกการโทรของระบบ ซึ่งจะช่วยให้ผู้ใช้ดูประวัติการโทร VoIP ได้จากส่วนกลางในแอปโทรศัพท์ของระบบ และโทรกลับได้โดยตรงจากแอปโทรศัพท์ คู่มือนี้จะอธิบายการ เปลี่ยนแปลงที่จำเป็นสำหรับ แอปโทร VoIP, แอปโทรศัพท์ของระบบ และ การจัดการการตั้งค่าประวัติการโทรแบบรวม

การเปลี่ยนแปลงสำหรับแอปการโทร

หากต้องการผสานรวมแอป VoIP กับบันทึกการโทรของระบบ ให้ทำตามขั้นตอนต่อไปนี้

ลงทะเบียนตัวกรอง Intent ของการติดต่อกลับ

ลงทะเบียน Intent ที่ระบบป้องกันไว้ TelecomManager.ACTION_CALL_BACK

เมื่อลงทะเบียนตัวกรอง Intent นี้อย่างถูกต้องแล้ว ระบบจะบันทึกการโทรที่แอปของคุณเพิ่มโดยใช้ CallsManager.addCall หรือ API อื่นๆ ที่เกี่ยวข้องของ Telecom โดยอัตโนมัติ ระบบจะใช้ Intent ที่ลงทะเบียนนี้เพื่อส่งการติดต่อกลับไปยังแอปของคุณในภายหลังเมื่อผู้ใช้เลือกรายการบันทึกการโทร 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>

ยกเว้นการบันทึกการโทร

เมื่อลงทะเบียนการติดต่อกลับแล้ว ระบบจะบันทึกการโทรทั้งหมดลงในแอปโทรศัพท์ของระบบ หากต้องการยกเว้นการโทรเป็นรายครั้ง ให้ตั้งค่า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
        ),
)

จัดการการติดต่อกลับ

การโทรที่เพิ่มผ่าน 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)
        )
    )
}

ยืนยันรายการบันทึกการโทร

บันทึกการโทรของระบบจะเก็บรายการไว้ตามจำนวนที่กำหนดและล้างบันทึกการโทรเก่าออกในที่สุด เนื่องจากแอปจัดเก็บการจับคู่ UUID กับรายละเอียดการโทรเพื่อจัดการการติดต่อกลับ แอปจึงควรตรวจสอบเป็นระยะๆ ว่า UUID ใดที่ยังอยู่ในบันทึกการโทรของระบบ หาก UUID ไม่อยู่ในบันทึกของระบบอีกต่อไป ผู้ใช้จะเริ่มการติดต่อกลับสำหรับการโทรนั้นไม่ได้ และแอปสามารถนำการจับคู่ออกจากที่เก็บข้อมูลในเครื่องได้อย่างปลอดภัย แนวทางปฏิบัตินี้ช่วยเพิ่มประสิทธิภาพที่เก็บข้อมูล

หากต้องการรับรายการ UUID ปัจจุบันที่ระบุไว้ในแอปภายในระบบ บันทึก ให้ใช้ CallLog.Calls.CONTENT_VOIP_URI

การเปลี่ยนแปลงสำหรับแอปโทรศัพท์

ทำตามขั้นตอนต่อไปนี้เพื่อเปิดใช้แอปโทรศัพท์ให้แสดงบันทึกการโทร VoIP และเริ่มการติดต่อกลับไปยังแอป VoIP

แสดงบันทึกการโทร VoIP ในแอปโทรศัพท์

โดยค่าเริ่มต้น บันทึกการโทรของแอป VoIP จะไม่ปรากฏในแอปโทรศัพท์ หากต้องการแสดงบันทึกการโทรที่ผสานรวมในแอปโทรศัพท์ ให้ทำดังนี้

  • ใน Android 16.1 (ระดับ API 36.1) ให้เพิ่มพารามิเตอร์การค้นหา include_voip_calls ลงใน Content Provider CallLog.Calls เพื่อแสดงบันทึกการโทร VoIP

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

  • ใน Android 17 (ระดับ API 37) ขึ้นไป ให้ใช้ Content Provider และคีย์พารามิเตอร์ที่เป็นทางการต่อไปนี้

เริ่มการติดต่อกลับจากแอปโทรศัพท์

หากต้องการเริ่มการติดต่อกลับจากแอปโทรศัพท์ ให้ใช้ TelecomManager.placeCall แพลตฟอร์มจะใช้ CallLog.Calls._ID ที่ไม่ซ้ำกันของรายการบันทึกการโทรเพื่อเปิดแอป VoIP ที่ถูกต้อง การเปิดนี้รวมถึง TelecomManager.ACTION_CALL_BACK Intent ซึ่งเป็นการดำเนินการที่ระบบกำหนดไว้สำหรับการเริ่มการโทรกลับ Intent นี้มี UUID ของการโทรใน Intent เพิ่มเติม 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)

จัดการการตั้งค่าประวัติการโทรแบบรวม

ตั้งแต่ Android 17 (ระดับ API 37) เป็นต้นไป ผู้ใช้จะดูและเปิด/ปิดประวัติการโทรแบบรวมได้เป็นรายแอปในการตั้งค่าระบบ (โดยปกติจะอยู่ในการตั้งค่า > บัญชีการโทร > บันทึกการโทรที่ผสานรวม หรือภายในแอปโทรศัพท์เริ่มต้นโดยตรง) ทั้งแอปโทรของบุคคลที่สามและแอปโทรศัพท์สามารถโต้ตอบกับการตั้งค่าเหล่านี้ได้

หากต้องการเปิดการตั้งค่าประวัติการโทรแบบรวม ให้เริ่มกิจกรรมด้วยการดำเนินการผ่าน Intent TelecomManager.ACTION_CONFIGURE_CALL_LOG_INTEGRATION

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

เมื่อผู้ใช้ปิดประวัติการโทรแบบรวมสำหรับแอปในการตั้งค่าระบบ ระบบจะล้างรายการบันทึกการโทรที่มีอยู่ทั้งหมดสำหรับแพ็กเกจนั้นออกจากผู้ให้บริการบันทึกการโทรดั้งเดิม (CallLog.Calls) ทันทีและถาวร ระบบจะไม่บันทึกการโทรในอนาคตที่เริ่มโดยหรือได้รับสำหรับแอปนั้นในแอปโทรศัพท์ของระบบ

ฟังการเปลี่ยนแปลงค่ากำหนด

หากต้องการซิงค์อยู่เสมอเมื่อผู้ใช้เปิดหรือปิดใช้ประวัติการโทรแบบรวมสำหรับ แอปการโทรของคุณในการตั้งค่าระบบหรือแอปโทรศัพท์ ให้ลงทะเบียน Broadcast Receiver สำหรับ Intent การออกอากาศ 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
            )
        }
    }
}

เมื่อผู้ใช้สลับปุ่มเปิด/ปิด แพลตฟอร์มจะออกอากาศ Intent นี้ไปยังแอปของคุณซึ่งมีสถานะบูลีนที่อัปเดตแล้วในส่วนเพิ่มเติม TelecomManager.EXTRA_VOIP_CALL_LOG_PREFERENCE_STATUS แอปของคุณสามารถฟังการออกอากาศนี้แทนการรอการยืนยันเป็นระยะๆ กับ CallLog.Calls เมื่อปิดใช้ประวัติการโทรแบบรวม (กล่าวคือ ตั้งค่าเป็น false) แอปของคุณจะอัปเดตสถานะภายในหรือทำการล้างข้อมูล เช่น ล้างการจับคู่การโทรที่แคชไว้ในเครื่องซึ่งใช้สำหรับการจัดการการติดต่อกลับ