Tạo ứng dụng gọi điện

Ứ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ác ứng dụng gọi điện dùng giao diện người dùng riêng để gọi điện, thay vì dùng giao diện người dùng giao diện mặc định của ứng dụng Điện thoại, như trong ảnh chụp màn hình sau đây.


Ví dụ về ứng dụng gọi Ví dụ về một ứng dụng gọi sử dụng giao diện người dùng riêng

Khung Android bao gồm gói android.telecom, chứa các lớp giúp bạn tạo một ứng dụng gọi điện theo khung. Việc xây dựng ứng dụng của bạn 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 khung này 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 sử dụng MANAGE_OWN_CALLS như được minh hoạ trong ví dụ sau đây:

<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 Quyền.

Bạn phải khai báo một dịch vụ chỉ định lớp sẽ triển khai ConnectionService trong ứng dụng của bạn. Viễn thông hệ thống con yêu cầu dịch vụ khai báo quyền BIND_TELECOM_CONNECTION_SERVICE có thể liên kết với nó. Ví dụ sau đây trình bày cách khai báo dịch vụ trong tệp kê khai ứng dụng của bạn:

<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ề việc khai báo thành phần ứng dụng (bao gồm cả dịch vụ), hãy xem 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 con viễn thông có thể liên kết. Quá trình triển khai ConnectionService của bạn sẽ ghi đè các phương thức sau:

onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)

Hệ thống con viễn thông gọi phương thức này để phản hồi ứ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ớp Connection (để biết thêm thông tin, hãy xem Triển khai mối kết nối) để biểu thị cuộc gọi đ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 hành động sau:

onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest)

Hệ thống con 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 placeCall(Uri, Bundle) và cuộc gọi đi thì không thể được đặt. Để ứng phó với tình huống này, ứng dụng của bạn phải 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) cho biết 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 có 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 mà không thể hãy giữ máy trước khi thực hiện cuộc gọi.

onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)

Hệ thống con 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 hệ thống về cuộc gọi đến mới trong ứng dụng của bạn. Ứng dụng của bạn trả về một thực thể mới của việc triển khai Connection (cho để biết thêm thông tin, hãy xem bài viết Triển khai mối liên kết) để đại diện cho cuộc gọi đến mới. Bạn có thể tuỳ chỉnh thêm kết nối bằng cách thực hiện các thao tác sau:

onCreateIncomingConnectionFailed(PhoneAccountHandle, ConnectionRequest)

Hệ thống con 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ề một cuộc gọi đến mới, nhưng không được phép cho cuộc gọi đến (để hãy xem các giới hạn gọi điện). Ứng dụng của bạn sẽ từ chối cuộc gọi đến, tùy ý đăng thông báo để thông báo người dùng của cuộc gọi nhỡ.

Triển khai mối kết nối

Ứng dụng phải tạo một lớp con của Connection để đại diện cho các cuộc gọi trong ứng dụng của bạn. Bạn nên ghi đè các phương thức sau trong cách triển khai của bạn:

onShowIncomingCallUi()

Hệ thống con viễn thông gọi phương thức này khi bạn thêm cuộc gọi đến mới và ứng dụng của bạn phải cho thấy giao diện người dùng có cuộc gọi đến.

onCallAudioStateChanged(CallAudioState)

Hệ thống con viễn thông gọi phương thức này để thông báo cho ứng dụng của bạn rằng âm thanh hiện tại tuyến đường hoặc chế độ đã thay đổi. Lệnh này được gọi để phản hồi việc ứng dụng của bạn thay đổi chế độ phát âm thanh bằng setAudioRoute(int) . Phương thức này cũng có thể được gọi nếu hệ thống thay đổi đường truyền âm thanh (ví dụ: khi tai nghe Bluetooth ngắt kết nối).

onHold()

