สร้างแอปพลิเคชันโทรศัพท์เริ่มต้น

แอปพลิเคชันโทรศัพท์เริ่มต้นช่วยให้เฟรมเวิร์ก Android Telecom แจ้งสถานะการโทรให้แอปพลิเคชันของคุณทราบโดยใช้เครื่องมือจัดการบทบาทและบริการระหว่างการโทรเพื่อสร้างแอปทดแทนแอปโทรศัพท์เริ่มต้นในอุปกรณ์ Android, ใช้ InCallService API การติดตั้งใช้งานต้องเป็นไปตามข้อกำหนดต่อไปนี้

โดยต้องไม่มีความสามารถในการโทร และต้องประกอบด้วยอินเทอร์เฟซผู้ใช้สำหรับการโทรเท่านั้น โดยต้องจัดการการโทรทั้งหมดที่เฟรมเวิร์ก Telecom ทราบ และไม่ตั้งสมมติฐานเกี่ยวกับลักษณะของการโทร ตัวอย่างเช่น แอปต้องไม่ถือว่าการโทรเป็นการโทรผ่านระบบโทรศัพท์ที่ใช้ซิม และต้องไม่ใช้ข้อจำกัดการโทรที่อิงตาม ConnectionService ใดๆ เช่น การบังคับใช้ข้อจำกัดของระบบโทรศัพท์สำหรับการวิดีโอคอล

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

ตัวอย่างแอปการโทร
ตัวอย่างแอปการโทรที่ใช้อินเทอร์เฟซผู้ใช้ของตนเอง

เฟรมเวิร์ก Android มีแพ็กเกจ android.telecom ซึ่งมีคลาสที่ช่วยคุณสร้างแอปการโทรตามเฟรมเวิร์กโทรคมนาคม การสร้างแอปตามเฟรมเวิร์กโทรคมนาคมมีประโยชน์ดังนี้

  • แอปของคุณทำงานร่วมกับระบบย่อยโทรคมนาคมแบบเนทีฟในอุปกรณ์ได้อย่างถูกต้อง
  • แอปของคุณทำงานร่วมกับแอปการโทรอื่นๆ ที่เป็นไปตามเฟรมเวิร์กได้อย่างถูกต้อง
  • เฟรมเวิร์กนี้ช่วยให้แอปจัดการการกำหนดเส้นทางเสียงและวิดีโอได้
  • เฟรมเวิร์กนี้ช่วยให้แอปของคุณระบุได้ว่าการโทรมีโฟกัสหรือไม่

การประกาศและสิทธิ์ในไฟล์ Manifest

ในไฟล์ Manifest ของแอป ให้ประกาศว่าแอปใช้สิทธิ์ MANAGE_OWN_CALLS ดังที่แสดงในตัวอย่างต่อไปนี้

<manifest … >
    <uses-permission android:name="android.permission.MANAGE_OWN_CALLS"/>
</manifest>

ดูข้อมูลเพิ่มเติมเกี่ยวกับการประกาศสิทธิ์ของแอปได้ที่สิทธิ์

คุณต้องประกาศบริการที่ระบุคลาสที่ใช้คลาส ConnectionService ในแอป ระบบย่อยโทรคมนาคมกำหนดให้บริการต้องประกาศสิทธิ์ BIND_TELECOM_CONNECTION_SERVICE เพื่อให้สามารถเชื่อมโยงกับบริการได้ ตัวอย่างต่อไปนี้แสดงวิธีประกาศบริการในไฟล์ Manifest ของแอป

<service android:name="com.example.MyConnectionService"
    android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.ConnectionService" />
    </intent-filter>
</service>

ดูข้อมูลเพิ่มเติมเกี่ยวกับการประกาศคอมโพเนนต์ของแอป ซึ่งรวมถึงบริการต่างๆ ได้ที่คอมโพเนนต์ของแอป

ใช้บริการการเชื่อมต่อ

แอปการโทรต้องมีการติดตั้งใช้งานคลาส ConnectionService ที่ระบบย่อยของโทรคมนาคมสามารถเชื่อมโยงได้ การติดตั้งใช้งาน ConnectionService ควรลบล้างเมธอดต่อไปนี้

onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)

ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอดนี้เพื่อตอบสนองต่อแอปของคุณที่เรียกใช้ placeCall(Uri, Bundle) เพื่อสร้างสายโทรออกใหม่ แอปจะแสดงผลอินสแตนซ์ใหม่ของการติดตั้งใช้งานคลาส Connection (ดูข้อมูลเพิ่มเติมได้ที่ติดตั้งใช้งานการเชื่อมต่อ) เพื่อแสดงสายโทรออกใหม่ คุณสามารถปรับแต่งการเชื่อมต่อขาออกเพิ่มเติมได้โดยทำตามขั้นตอนต่อไปนี้

  • แอปควรเรียกใช้เมธอด setConnectionProperties(int) โดยมีค่าคงที่ PROPERTY_SELF_MANAGED เป็นอาร์กิวเมนต์เพื่อระบุว่าการเชื่อมต่อมาจากแอปการโทร
  • หากแอปรองรับการพักสาย ให้เรียกใช้เมธอด setConnectionCapabilities(int) และตั้งค่าอาร์กิวเมนต์เป็นค่าบิตมาสก์ของค่าคงที่ CAPABILITY_HOLD และ CAPABILITY_SUPPORT_HOLD
  • หากต้องการตั้งชื่อผู้โทร ให้ใช้เมธอด setCallerDisplayName(String, int) โดยส่งค่าคงที่ PRESENTATION_ALLOWED เป็นพารามิเตอร์ int เพื่อระบุว่าควรแสดงชื่อผู้โทร
  • เพื่อให้แน่ใจว่าสายโทรออกมีสถานะวิดีโอที่เหมาะสม ให้เรียกใช้เมธอด setVideoState(int) ของออบเจ็กต์ Connection และส่งค่าที่แสดงผลโดยเมธอด getVideoState() ของออบเจ็กต์ ConnectionRequest
onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest)

ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอดนี้เมื่อแอปของคุณเรียกใช้เมธอด placeCall(Uri, Bundle) และไม่สามารถโทรออกได้ เมื่อเกิดสถานการณ์นี้ แอปควรแจ้งให้ผู้ใช้ทราบ (เช่น ใช้กล่องแจ้งเตือนหรือข้อความโทสต์) ว่าไม่สามารถโทรออกได้ แอปของคุณอาจโทรออกไม่ได้หากมีการโทรฉุกเฉินที่ดำเนินอยู่ หรือหากมีการโทรที่ดำเนินอยู่ในแอปอื่นซึ่งไม่สามารถพักสายก่อนที่จะโทรออกได้

onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)

ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอดนี้เมื่อแอปของคุณเรียกใช้เมธอด addNewIncomingCall(PhoneAccountHandle, Bundle) เพื่อแจ้งระบบเกี่ยวกับสายเรียกเข้าใหม่ในแอปของคุณ แอปของคุณจะแสดงผลอินสแตนซ์ใหม่ของการติดตั้งใช้งาน Connection (ดูข้อมูลเพิ่มเติมได้ที่ติดตั้งใช้งานการเชื่อมต่อ) เพื่อแสดงสายเรียกเข้าใหม่ คุณสามารถปรับแต่งการเชื่อมต่อขาเข้าเพิ่มเติมได้โดยดำเนินการต่อไปนี้

  • แอปควรเรียกใช้เมธอด setConnectionProperties(int) โดยมีค่าคงที่ PROPERTY_SELF_MANAGED เป็นอาร์กิวเมนต์เพื่อระบุว่าการเชื่อมต่อมาจากแอปการโทร
  • หากแอปรองรับการพักสาย ให้เรียกใช้เมธอด setConnectionCapabilities(int) และตั้งค่าอาร์กิวเมนต์เป็นค่าบิตมาสก์ของค่าคงที่ CAPABILITY_HOLD และ CAPABILITY_SUPPORT_HOLD
  • หากต้องการตั้งชื่อผู้โทร ให้ใช้เมธอด setCallerDisplayName(String, int) โดยส่งค่าคงที่ PRESENTATION_ALLOWED เป็นพารามิเตอร์ int เพื่อระบุว่าควรแสดงชื่อผู้โทร
  • หากต้องการระบุหมายเลขโทรศัพท์หรือที่อยู่ของสายเรียกเข้า ให้ใช้เมธอด setAddress(Uri, int) ของออบเจ็กต์ Connection
  • เพื่อให้แน่ใจว่าสายโทรออกมีสถานะวิดีโอที่เหมาะสม ให้เรียกใช้เมธอด setVideoState(int) ของออบเจ็กต์ Connection และส่งค่าที่แสดงผลโดยเมธอด getVideoState() ของออบเจ็กต์ ConnectionRequest
onCreateIncomingConnectionFailed(PhoneAccountHandle, ConnectionRequest)

