Lật ứng dụng dành cho Android

Sau khi triển khai OAuth 2.0, bạn có thể tuỳ ý định cấu hình App Flip, which allows your Android users to more quickly link their accounts in your authentication system to their Google accounts. The following sections describe how to design and implement App Flip for your smart home Action. dựa trên OAuth

Hướng dẫn thiết kế

Phần này mô tả các yêu cầu và đề xuất thiết kế cho màn hình đồng ý liên kết tài khoản Ứng dụng. Sau khi Google gọi ứng dụng của bạn, ứng dụng đó sẽ hiển thị màn hình xin phép người dùng.

Yêu cầu

1. Bạn phải thông báo rằng tài khoản của người dùng đang được liên kết với Google, không phải với một sản phẩm cụ thể của Google, chẳng hạn như Google Home hoặc Trợ lý Google.

Đề xuất

Bạn nên làm như sau:

1. Hiển thị Chính sách quyền riêng tư của Google. Bao gồm một đường liên kết đến Chính sách quyền riêng tư của Google trên màn hình đồng ý.

2. Dữ liệu cần chia sẻ. Sử dụng ngôn ngữ rõ ràng và súc tích để cho người dùng biết dữ liệu mà họ yêu cầu và vì sao.

3. Lời kêu gọi hành động rõ ràng. Nêu rõ lời kêu gọi hành động trên màn hình đồng ý, chẳng hạn như "Đồng ý và liên kết". Điều này là do người dùng cần hiểu rõ dữ liệu nào họ cần chia sẻ với Google để liên kết tài khoản.

4. Khả năng huỷ. Cung cấp cho người dùng cách quay lại hoặc huỷ nếu họ chọn không liên kết.

5. Khả năng huỷ liên kết. Cung cấp cơ chế để người dùng huỷ liên kết, chẳng hạn như URL đến chế độ cài đặt tài khoản của họ trên nền tảng của bạn. Ngoài ra, bạn có thể cung cấp đường liên kết đến Tài khoản Google để người dùng có thể quản lý tài khoản được liên kết.

6. Khả năng thay đổi tài khoản người dùng. Đề xuất phương thức để người dùng chuyển đổi(các) tài khoản của họ. Điều này đặc biệt có lợi nếu người dùng có xu hướng có nhiều tài khoản.

   • Nếu người dùng phải đóng màn hình đồng ý để chuyển đổi tài khoản, hãy gửi lỗi có thể khôi phục cho Google để người dùng có thể đăng nhập vào tài khoản mong muốn bằng tính năng Liên kết OAuth và quy trình ngầm ẩn.

7. Bao gồm biểu trưng của bạn. Hiển thị biểu tượng công ty của bạn trên màn hình đồng ý. Sử dụng nguyên tắc định kiểu để đặt biểu trưng của bạn. Nếu bạn cũng muốn hiển thị biểu tượng của Google, hãy xem Biểu trưng và nhãn hiệu.

Thiết lập ở chế độ Lật ứng dụng dựa trên OAuth

Các phần sau mô tả các điều kiện tiên quyết đối với Chiến dịch quảng cáo ứng dụng dựa trên OAuth và cách định cấu hình dự án Lật ứng dụng trong Bảng điều khiển Actions.

Tạo Hành động tại nhà thông minh và thiết lập máy chủ OAuth 2.0

Trước khi có thể định cấu hình Lật ứng dụng, bạn cần thực hiện những việc sau:

• Thiết lập máy chủ OAuth 2.0. Để biết thêm thông tin về cách thiết lập máy chủ OAuth, hãy xem phần Triển khai máy chủ OAuth 2.0.
• Tạo hành động. Để tạo một Hành động, hãy làm theo hướng dẫn trong bài viết Tạo dự án Hành động.

Định cấu hình Lật ứng dụng trong bảng điều khiển Actions

Phần sau đây mô tả cách định cấu hình Lật ứng dụng trong Bảng điều khiển Actions.