Hệ thống con viễn thông gọi phương thức này khi muốn tạm dừng một cuộc gọi. Để phản hồi yêu cầu này, ứng dụng của bạn sẽ giữ cuộc gọi rồi gọi Phương thức setOnHold() để thông báo cho hệ thống cho biết cuộc gọi đang được giữ. Hệ thống con viễn thông có thể gọi phương thức này khi một dịch vụ đang gọi điện (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 về việc giữ cuộc gọi. Hệ thống con viễn thông này cũng gọi phương thức này nếu người dùng kích hoạt một cuộc gọi trong một ứng dụng khác. Để biết thêm thông tin về các dịch vụ trong cuộc gọi, xem InCallService.

onUnhold()

Hệ thống con viễn thông gọi phương thức này khi nó muốn tiếp tục một cuộc gọi đã bị giữ máy. Sau khi ứng dụng của bạn tiếp tục lệnh gọi, nó sẽ gọi setActive() để thông báo cho hệ thống rằng cuộc gọi không còn bị giữ máy. Viễn thông hệ thống con có thể gọi phương thức này khi một dịch vụ đang gọi điện, 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 một yêu cầu để tiếp tục cuộc gọi đó. Cho để biết thêm thông tin về các dịch vụ trong cuộc gọi, hãy xem InCallService.

onAnswer()

Hệ thống con viễn thông gọi phương thức này để thông báo ứng dụng của bạn để trả lời cuộc gọi đến. Khi ứng dụng của bạn đã trả lời lệnh gọi, nó sẽ gọi setActive() để thông báo cho hệ thống rằng cuộc gọi đã được trả lời. Viễn thông hệ thống con 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à hiện có một cuộc gọi đang diễn ra trong một ứng dụng khác không thể chuyển sang chế độ chờ. Hệ thống con viễn thông hiển thị giao diện người dùng của cuộc gọi đến thay mặt cho ứng dụng của bạn trong các trường hợp này. Khung này cung cấp một phương thức nạp chồng để cung cấp hỗ trợ để chỉ định trạng thái video sẽ trả lời cuộc gọi. Để biết thêm thông tin, hãy xem onAnswer(int).

onReject()

Hệ thống con viễn thông gọi phương thức này khi muốn từ chối lời mời đến . Sau khi từ chối lệnh gọi, ứng dụng của bạn phải gọi setDisconnected(DisconnectCause) và chỉ định REJECTED làm tham số. Ứng dụng của bạn sẽ sau đó gọi phương thức destroy() để thông báo hệ thống mà ứng dụng đã xử lý cuộc gọi. Hệ thống con viễn thông 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 con viễn thông 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 nên gọi phương thức setDisconnected(DisconnectCause) và chỉ định LOCAL làm tham số để cho biết rằng một phương thức 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 của bạn sẽ gọi hàm Phương thức destroy() để thông báo cho hệ thống viễn thông hệ thống con mà ứng dụng đã xử lý lệnh 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 cuộc gọi thông qua một dịch vụ trong cuộc 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 lệnh gọi của bạn phải ngắt kết nối để cho phép thực hiện cuộc gọi khác, ví dụ: 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 xem InCallService.

Xử lý các tình huống gọi điện phổ biến

Sử dụng API ConnectionService trong lệnh gọi luồng bao gồm tương tác với các lớp khác trong android.telecom . Các phần sau đây mô tả các trường hợp gọi điện phổ biến và cách ứng dụng sẽ sử dụng API để xử lý chúng.

Trả lời cuộc gọi đến

Quy trình xử lý cuộc gọi đến sẽ thay đổi dù có cuộc gọi trong các ứng dụng khác hay không hoặc không. Nguyên nhân của sự khác biệt về 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 diễn ra trong các ứng dụng khác để đảm bảo môi trường ổn định cho mọi ứng dụng gọi trên thiết bị. Để biết thêm hãy xem Hạn chế về việc 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 hoạt động trong các ứng dụng khác, hãy làm theo các bước sau:

  1. Ứng dụng của bạn nhận được một cuộc gọi đến mới theo cơ chế thông thường.
  2. Sử dụng phương thức addNewIncomingCall(PhoneAccountHandle, Bundle) để thông báo cho hệ thống viễn thông con về cuộc gọi đến mới.
  3. Hệ thống con viễn thông liên kết với quá trình triển khai ConnectionService của ứng dụng và yêu cầu một thực thể mới của lớp Connection đại diện cho lớp mới sắp đến bằng phương thức onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest).
  4. Hệ thống con viễn thông sẽ thông báo cho ứng dụng của bạn rằng cần hiện cuộc gọi đến giao diện người dùng bằng phương thức onShowIncomingCallUi().
  5. Ứ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 thông báo kèm theo ý định toàn màn hình. Để biết thêm thông tin, hãy xem onShowIncomingCallUi().
  6. Gọi phương thức setActive() nếu người dùng chấp nhận cuộc gọi đến, hoặc setDisconnected(DisconnectCause) chỉ định REJECTED làm tham số, theo sau là gọi phương thức destroy() nếu người dùng từ chối cuộc gọi đến.

Cuộc gọi đang diễn ra trong các ứng dụng khác không thể chuyển sang 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ể trả lời bị tạm dừng, hãy làm theo các bước sau:

  1. Ứng dụng của bạn nhận được một cuộc gọi đến mới theo cơ chế thông thường.
  2. Sử dụng phương thức addNewIncomingCall(PhoneAccountHandle, Bundle) để thông báo cho hệ thống viễn thông con về cuộc gọi đến mới.
  3. Hệ thống con viễn thông liên kết với quá trình 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ượng Connection đại diện cho cuộc gọi đến bằng phương thức onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest).
  4. Hệ thống con viễn thông hiển thị giao diện người dùng cho cuộc gọi đến cho cuộc gọi đến.
  5. Nếu người dùng chấp nhận cuộc gọi, hệ thống con viễn thông sẽ gọi phương thức onAnswer(). Bạn nên gọi phương thức setActive() để cho biết dịch vụ viễn thông đó hệ thống con mà cuộc gọi hiện đã được kết nối.
  6. Nếu người dùng từ chối cuộc gọi, hệ thống con viễn thông sẽ gọi phương thức onReject(). Bạn nên gọi phương thức setDisconnected(DisconnectCause), chỉ định REJECTED làm tham số, theo sau là một gọi phương thức destroy().

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 vì các hạn chế do khung viễn thông áp đặt. Để biết thêm thông tin, hãy xem Các quy tắc ràng buộc đối với việc gọi.