ระบบย่อยของ Telecom จะเรียกใช้เมธอดนี้เมื่อแอปของคุณเรียกใช้เมธอด addNewIncomingCall(PhoneAccountHandle, Bundle) เพื่อแจ้ง Telecom เกี่ยวกับสายเรียกเข้าใหม่ แต่สายเรียกเข้าไม่ได้รับอนุญาต (ดูข้อมูลเพิ่มเติมได้ที่ข้อจำกัดการโทร) แอปของคุณควรปฏิเสธสายเรียกเข้าโดยไม่มีเสียง และอาจโพสต์การแจ้งเตือนเพื่อแจ้งให้ผู้ใช้ทราบเกี่ยวกับสายที่ไม่ได้รับ

ใช้การเชื่อมต่อ

แอปของคุณควรสร้างคลาสย่อยของ Connection เพื่อแสดงการโทรในแอป คุณควรลบล้างเมธอดต่อไปนี้ในการติดตั้งใช้งาน

onShowIncomingCallUi()

ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอดนี้เมื่อคุณเพิ่มสายเรียกเข้าใหม่ และแอปของคุณควรแสดง UI สายเรียกเข้า

onCallAudioStateChanged(CallAudioState)

ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอดนี้เพื่อแจ้งให้แอปทราบว่าเส้นทางหรือโหมดเสียงปัจจุบันมีการเปลี่ยนแปลง ระบบจะเรียกใช้เมธอดนี้เพื่อตอบสนองต่อแอปที่เปลี่ยนโหมดเสียงโดยใช้เมธอด setAudioRoute(int) นอกจากนี้ ระบบอาจเรียกใช้เมธอดนี้หากมีการเปลี่ยนเส้นทางเสียง (เช่น เมื่อชุดหูฟังบลูทูธยกเลิกการเชื่อมต่อ)

onHold()

ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอดนี้เมื่อต้องการพักสาย เพื่อตอบสนองต่อคำขอนี้ แอปของคุณควรพักสายไว้ แล้วเรียกใช้เมธอด setOnHold() เพื่อแจ้งให้ระบบทราบว่ามีการพักสายอยู่ ระบบย่อยของโทรคมนาคมอาจเรียกใช้เมธอดนี้เมื่อบริการระหว่างการโทร เช่น Android Auto ที่แสดงการโทรต้องการส่งต่อคำขอของผู้ใช้เพื่อพักสาย ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอดนี้ด้วยหากผู้ใช้โทรออกในแอปอื่น ดูข้อมูลเพิ่มเติมเกี่ยวกับบริการระหว่างการโทรได้ที่ InCallService

onUnhold()

ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอดนี้เมื่อต้องการกลับมาโทรต่อหลังจากที่พักสายไว้ เมื่อแอปกลับมาโทรต่อแล้ว แอปควรเรียกใช้เมธอด setActive() เพื่อแจ้งให้ระบบทราบว่าการโทรไม่ได้ถูกพักสายอีกต่อไป ระบบย่อยของโทรคมนาคมอาจเรียกใช้เมธอดนี้เมื่อบริการระหว่างการโทร เช่น Android Auto ที่แสดงการโทรของคุณต้องการส่งต่อคำขอเพื่อกลับมาโทรต่อ ดูข้อมูลเพิ่มเติมเกี่ยวกับบริการระหว่างการโทรได้ที่ InCallService

onAnswer()

ระบบย่อยของ Telecom จะเรียกใช้เมธอดนี้เพื่อแจ้งให้แอปทราบว่าควรรับสายเรียกเข้า เมื่อแอปของคุณรับสายแล้ว แอปควรเรียกใช้เมธอด setActive() เพื่อแจ้งให้ระบบทราบว่ามีการรับสายแล้ว ระบบย่อยของโทรคมนาคมอาจเรียกใช้เมธอดนี้เมื่อแอปของคุณเพิ่มสายเรียกเข้าใหม่และมีสายที่ดำเนินอยู่แล้วในแอปอื่นซึ่งพักสายไม่ได้ ระบบย่อยของโทรคมนาคมจะแสดง UI สายเรียกเข้าในนามของแอปในกรณีเหล่านี้ เฟรมเวิร์กนี้มีเมธอดที่โอเวอร์โหลดซึ่งรองรับการระบุสถานะวิดีโอที่จะรับสาย ดูข้อมูลเพิ่มเติมได้ที่ onAnswer(int)

onReject()

ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอดนี้เมื่อต้องการปฏิเสธสายเรียกเข้า เมื่อแอปปฏิเสธการโทรแล้ว แอปควรเรียกใช้ setDisconnected(DisconnectCause) และระบุ REJECTED เป็นพารามิเตอร์ จากนั้นแอปควรเรียกใช้เมธอด destroy() เพื่อแจ้งให้ระบบทราบว่าแอปได้ประมวลผลการโทรแล้ว ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอดนี้เมื่อผู้ใช้ปฏิเสธสายเรียกเข้าจากแอปของคุณ