1. Điền vào tất cả các trường trong phần Thông tin ứng dụng OAuth. (Nếu không hỗ trợ Lật ứng dụng, OAuth thông thường sẽ được dùng làm dự phòng.)
2. Trong phần Sử dụng ứng dụng để liên kết tài khoản (không bắt buộc), hãy chọn Bật cho Android.
3. Điền vào các trường sau:
• Mã ứng dụng. Application ID (Mã ứng dụng) là mã nhận dạng duy nhất mà bạn đặt cho ứng dụng.
• Chữ ký ứng dụng. Các ứng dụng Android phải được "ký" bằng chứng chỉ khóa công khai trước khi có thể được cài đặt. Để biết thông tin về cách lấy chữ ký ứng dụng của bạn, hãy xem phần Xác thực ứng dụng.
• Ý định uỷ quyền. Trong trường này, hãy nhập một chuỗi chỉ định thao tác theo ý định.
4. Nếu bạn muốn định cấu hình ứng dụng của mình, hãy thêm phạm vi và nhấp vào Thêm phạm vi trong Định cấu hình ứng dụng của bạn (không bắt buộc).
5. Nhấp vào Lưu.

Triển khai tính năng Lật ứng dụng trong các ứng dụng Android

Để triển khai tính năng Lật ứng dụng, bạn cần sửa đổi mã uỷ quyền người dùng trong ứng dụng của mình để chấp nhận một đường liên kết sâu từ Google.

Tính năng liên kết ứng dụng trên cơ sở OAuth (sử dụng tính năng Lật ứng dụng) sẽ chèn ứng dụng Android của bạn vào quy trình Liên kết tài khoản Google. Quy trình liên kết tài khoản truyền thống yêu cầu người dùng nhập thông tin xác thực của họ vào trình duyệt. Việc sử dụng tính năng Lật ứng dụng sẽ hoãn việc đăng nhập của người dùng vào ứng dụng Android, cho phép bạn tận dụng các lệnh uỷ quyền hiện có. Nếu người dùng đã đăng nhập vào ứng dụng, thì họ không cần nhập lại thông tin đăng nhập để liên kết tài khoản. Cần thay đổi mã ở mức tối thiểu để triển khai tính năng Lật ứng dụng trên ứng dụng Android.

Trong tài liệu này, bạn sẽ tìm hiểu cách sửa đổi ứng dụng Android để hỗ trợ tính năng Lật ứng dụng.

Thử đọc mẫu

Ứng dụng mẫu liên kết Lật ứng dụng minh họa quá trình tích hợp liên kết tài khoản tương thích với ứng dụng Lật trên Android. Bạn có thể sử dụng ứng dụng này để xác minh cách phản hồi ý định đến của Ứng dụng đang đến từ các ứng dụng của Google dành cho thiết bị di động.

Ứng dụng mẫu được định cấu hình trước để tích hợp với Công cụ kiểm thử lật của ứng dụng dành cho Android. Bạn có thể sử dụng công cụ này để xác minh quá trình tích hợp của ứng dụng Android với tính năng lật ứng dụng trước khi định cấu hình liên kết tài khoản với Google. Ứng dụng này mô phỏng ý định của ứng dụng di động Google khi bật tính năng Lật ứng dụng.

Cách hoạt động

Bạn cần thực hiện các bước sau để tiến hành tích hợp Ứng dụng dạng lật:

1. Ứng dụng Google sẽ kiểm tra xem ứng dụng của bạn có được cài đặt trên thiết bị bằng tên gói của ứng dụng đó hay không.
2. Ứng dụng Google sử dụng quy trình kiểm tra chữ ký gói để xác thực rằng ứng dụng đã cài đặt là ứng dụng chính xác.
3. Ứng dụng Google tạo ý định bắt đầu một hoạt động được chỉ định trong ứng dụng. Ý định này bao gồm dữ liệu bổ sung cần thiết để liên kết. Lớp này cũng kiểm tra xem ứng dụng của bạn có hỗ trợ tính năng Lật ứng dụng hay không bằng cách giải quyết ý định này thông qua khung Android.
4. Ứng dụng sẽ xác thực rằng yêu cầu này là của ứng dụng Google. Để làm như vậy, ứng dụng sẽ kiểm tra chữ ký gói và mã ứng dụng khách đã cung cấp.
5. Ứng dụng của bạn yêu cầu mã uỷ quyền từ máy chủ OAuth 2.0. Khi kết thúc quy trình này, ứng dụng sẽ trả về mã ủy quyền hoặc lỗi đối với ứng dụng Google.
6. Ứng dụng Google truy xuất kết quả và tiếp tục liên kết tài khoản. Nếu bạn cung cấp mã uỷ quyền, quá trình trao đổi mã thông báo sẽ diễn ra từ máy chủ đến máy chủ, tương tự như cách họ thực hiện trong quy trình liên kết OAuth dựa trên trình duyệt.

