Ứng dụng gọi điện cho phép người dùng nhận hoặc thực hiện cuộc gọi thoại/video trên thiết bị của họ. Ứng dụng gọi điện dùng giao di���n người dùng riêng cho cuộc gọi thay vì dùng giao diện mặc định của ứng dụng Điện thoại, như minh hoạ trong ảnh chụp màn hình sau đây.
Khung Android bao gồm gói android.telecom
, chứa các lớp giúp bạn tạo ứng dụng gọi theo khung viễn thông. Việc xây dựng ứng dụng theo khung viễn thông sẽ mang lại các lợi ích sau:
- Ứng dụng của bạn tương tác chính xác với hệ thống con viễn thông gốc trong thiết bị.
- Ứng dụng của bạn tương tác chính xác với các ứng dụng gọi khác cũng tuân thủ khung này.
- Khung này giúp ứng dụng của bạn quản lý việc định tuyến âm thanh và video.
- Khung này giúp ứng dụng của bạn xác định xem các lệnh gọi của ứng dụng có tâm điểm hay không.
Quyền và nội dung khai báo trong tệp kê khai
Trong tệp kê khai ứng dụng, hãy khai báo rằng ứng dụng của bạn sử dụng quyền MANAGE_OWN_CALLS
, như trong ví dụ sau:
<manifest … >
<uses-permission android:name="android.permission.MANAGE_OWN_CALLS"/>
</manifest>
Để biết thêm thông tin về việc khai báo quyền cho ứng dụng, hãy xem bài viết Quyền.
Bạn phải khai báo một dịch vụ chỉ định lớp triển khai lớp ConnectionService
trong ứng dụng của bạn. Hệ thống viễn thông phụ yêu cầu dịch vụ khai báo quyền BIND_TELECOM_CONNECTION_SERVICE
để có thể liên kết với lớp đó. Ví dụ sau cho biết cách khai báo dịch vụ trong tệp kê khai ứng dụng:
<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>
Để biết thêm thông tin về cách khai báo các thành phần ứng dụng, bao gồm cả dịch vụ, hãy xem phần Thành phần ứng dụng.
Triển khai dịch vụ kết nối
Ứng dụng gọi của bạn phải cung cấp phương thức triển khai lớp ConnectionService
mà hệ thống viễn thông phụ có thể liên kết.
Quá trình triển khai ConnectionService
của bạn nên ghi đè các phương thức sau:
onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)
Hệ thống viễn thông phụ gọi phương thức này để phản hồi việc ứng dụng của bạn gọi
placeCall(Uri, Bundle)
để tạo một cuộc gọi đi mới. Ứng dụng của bạn trả về một thực thể mới của quá trình triển khai lớpConnection
(để biết thêm thông tin, hãy xem bài viết Triển khai kết nối) để biểu thị lệnh gọi đi mới. Bạn có thể tuỳ chỉnh thêm kết nối đi bằng cách thực hiện các thao tác sau:- Ứng dụng của bạn nên gọi phương thức
setConnectionProperties(int)
với hằng sốPROPERTY_SELF_MANAGED
làm đối số để cho biết rằng kết nối bắt nguồn từ một ứng dụng gọi. - Nếu ứng dụng của bạn hỗ trợ giữ lệnh gọi, hãy gọi phương thức
setConnectionCapabilities(int)
và đ��t đối số thành giá trị mặt nạ bit của các hằng sốCAPABILITY_HOLD
vàCAPABILITY_SUPPORT_HOLD
. - Để đặt tên của phương thức gọi, hãy sử dụng phương thức
setCallerDisplayName(String, int)
truyền hằng sốPRESENTATION_ALLOWED
làm tham sốint
để cho biết rằng tên của phương thức gọi sẽ được hiển thị. - Để đảm bảo lệnh gọi đi có trạng thái video thích hợp, hãy gọi phương thức
setVideoState(int)
của đối tượngConnection
và gửi giá trị được phương thứcgetVideoState()
của đối tượngConnectionRequest
trả về.
- Ứng dụng của bạn nên gọi phương thức
onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest)
Hệ thống viễn thông phụ gọi phương thức này khi ứng dụng của bạn gọi phương thức
placeCall(Uri, Bundle)
và không thể thực hiện cuộc gọi đi. Để đối phó với tình huống này, ứng dụng của bạn nên thông báo cho người dùng (ví dụ: sử dụng hộp cảnh báo hoặc thông báo ngắn) rằng không thể thực hiện cuộc gọi đi. Ứng dụng của bạn có thể không thực hiện được cuộc gọi nếu đang diễn ra một cuộc gọi khẩn cấp, hoặc nếu có một cuộc gọi đang diễn ra trong một ứng dụng khác nên không thể giữ máy trước khi thực hiện cuộc gọi.onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)
Hệ thống con của ngành viễn thông sẽ gọi phương thức này khi ứng dụng của bạn gọi phương thức
addNewIncomingCall(PhoneAccountHandle, Bundle)
để thông báo cho hệ thống về cuộc gọi đến mới trong ứng dụng. Ứng dụng sẽ trả về một phiên bản mới của quá trình triển khaiConnection
(để biết thêm thông tin, hãy xem phần Triển khai kết nối) để biểu thị cuộc gọi đến mới. Bạn có thể tuỳ chỉnh thêm kết nối đến bằng cách thực hiện các thao tác sau:- Ứng dụng của bạn nên gọi phương thức
setConnectionProperties(int)
với hằng sốPROPERTY_SELF_MANAGED
làm đối số để cho biết rằng kết nối bắt nguồn từ một ứng dụng gọi. - Nếu ứng dụng của bạn hỗ trợ giữ lệnh gọi, hãy gọi phương thức
setConnectionCapabilities(int)
và đặt đối số thành giá trị mặt nạ bit của các hằng sốCAPABILITY_HOLD
vàCAPABILITY_SUPPORT_HOLD
. - Để đặt tên của phương thức gọi, hãy sử dụng phương thức
setCallerDisplayName(String, int)
truyền hằng sốPRESENTATION_ALLOWED
làm tham sốint
để cho biết rằng tên của phương thức gọi sẽ được hiển thị. - Để chỉ định số điện thoại hoặc địa chỉ của cuộc gọi đến, hãy sử dụng phương thức
setAddress(Uri, int)
của đối tượngConnection
. - Để đảm bảo lệnh gọi đi có trạng thái video thích hợp, hãy gọi phương thức
setVideoState(int)
của đối tượngConnection
và gửi giá trị được phương thứcgetVideoState()
của đối tượngConnectionRequest
trả về.
- Ứng dụng của bạn nên gọi phương thức
onCreateIncomingConnectionFailed(PhoneAccountHandle, ConnectionRequest)
Hệ thống con của viễn thông gọi phương thức này khi ứng dụng của bạn gọi phương thức
addNewIncomingCall(PhoneAccountHandle, Bundle)
để thông báo cho Telecom về cuộc gọi đến mới, nhưng cuộc gọi đến không được cho phép (để biết thêm thông tin, hãy xem phần các giới hạn đối với việc gọi). Ứng dụng của bạn sẽ tự động từ chối cuộc gọi đến, tuỳ ý đăng thông báo để thông báo cho người dùng về cuộc gọi nhỡ.
Triển khai kết nối
Ứng dụng nên tạo một lớp con của Connection
để đại diện cho các lệnh gọi trong ứng dụng. Bạn nên ghi đè các phương thức sau trong quá trình triển khai:
onShowIncomingCallUi()
Hệ thống viễn thông phụ gọi phương thức này khi bạn thêm cuộc gọi đến mới và ứng dụng sẽ hiển thị giao diện người dùng cho cuộc gọi đến.
onCallAudioStateChanged(CallAudioState)
Hệ thống viễn thông phụ gọi phương thức này để thông báo cho ứng dụng của bạn rằng tuyến hoặc chế độ âm thanh hiện tại đã thay đổi. Lệnh này được gọi để phản hồi khi ứng dụng của bạn thay đổi chế độ âm thanh bằng phương thức
setAudioRoute(int)
. Phương thức này cũng có thể được gọi nếu hệ thống thay đổi tuyến âm thanh (ví dụ: khi tai nghe Bluetooth ngắt kết nối).onHold()
Hệ thống viễn thông phụ gọi phương thức này khi muốn giữ cuộc gọi. Để phản hồi yêu cầu này, ứng dụng của bạn cần giữ lệnh gọi và sau đó gọi phương thức
setOnHold()
để thông báo cho hệ thống rằng lệnh gọi đang được giữ. Hệ thống viễn thông con có thể gọi phương thức này khi một dịch vụ trong cuộc gọi (chẳng hạn như Android Auto) cho biết cuộc gọi của bạn muốn chuyển tiếp yêu cầu của người dùng để chuyển cuộc gọi sang trạng thái chờ. Hệ thống viễn thông phụ cũng gọi phương thức này nếu người dùng thực hiện cuộc gọi đang hoạt động trong một ứng dụng khác. Để biết thêm thông tin về dịch vụ trong cuộc gọi, hãy xemInCallService
.onUnhold()
Hệ thống viễn thông phụ sẽ gọi phương thức này khi muốn tiếp tục một cuộc gọi đã bị tạm ngưng. Sau khi tiếp tục cuộc gọi, ứng dụng của bạn sẽ gọi phương thức
setActive()
để thông báo cho hệ thống rằng cuộc gọi không còn ở trạng thái chờ nữa. Hệ thống viễn thông phụ có thể gọi phương thức này khi một dịch vụ trong cuộc gọi (chẳng hạn như Android Auto) đang cho thấy cuộc gọi của bạn muốn chuyển tiếp yêu cầu tiếp tục cuộc gọi. Để biết thêm thông tin về dịch vụ trong cuộc gọi, hãy xemInCallService
.onAnswer()
Hệ thống viễn thông phụ gọi phương thức này để thông báo cho ứng dụng rằng cần trả lời cuộc gọi đến. Sau khi trả lời lệnh gọi, ứng dụng của bạn sẽ gọi phương thức
setActive()
để thông báo cho hệ thống rằng lệnh gọi đã được trả lời. Hệ thống viễn thông phụ có thể gọi phương thức này khi ứng dụng của bạn thêm cuộc gọi đến mới và có một cuộc gọi đang diễn ra trong một ứng dụng khác mà không thể đặt ở chế độ chờ. Hệ thống con của ngành viễn thông sẽ thay mặt ứng dụng hiển thị giao diện người dùng của cuộc gọi đến trong những trường hợp này. Khung này cung cấp một phương thức nạp chồng hỗ trợ chỉ định trạng thái video để trả lời lệnh gọi. Để biết thêm thông tin, hãy xemonAnswer(int)
.onReject()
Hệ thống con của viễn thông sẽ gọi phương thức này khi muốn từ chối một cuộc gọi đến. Sau khi từ chối lệnh gọi, ứng dụng của bạn sẽ gọi
setDisconnected(DisconnectCause)
và chỉ địnhREJECTED
làm tham số. Sau đó, ứng dụng nên gọi phương thứcdestroy()
để thông báo cho hệ thống biết rằng ứng dụng đã xử lý lệnh gọi. Hệ thống viễn thông phụ gọi phương thức này khi người dùng từ chối cuộc gọi đến từ ứng dụng của bạn.onDisconnect()
Hệ thống viễn thông phụ gọi phương thức này khi muốn ngắt kết nối một cuộc gọi. Sau khi lệnh gọi kết thúc, ứng dụng phải gọi phương thức
setDisconnected(DisconnectCause)
và chỉ địnhLOCAL
làm tham số để cho biết rằng yêu cầu của người dùng khiến cuộc gọi bị ngắt kết nối. Sau đó, ứng dụng nên gọi phương thứcdestroy()
để thông báo cho hệ thống viễn thông phụ rằng ứng dụng đã xử lý cuộc gọi. Hệ thống có thể gọi phương thức này khi người dùng ngắt kết nối một cuộc gọi thông qua một dịch vụ trong lệnh gọi khác, chẳng hạn như Android Auto. Hệ thống cũng gọi phương thức này khi bạn phải ngắt kết nối cuộc gọi để cho phép thực hiện cuộc gọi khác, chẳng hạn như nếu người dùng muốn thực hiện cuộc gọi khẩn cấp. Để biết thêm thông tin về dịch vụ trong cuộc gọi, hãy xemInCallService
.
Xử lý các tình huống gọi phổ biến
Để sử dụng API ConnectionService
trong quy trình gọi, bạn cần tương tác với các lớp khác trong gói android.telecom
. Các phần sau đây mô tả các trường hợp gọi phổ biến và cách ứng dụng của bạn nên dùng API để xử lý các trường hợp đó.
Trả lời cuộc gọi đến
Luồng xử lý các cuộc gọi đến sẽ thay đổi dù có lệnh gọi trong ứng dụng khác hay không. Lý do cho sự khác biệt về các luồng là khung viễn thông phải thiết lập một số quy tắc ràng buộc khi có các lệnh gọi đang hoạt động trong các ứng dụng khác để đảm bảo môi trường ổn định cho tất cả ứng dụng gọi trên thiết bị. Để biết thêm thông tin, hãy xem bài viết Các điều kiện ràng buộc đối với lệnh gọi.
Không có cuộc gọi nào đang diễn ra trong các ứng dụng khác
Để trả lời cuộc gọi đến khi không có cuộc gọi nào đang diễn ra trong các ứng dụng khác, hãy làm theo các bước sau:
- Ứng dụng của bạn nhận cuộc gọi đến mới bằng các cơ chế thông thường của ứng dụng.
- Sử dụng phương thức
addNewIncomingCall(PhoneAccountHandle, Bundle)
để thông báo cho hệ thống viễn thông phụ về cuộc gọi đến mới. - Hệ thống viễn thông phụ liên kết với phương thức triển khai
ConnectionService
của ứng dụng và yêu cầu một thực thể mới của lớpConnection
đại diện cho lệnh gọi đến mới bằng phương thứconCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)
. - Hệ thống viễn thông phụ thông báo cho ứng dụng của bạn rằng ứng dụng cần hiển thị giao diện người dùng có cuộc gọi đến bằng phương thức
onShowIncomingCallUi()
. - Ứng dụng của bạn hiển thị giao diện người dùng đến bằng cách sử dụng một thông báo có ý định toàn màn hình được liên kết. Để biết thêm thông tin, hãy xem
onShowIncomingCallUi()
. - Gọi phương thức
setActive()
nếu người dùng chấp nhận lệnh gọi đến hoặcsetDisconnected(DisconnectCause)
chỉ địnhREJECTED
làm tham số, theo sau là lệnh gọi đến phương thứcdestroy()
nếu người dùng từ chối lệnh gọi đến.
Các cuộc gọi đang diễn ra trong các ứng dụng khác mà không thể đặt ở chế độ chờ
Để trả lời cuộc gọi đến khi có cuộc gọi đang diễn ra trong các ứng dụng khác không thể tạm ngưng, hãy làm theo các bước sau:
- Ứng dụng của bạn nhận cuộc gọi đến mới bằng các cơ chế thông thường của ứng dụng.
- Sử dụng phương thức
addNewIncomingCall(PhoneAccountHandle, Bundle)
để thông báo cho hệ thống viễn thông phụ về cuộc gọi đến mới. - Hệ thống viễn thông phụ liên kết với phương thức triển khai
ConnectionService
của ứng dụng và yêu cầu một thực thể mới của đối tượngConnection
đại diện cho lệnh gọi đến mới bằng phương thứconCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)
. - Hệ thống viễn thông phụ hiển thị giao diện người dùng của cuộc gọi đến cho cuộc gọi đến.
- Nếu người dùng chấp nhận cuộc gọi, hệ thống viễn thông phụ sẽ gọi phương thức
onAnswer()
. Bạn nên gọi phương thứcsetActive()
để cho hệ thống viễn thông phụ biết rằng cuộc gọi hiện đã được kết nối. - Nếu người dùng từ chối cuộc gọi, hệ thống viễn thông phụ sẽ gọi phương thức
onReject()
. Bạn nên gọi phương thứcsetDisconnected(DisconnectCause)
chỉ địnhREJECTED
làm tham số, theo sau là một lệnh gọi đến phương thứcdestroy()
.
Thực hiện cuộc gọi đi
Quy trình thực hiện cuộc gọi đi liên quan đến việc xử lý khả năng không thể thực hiện cuộc gọi do những hạn chế do khung viễn thông áp đặt. Để biết thêm thông tin, hãy xem bài viết Các điều kiện ràng buộc đối với lệnh gọi.
Để thực hiện cuộc gọi đi, hãy làm theo các bước sau:
- Người dùng bắt đầu một cuộc gọi đi trong ứng dụng của bạn.
- Sử dụng phương thức
placeCall(Uri, Bundle)
để thông báo cho hệ thống viễn thông phụ về cuộc gọi đi mới. Hãy xem xét những điểm sau đây đối với các tham số của phương thức:- Tham số
Uri
biểu thị địa chỉ nơi thực hiện lệnh gọi. Đối với các số điện thoại thông thường, hãy sử dụng lược đồ URItel:
. - Tham số
Bundle
cho phép bạn cung cấp thông tin về ứng dụng gọi bằng cách thêm đối tượngPhoneAccountHandle
của ứng dụng vào phần bổ sungEXTRA_PHONE_ACCOUNT_HANDLE
. Ứng dụng của bạn phải cung cấp đối tượngPhoneAccountHandle
cho mọi lệnh gọi đi. - Tham số
Bundle
cũng cho phép bạn chỉ định xem cuộc gọi đi có chứa video hay không bằng cách chỉ định giá trịSTATE_BIDIRECTIONAL
trong phần bổ sungEXTRA_START_CALL_WITH_VIDEO_STATE
. Hãy xem xét điều đó theo mặc định, hệ thống viễn thông phụ sẽ định tuyến cuộc gọi video đến loa ngoài.
- Tham số
- Hệ thống viễn thông phụ liên kết với cách triển khai
ConnectionService
của ứng dụng. - Nếu ứng dụng của bạn không thể thực hiện cuộc gọi đi, thì hệ thống viễn thông phụ sẽ gọi phương thức
onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest)
để thông báo cho ứng dụng rằng không thể thực hiện cuộc gọi tại thời điểm hiện tại. Ứng dụng của bạn phải thông báo cho người dùng rằng không thể thực hiện lệnh gọi. - Nếu ứng dụng của bạn có thể thực hiện cuộc gọi đi, thì hệ thống viễn thông phụ sẽ gọi phương thức
onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)
. Ứng dụng của bạn sẽ trả về một thực thể của lớpConnection
để đại diện cho cuộc gọi đi mới. Để biết thêm thông tin về các thuộc tính mà bạn nên thiết lập trong kết nối, hãy xem bài viết Triển khai dịch vụ kết nối. - Khi cuộc gọi đi đã được kết nối, hãy gọi phương thức
setActive()
để thông báo cho hệ thống viễn thông phụ rằng cuộc gọi đang hoạt động.
Kết thúc cuộc gọi
Để kết thúc cuộc gọi, hãy làm theo các bước sau:
- Gọi
setDisconnected(DisconnectCause)
gửiLOCAL
dưới dạng tham số nếu người dùng đã kết thúc lệnh gọi hoặc gửiREMOTE
dưới dạng tham số nếu bên kia đã chấm dứt lệnh gọi. - Gọi phương thức
destroy()
.
Các quy tắc ràng buộc đối với lệnh gọi
Để đảm bảo người dùng có trải nghiệm gọi đơn giản và nhất quán, khung viễn thông sẽ thực thi một số quy tắc ràng buộc để quản lý các lệnh gọi trên thiết bị. Ví dụ: hãy xem xét việc người dùng đã cài đặt 2 ứng dụng gọi điện để triển khai API ConnectionService
tự quản lý, FooTalk và BarTalk. Trong trường hợp này, những hạn chế sau sẽ được áp dụng:
Trên các thiết bị chạy ở API cấp 27 trở xuống, chỉ một ứng dụng có thể duy trì lệnh gọi đang diễn ra tại một thời điểm bất kỳ. Quy tắc ràng buộc này có nghĩa là trong khi người dùng có một cuộc gọi đang diễn ra bằng ứng dụng FooTalk, ứng dụng BarTalk không thể bắt đầu hoặc nhận cuộc gọi mới.
Trên các thiết bị chạy trên API cấp 28 trở lên, nếu cả FooTalk và BarTalk đều khai báo quyền
CAPABILITY_SUPPORT_HOLD
và quyềnCAPABILITY_HOLD
, thì người dùng có thể duy trì nhiều lệnh gọi đang diễn ra bằng cách chuyển đổi giữa các ứng dụng để bắt đầu hoặc trả lời một lệnh gọi khác.Nếu người dùng tham gia vào các cuộc gọi được quản lý thông thường (ví dụ: dùng ứng dụng Điện thoại hoặc Trình quay số tích hợp sẵn), thì người dùng không thể tham gia các cuộc gọi bắt nguồn từ các ứng dụng gọi. Điều này có nghĩa là nếu người dùng đang thực hiện cuộc gọi thông thường bằng nhà mạng di động, thì họ cũng không thể đồng thời tham gia cuộc gọi FooTalk hoặc BarTalk.
Hệ thống viễn thông phụ sẽ ngắt kết nối các cuộc gọi của ứng dụng nếu người dùng gọi điện thoại khẩn cấp.
Ứng dụng của bạn không thể nhận hoặc thực hiện cuộc gọi trong khi người dùng đang thực hiện cuộc gọi khẩn cấp.
Nếu có một cuộc gọi đang diễn ra trong ứng dụng gọi khác khi ứng dụng của bạn nhận được một cuộc gọi đến, thì việc trả lời cuộc gọi đến đó sẽ kết thúc mọi cuộc gọi đang diễn ra trong ứng dụng đó. Ứng dụng của bạn không nên hiển thị giao diện người dùng có cuộc gọi đến thông thường. Khung viễn thông hiển thị giao diện người dùng của cuộc gọi đến và thông báo cho người dùng rằng việc trả lời cuộc gọi mới sẽ kết thúc(các) cuộc gọi đang diễn ra. Điều này nghĩa là nếu người dùng đang tham gia cuộc gọi FooTalk và ứng dụng BarTalk nhận được cuộc gọi đến, khung viễn thông sẽ thông báo cho người dùng rằng họ có cuộc gọi BarTalk mới đến và việc trả lời cuộc gọi BarTalk sẽ kết thúc cuộc gọi FooTalk của họ.