onDisconnect()

ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอดนี้เมื่อต้องการยกเลิกการเชื่อมต่อสาย เมื่อการโทรสิ้นสุดลง แอปควรเรียกใช้เมธอด setDisconnected(DisconnectCause) และระบุ LOCAL เป็นพารามิเตอร์เพื่อระบุว่าคำขอของผู้ใช้ทำให้การโทรถูกตัดการเชื่อมต่อ จากนั้นแอปควรเรียกใช้เมธอด destroy() เพื่อแจ้งระบบย่อยของโทรคมนาคมว่าแอปได้ประมวลผลการโทรแล้ว ระบบอาจเรียกใช้เมธอดนี้เมื่อผู้ใช้ยกเลิกการเชื่อมต่อการโทรผ่านบริการระหว่างการโทรอื่น เช่น Android Auto ระบบจะเรียกใช้เมธอดนี้เมื่อต้องยกเลิกการเชื่อมต่อการโทรของคุณเพื่อให้โทรออกอื่นๆ ได้ เช่น หากผู้ใช้ต้องการโทรฉุกเฉิน ดูข้อมูลเพิ่มเติมเกี่ยวกับบริการระหว่างการโทรได้ที่ InCallService

จัดการสถานการณ์การโทรที่พบบ่อย

การใช้ ConnectionService API ในขั้นตอนการโทรเกี่ยวข้องกับการโต้ตอบกับคลาสอื่นๆ ในแพ็กเกจ android.telecom ส่วนต่อไปนี้จะอธิบายสถานการณ์การโทรที่พบบ่อยและวิธีที่แอปควรใช้ API เพื่อจัดการสถานการณ์เหล่านั้น

รับสายเรียกเข้า

ขั้นตอนการจัดการสายเรียกเข้าจะเปลี่ยนไปตามการมีสายในแอปอื่นๆ หรือไม่ สาเหตุที่ขั้นตอนแตกต่างกันคือเฟรมเวิร์กโทรคมนาคมต้องกำหนดข้อจำกัดบางอย่างเมื่อมีการโทรที่ดำเนินอยู่ในแอปอื่นๆ เพื่อให้มั่นใจว่าสภาพแวดล้อมการทำงานของแอปการโทรทั้งหมดในอุปกรณ์มีความเสถียร ดูข้อมูลเพิ่มเติมได้ที่ข้อจำกัดในการโทร

ไม่มีการโทรที่ใช้งานอยู่ในแอปอื่นๆ

หากต้องการรับสายเรียกเข้าเมื่อไม่มีสายที่ใช้งานอยู่ในแอปอื่นๆ ให้ทำตามขั้นตอนต่อไปนี้

  1. แอปของคุณได้รับสายเรียกเข้าใหม่โดยใช้กลไกตามปกติ
  2. ใช้เมธอด addNewIncomingCall(PhoneAccountHandle, Bundle) เพื่อแจ้งระบบย่อยของโทรคมนาคมเกี่ยวกับสายเรียกเข้าใหม่
  3. ระบบย่อยของโทรคมนาคมจะเชื่อมโยงกับการติดตั้งใช้งาน ConnectionService ของแอปและขออินสแตนซ์ใหม่ของคลาส Connection ที่แสดงถึงสายเรียกเข้าใหม่โดยใช้เมธอด onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)
  4. ระบบย่อยของโทรคมนาคมจะแจ้งให้แอปทราบว่าควรแสดงอินเทอร์เฟซผู้ใช้ของสายเรียกเข้าโดยใช้เมธอด onShowIncomingCallUi()
  5. แอปของคุณแสดง UI ขาเข้าโดยใช้การแจ้งเตือนที่มี Intent เต็มหน้าจอที่เชื่อมโยง ดูข้อมูลเพิ่มเติมได้ที่ onShowIncomingCallUi()
  6. เรียกใช้เมธอด setActive() หากผู้ใช้ยอมรับสายเรียกเข้า หรือ setDisconnected(DisconnectCause) โดยระบุ REJECTED เป็นพารามิเตอร์ ตามด้วยการเรียกใช้เมธอด destroy() หากผู้ใช้ปฏิเสธสายเรียกเข้า

การโทรที่ใช้งานอยู่ในแอปอื่นๆ ซึ่งพักสายไม่ได้