Sửa đổi ứng dụng Android của bạn để hỗ trợ tính năng Lật ứng dụng

Để hỗ trợ ứng dụng Lật ứng dụng, hãy thực hiện các thay đổi mã sau đây đối với ứng dụng Android của bạn:

1. Thêm <intent-filter> vào tệp AndroidManifest.xml bằng một chuỗi hành động khớp với giá trị bạn đã nhập vào trường Ý định lật ứng dụng.

   <activity android:name="AuthActivity">
     <!-- Handle the app flip intent -->
     <intent-filter>
       <action android:name="INTENT_ACTION_FROM_CONSOLE"/>
       <category android:name="android.intent.category.DEFAULT"/>
     </intent-filter>
   </activity>
   

2. Xác thực chữ ký của ứng dụng gọi.

   private fun verifyFingerprint(
           expectedPackage: String,
           expectedFingerprint: String,
           algorithm: String
   ): Boolean {
   
       callingActivity?.packageName?.let {
           if (expectedPackage == it) {
               val packageInfo =
                   packageManager.getPackageInfo(it, PackageManager.GET_SIGNATURES)
               val signatures = packageInfo.signatures
               val input = ByteArrayInputStream(signatures[0].toByteArray())
   
               val certificateFactory = CertificateFactory.getInstance("X509")
               val certificate =
                   certificateFactory.generateCertificate(input) as X509Certificate
               val md = MessageDigest.getInstance(algorithm)
               val publicKey = md.digest(certificate.encoded)
               val fingerprint = publicKey.joinToString(":") { "%02X".format(it) }
   
               return (expectedFingerprint == fingerprint)
           }
       }
       return false
   }
   

3. Trích xuất mã ứng dụng khách từ tham số của ý định và xác minh rằng mã nhận dạng ứng dụng khách khớp với giá trị dự kiến.

   private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
   private const val EXPECTED_PACKAGE = "<google-app-package-name>"
   private const val EXPECTED_FINGERPRINT = "<google-app-signature>"
   private const val ALGORITHM = "SHA-256"
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINT, ALGORITHM)) {
   
           // ...authorize the user...
       }
   }
   

4. Sau khi uỷ quyền thành công, hãy trả lại mã uỷ quyền kết quả cho Google.

   // Successful result
   val data = Intent().apply {
       putExtra("AUTHORIZATION_CODE", authCode)
   }
   setResult(Activity.RESULT_OK, data)
   finish()
   

5. Nếu xảy ra lỗi, hãy trả về kết quả lỗi.

   // Error result
   val error = Intent().apply {
       putExtra("ERROR_TYPE", 1)
       putExtra("ERROR_CODE", 1)
       putExtra("ERROR_DESCRIPTION", "Invalid Request")
   }
   setResult(-2, error)
   finish()
   

Nội dung của ý định khởi chạy

Ý định trên Android để khởi chạy ứng dụng của bạn bao gồm các trường sau:

• CLIENT_ID (String): Google client_id đã đăng ký trong ứng dụng của bạn.
• SCOPE (String[]): Danh sách các phạm vi được yêu cầu.
• REDIRECT_URI (String): URL chuyển hướng.

Nội dung dữ liệu phản hồi

Dữ liệu được trả về ứng dụng Google được thiết lập trong ứng dụng của bạn bằng cách gọi setResult(). Những dữ liệu này bao gồm:

• AUTHORIZATION_CODE (String): Giá trị của mã ủy quyền.
• resultCode (int): Cho biết quy trình thành công hay không thành công và nhận một trong các giá trị sau:
  • Activity.RESULT_OK: Cho biết thành công; mã ủy quyền được trả về.
  • Activity.RESULT_CANCELLED: Tín hiệu cho biết người dùng đã huỷ quá trình. Trong trường hợp này, ứng dụng Google sẽ cố gắng liên kết tài khoản bằng URL uỷ quyền của bạn.
  • -2: Cho biết đã xảy ra lỗi. Các loại lỗi khác nhau được mô tả dưới đây.
• ERROR_TYPE (int): Loại lỗi, nhận một trong các giá trị sau:
  • 1: Lỗi có thể khôi phục: Ứng dụng Google sẽ tìm cách liên kết tài khoản bằng URL ủy quyền.
  • 2: Lỗi không thể khôi phục: Ứng dụng Google hủy liên kết tài khoản.
  • 3: Tham số yêu cầu không hợp lệ hoặc bị thiếu.