Để thực hiện cuộc gọi đi, hãy làm theo các bước sau:

  1. Người dùng bắt đầu một cuộc gọi đi trong ứng dụng của bạn.
  2. Sử dụng phương thức placeCall(Uri, Bundle) để thông báo hệ thống viễn thông con về cuộc gọi đi mới. Thực hiện các bước sau các cân nhắc cho tham số phương thức:
    • Tham số Uri đại diện cho địa chỉ mà cuộc gọi đang được thực hiện. Đối với các số điện thoại thông thường, hãy dùng URI tel: hệ thống.
    • 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ượng PhoneAccountHandle của ứng dụng vào phần bổ sung EXTRA_PHONE_ACCOUNT_HANDLE. Thông tin ứng dụng phải cung cấp đối tượng PhoneAccountHandle cho mọi cuộc gọi đi.
    • Tham số Bundle cũng cho phép bạn chỉ định xem cuộc gọi đi bao gồm video bằng cách chỉ định giá trị STATE_BIDIRECTIONAL trong EXTRA_START_CALL_WITH_VIDEO_STATE bổ sung. Hãy xem xét rằng theo mặc định, hệ thống con viễn thông định tuyến các cuộc gọi video đến loa ngoài.
  3. Hệ thống con viễn thông liên kết với ConnectionService của ứng dụng trong quá trình triển khai.
  4. Nếu ứng dụng của bạn không thể thực hiện cuộc gọi đi, hệ thống con viễn thông 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 vào 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 cuộc gọi.
  5. Nếu ứng dụng của bạn có thể thực hiện cuộc gọi đi, hệ thống con viễn thông sẽ gọi onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest) . Ứng dụng của bạn sẽ trả về một thực thể của lớp Connection để biểu thị lệnh gọi đi mới. Cho thêm thông tin về thuộc tính mà bạn nên đặt trong kết nối, hãy xem phần Triển khai dịch vụ kết nối.
  6. 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ụ cho biết 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:

  1. Gọi setDisconnected(DisconnectCause) gửi LOCAL dưới dạng tham số nếu người dùng đã kết thúc cuộc gọi hoặc gửi REMOTE dưới dạng tham số nếu bên kia đã kết thúc cuộc gọi.
  2. 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 trải nghiệm gọi điện nhất quán và đơn giản cho người dùng, dịch vụ viễn thông khung thực thi một số quy tắc ràng buộc để quản lý lệnh gọi trên thiết bị. Cho ví dụ: hãy xem xét việc người dùng đã cài đặt hai ứng dụng gọi có triển khai API ConnectionService tự quản lý, FooTalk và BarTalk. Trong trường hợp này, các điều kiện ràng buộc sau sẽ được áp dụng:

  • Trên các thiết bị chạy trên API cấp 27 trở xuống, chỉ một ứng dụng có thể duy trì cuộc gọi đang diễn ra tại bất kỳ thời điểm cụ thể nào. Hạn chế này có nghĩa là mặc dù người dùng có 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 một cuộc gọi mới.

    Trên các thiết bị chạy ở API cấp 28 trở lên, nếu cả FooTalk và BarTalk khai báo CAPABILITY_SUPPORT_HOLD và CAPABILITY_HOLD quyền truy cập, thì người dùng có thể duy trì nhiều cuộc 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 cuộc 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ụ: sử dụng ứng dụng Trình quay số hoặc Điện thoại tích hợp sẵn), người dùng không thể tham gia các cuộc gọi bắt nguồn từ gọi điện. Điều này có nghĩa là nếu người dùng tham gia một cuộc gọi thông thường bằng nhà mạng di động, họ cũng không thể đồng thời tham gia cuộc gọi FooTalk hoặc BarTalk.

  • Hệ thống con viễn thông sẽ ngắt kết nối các cuộc gọi của ứng dụng nếu người dùng quay số cuộc gọ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 một ứng dụng gọi khác khi ứng dụng đó nhận được một cuộc gọi đến, 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 khác. Ứng dụng của bạn không được hiển thị giao diện người dùng cho 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 người dùng trả lời cuộc gọi mới sẽ kết thúc(các) cuộc gọi đang diễn ra của họ. Chiến dịch này có nghĩa là nếu người dùng đang thực hiện 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 đến của BarTalk và việc trả lời cuộc gọi này sẽ chấm dứt Cuộc gọi qua FooTalk.