หากต้องการรับสายเรียกเข้าเมื่อมีสายที่กำลังสนทนาอยู่ในแอปอื่นๆ ซึ่งไม่สามารถพักสายได้ ให้ทำตามขั้นตอนต่อไปนี้

  1. แอปของคุณได้รับสายเรียกเข้าใหม่โดยใช้กลไกตามปกติ
  2. ใช้เมธอด addNewIncomingCall(PhoneAccountHandle, Bundle) เพื่อแจ้งระบบย่อยของโทรคมนาคมเกี่ยวกับสายเรียกเข้าใหม่
  3. ระบบย่อยของโทรคมนาคมจะเชื่อมโยงกับการติดตั้งใช้งาน ConnectionService ของแอปและขออินสแตนซ์ใหม่ของออบเจ็กต์ Connection ที่แสดงถึงสายเรียกเข้าใหม่โดยใช้เมธอด onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)
  4. ระบบย่อยของโทรคมนาคมจะแสดง UI สายเรียกเข้าสำหรับสายเรียกเข้าของคุณ
  5. หากผู้ใช้รับสาย ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอด onAnswer() คุณควรเรียกใช้เมธอด setActive() เพื่อระบุให้ระบบย่อยของโทรคมนาคมทราบว่าการโทรเชื่อมต่อแล้ว
  6. หากผู้ใช้ปฏิเสธสาย ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอด onReject() คุณควรเรียกใช้เมธอด setDisconnected(DisconnectCause) โดยระบุ REJECTED เป็นพารามิเตอร์ ตามด้วยการเรียกใช้เมธอด destroy()

โทรออก

ขั้นตอนการโทรออกเกี่ยวข้องกับการจัดการความเป็นไปได้ที่การโทรออกไม่สำเร็จเนื่องจากข้อจำกัดที่กำหนดโดยเฟรมเวิร์กโทรคมนาคม ดูข้อมูลเพิ่มเติมได้ที่ข้อจำกัดในการโทร

หากต้องการโทรออก ให้ทำตามขั้นตอนต่อไปนี้

  1. ผู้ใช้เริ่มสายโทรออกภายในแอปของคุณ
  2. ใช้เมธอด placeCall(Uri, Bundle) เพื่อแจ้งระบบย่อยของโทรคมนาคมเกี่ยวกับสายโทรออกใหม่ พิจารณาพารามิเตอร์เมธอดต่อไปนี้
    • พารามิเตอร์ Uri แสดงที่อยู่ที่มีการโทรออก สำหรับหมายเลขโทรศัพท์ปกติ ให้ใช้สคีม URI tel:
    • พารามิเตอร์ Bundle ช่วยให้คุณระบุข้อมูลเกี่ยวกับแอปการโทรได้โดยการเพิ่มออบเจ็กต์ PhoneAccountHandle ของแอปไปยังส่วนเสริม EXTRA_PHONE_ACCOUNT_HANDLE แอปของคุณต้องระบุออบเจ็กต์ PhoneAccountHandle ให้กับสายโทรออกทุกสาย
    • พารามิเตอร์ Bundle ยังช่วยให้คุณระบุได้ว่าสายโทรออกมีวิดีโอหรือไม่โดยระบุค่า STATE_BIDIRECTIONAL ใน EXTRA_START_CALL_WITH_VIDEO_STATE เพิ่มเติม โปรดทราบว่าโดยค่าเริ่มต้น ระบบย่อยของโทรคมนาคมจะกำหนดเส้นทางวิดีโอคอลไปยังลำโพง
  3. ระบบย่อยของ Telecom จะเชื่อมโยงกับการติดตั้งใช้งาน ConnectionService ของแอป
  4. หากแอปไม่สามารถโทรออกได้ ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอด onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest) เพื่อแจ้งให้แอปทราบว่าไม่สามารถโทรออกได้ในขณะนี้ แอปควรแจ้งให้ผู้ใช้ทราบว่าไม่สามารถโทรออกได้
  5. หากแอปของคุณโทรออกได้ ระบบย่อยของโทรคมนาคมจะเรียกใช้เมธอด onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest) แอปควรแสดงผลอินสแตนซ์ของคลาส Connection เพื่อแสดงสายโทรออกใหม่ ดูข้อมูลเพิ่มเติมเกี่ยวกับพร็อพเพอร์ตี้ที่ควรตั้งค่าในการเชื่อมต่อได้ที่ใช้บริการการเชื่อมต่อ
  6. เมื่อเชื่อมต่อสายโทรออกแล้ว ให้เรียกใช้เมธอด setActive() เพื่อแจ้งระบบย่อยของโทรคมนาคมว่าสายกำลังทำงานอยู่

วางสาย

หากต้องการวางสาย ให้ทำตามขั้นตอนต่อไปนี้

  1. เรียกใช้ setDisconnected(DisconnectCause) โดยส่ง LOCAL เป็นพารามิเตอร์หากผู้ใช้สิ้นสุดการโทร หรือส่ง REMOTE เป็นพารามิเตอร์หากอีกฝ่ายสิ้นสุดการโทร
  2. เรียกใช้เมธอด destroy()