• ERROR_CODE (int): Một số nguyên thể hiện bản chất của lỗi. Để xem ý nghĩa của từng mã lỗi, hãy tham khảo bảng mã lỗi.

• ERROR_DESCRIPTION (String, không bắt buộc): Thông báo trạng thái có thể đọc được, mô tả lỗi.

Một giá trị cho AUTHORIZATION_CODE được dự kiến khi resultCode == Activity.RESULT_OK. Trong tất cả các trường hợp khác, giá trị của AUTHORIZATION_CODE cần để trống. Nếu resultCode == -2, thì giá trị ERROR_TYPE dự kiến sẽ được điền sẵn.

Bảng mã lỗi

Bảng dưới đây cho thấy các mã lỗi khác nhau và liệu mỗi lỗi có thể khôi phục hay không thể khôi phục:

Mã lỗi	Ý nghĩa	Có thể khôi phục	Không thể khôi phục
1	INVALID_REQUEST	✔
2	NO_INTERNET_CONNECTION		✔
3	OFFLINE_MODE_ACTIVE	✔
4	CONNECTION_TIMEOUT	✔
5	INTERNAL_ERROR	✔
6	AUTHENTICATION_SERVICE_UNAVAILABLE		✔
8	CLIENT_VERIFICATION_FAILED	✔
9	INVALID_CLIENT	✔
10	INVALID_APP_ID	✔
11	INVALID_REQUEST	✔
12	AUTHENTICATION_SERVICE_UNKNOWN_ERROR		✔
13	AUTHENTICATION_DENIED_BY_USER		✔
14	CANCELLED_BY_USER		✔
15	FAILURE_OTHER		✔
16	USER_AUTHENTICATION_FAILED	✔

Đối với tất cả các mã lỗi, bạn phải trả về kết quả lỗi qua setResult để đảm bảo dự phòng thích hợp được kích hoạt.

Thử nghiệm Lật ứng dụng trên thiết bị

Bây giờ, sau khi đã tạo Hành động và định cấu hình Lật ứng dụng trên bảng điều khiển và trong ứng dụng, bạn có thể thử nghiệm tính năng Lật ứng dụng trên thiết bị di động. Bạn có thể dùng ứng dụng Trợ lý Google hoặc ứng dụng Google Home để kiểm tra tính năng Lật ứng dụng.

Để kiểm tra tính năng Lật ứng dụng bằng ứng dụng Trợ lý, hãy làm theo các bước sau:

1. Chuyển đến Bảng điều khiển Actions rồi chọn dự án của bạn.
2. Nhấp vào Kiểm thử trong thanh điều hướng trên cùng.
3. Kích hoạt quy trình liên kết tài khoản trong ứng dụng Trợ lý:
1. Mở ứng dụng Trợ lý Google.
2. Nhấp vào Cài đặt.
3. Trên thẻ Trợ lý, hãy nhấp vào Điều khiển nhà.
4. Nhấp vào Add(+).
5. Chọn Hành động của bạn trong danh sách nhà cung cấp. Giá trị này sẽ có tiền tố là “[test]” trong danh sách. Khi bạn chọn Hành động [kiểm thử] từ danh sách, thao tác này sẽ mở ứng dụng của bạn.
6. Xác minh rằng ứng dụng của bạn đã được khởi chạy và bắt đầu kiểm thử quy trình uỷ quyền.

Để kiểm tra tính năng Lật ứng dụng trên ứng dụng Home, hãy làm theo các bước sau:

1. Chuyển đến Bảng điều khiển Actions rồi chọn dự án của bạn.
2. Nhấp vào Kiểm thử trong thanh điều hướng trên cùng.
3. Kích hoạt quy trình liên kết tài khoản từ ứng dụng Home:
1. Mở ứng dụng Google Home.
2. Nhấp vào nút +.
3. Nhấp vào Thiết lập thiết bị.
4. Nhấp vào Bạn đã thiết lập thiết bị?
5. Chọn Hành động dành cho nhà thông minh trong danh sách nhà cung cấp. Giá trị này sẽ có tiền tố là “[test]” trong danh sách. Khi bạn chọn Hành động [kiểm thử] từ danh sách, thao tác này sẽ mở ứng dụng của bạn.
6. Xác minh rằng ứng dụng của bạn đã được khởi chạy và bắt đầu kiểm thử quy trình uỷ quyền.