ข้อจำกัดการโทร

เฟรมเวิร์กโทรคมนาคมจะบังคับใช้ข้อจำกัดบางอย่างสำหรับการจัดการการโทรในอุปกรณ์ เพื่อให้ผู้ใช้ได้รับประสบการณ์การโทรที่สอดคล้องและเรียบง่าย ตัวอย่างเช่น สมมติว่าผู้ใช้ติดตั้งแอปการโทร 2 แอปที่ใช้ API ConnectionService ที่จัดการด้วยตนเอง ได้แก่ FooTalk และ BarTalk ในกรณีนี้ จะมีข้อจำกัดดังต่อไปนี้

  • ในอุปกรณ์ที่ใช้ระดับ API 27 หรือต่ำกว่า จะมีแอปเดียวเท่านั้นที่สามารถรักษาการโทรที่ดำเนินอยู่ได้ ณ เวลาใดเวลาหนึ่ง ข้อจำกัดนี้หมายความว่าขณะที่ผู้ใช้กำลังโทรโดยใช้แอป FooTalk แอป BarTalk จะเริ่มหรือรับสายใหม่ไม่ได้

    ในอุปกรณ์ที่ใช้ระดับ API 28 ขึ้นไป หากทั้ง FooTalk และ BarTalk ประกาศสิทธิ์ CAPABILITY_SUPPORT_HOLD และ CAPABILITY_HOLD ผู้ใช้จะสามารถรักษาการโทรที่ดำเนินอยู่ได้มากกว่า 1 สายโดยสลับระหว่างแอปเพื่อเริ่มหรือรับสายอื่น

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

  • ระบบย่อยของโทรคมนาคมจะยกเลิกการเชื่อมต่อการโทรของแอปหากผู้ใช้โทรฉุกเฉิน

  • แอปของคุณจะรับสายหรือโทรออกไม่ได้ขณะที่ผู้ใช้กำลังโทรหาหมายเลขฉุกเฉิน

  • หากมีสายที่สนทนาอยู่แล้วในแอปการโทรอื่นเมื่อแอปของคุณได้รับสายเรียกเข้า การรับสายเรียกเข้าจะวางสายที่สนทนาอยู่แล้วในแอปอื่น แอปของคุณไม่ควรแสดงอินเทอร์เฟซผู้ใช้สำหรับสายเรียกเข้าตามปกติ เฟรมเวิร์กโทรคมนาคมจะแสดงอินเทอร์เฟซผู้ใช้ของสายเรียกเข้าและแจ้งให้ผู้ใช้ทราบว่าการรับสายใหม่จะวางสายที่สนทนาอยู่ ซึ่งหมายความว่าหากผู้ใช้อยู่ในสาย FooTalk และแอป BarTalk ได้รับสายเรียกเข้า เฟรมเวิร์กโทรคมนาคมจะแจ้งให้ผู้ใช้ทราบว่ามีสายเรียกเข้าใหม่จาก BarTalk และการรับสาย BarTalk จะเป็นการวางสาย FooTalk

การเป็นแอปโทรศัพท์เริ่มต้น

แอปโทรศัพท์/แป้นโทรศัพท์เริ่มต้นคือแอปที่แสดงอินเทอร์เฟซผู้ใช้ขณะกำลังใช้สายเมื่ออุปกรณ์กำลังมีการโทร นอกจากนี้ยังช่วยให้ผู้ใช้เริ่มการโทรและดูประวัติการโทรในอุปกรณ์ได้ด้วย อุปกรณ์จะมาพร้อมกับแอปโทรศัพท์/แอปโทรศัพท์เริ่มต้นที่ระบบมีให้ ผู้ใช้อาจเลือกแอปเดียวเพื่อรับบทบาทนี้จากแอประบบ แอปที่ต้องการทำหน้าที่นี้จะใช้ RoleManager เพื่อขอให้ทำหน้าที่ RoleManager.ROLE_DIALER

แอปโทรศัพท์เริ่มต้นจะแสดงอินเทอร์เฟซผู้ใช้ขณะที่อุปกรณ์กำลังโทร และอุปกรณ์ไม่ได้อยู่ในโหมดรถยนต์ (กล่าวคือ UiModeManager#getCurrentModeType() ไม่ใช่ Configuration.UI_MODE_TYPE_CAR)

แอปต้องมีคุณสมบัติตรงตามข้อกำหนดต่อไปนี้จึงจะทำหน้าที่เป็น RoleManager.ROLE_DIALER ได้

  • โดยต้องจัดการ Intent Intent#ACTION_DIAL ซึ่งหมายความว่าแอปต้องมี UI แป้นกดหมายเลขเพื่อให้ผู้ใช้เริ่มสายโทรออกได้
  • โดยต้องใช้ InCallService API อย่างเต็มรูปแบบและมีทั้ง UI สายเรียกเข้าและ UI สายที่กำลังสนทนาอยู่

ระบบจะใช้แป้นโทรศัพท์ที่โหลดไว้ล่วงหน้าเสมอเมื่อผู้ใช้โทรฉุกเฉิน แม้ว่าแอปของคุณจะทำหน้าที่เป็น RoleManager.ROLE_DIALER ก็ตาม เพื่อให้ได้รับประสบการณ์การใช้งานที่ดีที่สุดเมื่อโทรฉุกเฉิน แป้นโทรศัพท์เริ่มต้นควรใช้ TelecomManager.placeCall(Uri, Bundle) เพื่อโทรออก (รวมถึงการโทรฉุกเฉิน) เสมอ วิธีนี้ช่วยให้แพลตฟอร์มยืนยันได้ว่าคำขอมาจากแป้นโทรศัพท์เริ่มต้น หากแอปโทรศัพท์ที่ไม่ได้โหลดไว้ล่วงหน้าใช้ Intent#ACTION_CALL เพื่อโทรฉุกเฉิน ระบบจะส่งต่อการโทรไปยังแอปโทรศัพท์ที่โหลดไว้ล่วงหน้าโดยใช้ Intent#ACTION_DIAL เพื่อยืนยัน ซึ่งเป็นประสบการณ์ของผู้ใช้ที่ไม่เหมาะสม

ด้านล่างนี้คือตัวอย่างการลงทะเบียนไฟล์ Manifest สำหรับ InCallService ข้อมูลเมตา TelecomManager#METADATA_IN_CALL_SERVICE_UI บ่งชี้ว่าการติดตั้งใช้งาน InCallService นี้มีจุดประสงค์เพื่อแทนที่ UI ระหว่างการโทรในตัว ข้อมูลเมตา TelecomManager#METADATA_IN_CALL_SERVICE_RINGING บ่งชี้ว่า InCallService นี้จะเล่นเสียงเรียกเข้าสำหรับสายเรียกเข้า ดูข้อมูลเพิ่มเติมเกี่ยวกับการแสดง UI สายเรียกเข้าและการเล่นเสียงเรียกเข้าในแอปได้ที่ด้านล่าง

 <service android:name="your.package.YourInCallServiceImplementation"
          android:permission="android.permission.BIND_INCALL_SERVICE"
          android:exported="true">
      <meta-data android:name="android.telecom.IN_CALL_SERVICE_UI" android:value="true" />
      <meta-data android:name="android.telecom.IN_CALL_SERVICE_RINGING"
          android:value="true" />
      <intent-filter>
          <action android:name="android.telecom.InCallService"/>
      </intent-filter>
 </service>

หมายเหตุ: คุณไม่ควรทำเครื่องหมาย InCallService ด้วยแอตทริบิวต์ android:exported="false" เพราะอาจทำให้เชื่อมโยงกับการติดตั้งใช้งานของคุณไม่สำเร็จระหว่างการโทร

นอกเหนือจากการใช้ InCallService API แล้ว คุณยังต้องประกาศกิจกรรมในไฟล์ Manifest ซึ่งจัดการ Intent Intent#ACTION_DIAL ด้วย ตัวอย่างด้านล่างแสดงวิธีการดำเนินการนี้

 <activity android:name="your.package.YourDialerActivity"
           android:label="@string/yourDialerActivityLabel">
      <intent-filter>
           <action android:name="android.intent.action.DIAL" />
           <category android:name="android.intent.category.DEFAULT" />
      </intent-filter>
      <intent-filter>
           <action android:name="android.intent.action.DIAL" />
           <category android:name="android.intent.category.DEFAULT" />
           <data android:scheme="tel" />
      </intent-filter>
 </activity>

เมื่อผู้ใช้ติดตั้งแอปพลิเคชันและเรียกใช้เป็นครั้งแรก คุณควรใช้ RoleManager เพื่อแจ้งให้ผู้ใช้ทราบว่าต้องการให้แอปของคุณเป็นแอปโทรศัพท์เริ่มต้นใหม่หรือไม่

โค้ดด้านล่างแสดงวิธีที่แอปของคุณสามารถขอเป็นแอปโทรศัพท์/แป้นโทรศัพท์เริ่มต้นได้

 private static final int REQUEST_ID = 1;

 public void requestRole() {
     RoleManager roleManager = (RoleManager) getSystemService(ROLE_SERVICE);
     Intent intent = roleManager.createRequestRoleIntent(RoleManager.ROLE_DIALER);
     startActivityForResult(intent, REQUEST_ID);
 }

 public void onActivityResult(int requestCode, int resultCode, Intent data) {
     if (requestCode == REQUEST_ID) {
         if (resultCode == android.app.Activity.RESULT_OK) {
             // Your app is now the default dialer app
         } else {
             // Your app is not the default dialer app
         }
     }
 }

สิทธิ์เข้าถึง InCallService สำหรับอุปกรณ์ที่สวมใส่ได้

หากแอปของคุณเป็นแอปที่ใช้ร่วมกันของบุคคลที่สามและต้องการเข้าถึง InCallService API สิ่งที่แอปของคุณทำได้มีดังนี้

  1. ประกาศสิทธิ์ MANAGE_ONGOING_CALLS ในไฟล์ Manifest
  2. เชื่อมโยงกับอุปกรณ์ที่สวมใส่ได้จริงผ่าน API CompanionDeviceManager เป็นแอปที่ใช้ร่วมกัน ดูการจับคู่อุปกรณ์ที่ใช้ร่วมกัน
  3. ใช้ InCallService นี้กับสิทธิ์ BIND_INCALL_SERVICE

การแสดงการแจ้งเตือนสายเรียกเข้า

เมื่อแอปของคุณได้รับสายเรียกเข้าใหม่ผ่าน InCallService#onCallAdded(Call) แอปจะมีหน้าที่แสดง UI สายเรียกเข้าสำหรับสายเรียกเข้านั้น โดยควรดำเนินการโดยใช้ API ของ NotificationManager เพื่อโพสต์การแจ้งเตือนสายเรียกเข้าใหม่

เมื่อแอปประกาศข้อมูลเมตา TelecomManager#METADATA_IN_CALL_SERVICE_RINGING แอปจะมีหน้าที่เล่นเสียงเรียกเข้าสำหรับสายเรียกเข้า แอปของคุณควรสร้าง NotificationChannel ซึ่งระบุเสียงเรียกเข้าที่ต้องการ เช่น

 NotificationChannel channel = new NotificationChannel(YOUR_CHANNEL_ID, "Incoming Calls",
          NotificationManager.IMPORTANCE_MAX);
 // other channel setup stuff goes here.

 // We'll use the default system ringtone for our incoming call notification channel.  You can
 // use your own audio resource here.
 Uri ringtoneUri = RingtoneManager.getDefaultUri(RingtoneManager.TYPE_RINGTONE);
 channel.setSound(ringtoneUri, new AudioAttributes.Builder()
          // Setting the AudioAttributes is important as it identifies the purpose of your
          // notification sound.
          .setUsage(AudioAttributes.USAGE_NOTIFICATION_RINGTONE)
          .setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
      .build());

 NotificationManager mgr = getSystemService(NotificationManager.class);
 mgr.createNotificationChannel(channel);

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

 // Create an intent which triggers your fullscreen incoming call user interface.
 Intent intent = new Intent(Intent.ACTION_MAIN, null);
 intent.setFlags(Intent.FLAG_ACTIVITY_NO_USER_ACTION | Intent.FLAG_ACTIVITY_NEW_TASK);
 intent.setClass(context, YourIncomingCallActivity.class);
 PendingIntent pendingIntent = PendingIntent.getActivity(context, 1, intent, PendingIntent.FLAG_MUTABLE_UNAUDITED);
 // Build the notification as an ongoing high priority item; this ensures it will show as
 // a heads up notification which slides down over top of the current content.
 final Notification.Builder builder = new Notification.Builder(context);
 builder.setOngoing(true);
 builder.setPriority(Notification.PRIORITY_HIGH);
 // Set notification content intent to take user to the fullscreen UI if user taps on the
 // notification body.
 builder.setContentIntent(pendingIntent);
 // Set full screen intent to trigger display of the fullscreen UI when the notification
 // manager deems it appropriate.
 builder.setFullScreenIntent(pendingIntent, true);
 // Setup notification content.
 builder.setSmallIcon( yourIconResourceId );
 builder.setContentTitle("Your notification title");
 builder.setContentText("Your notification content.");
 // Use builder.addAction(..) to add buttons to answer or reject the call.
 NotificationManager notificationManager = mContext.getSystemService(
     NotificationManager.class);
 notificationManager.notify(YOUR_CHANNEL_ID, YOUR_TAG, YOUR_ID, builder.build());
```