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 dựa trên OAuth để cho phép người dùng Android liên kết tài khoản của họ trong hệ thống xác thực của bạn với Tài khoản Google của họ nhanh hơn. Các phần sau đây mô tả cách thiết kế và triển khai App Flip cho quá trình tích hợp Cloud-to-cloud trên Android.

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

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

Yêu cầu

  1. Bạn phải có một tuyên bố uỷ quyền của Google, chẳng hạn như "Sau khi liên kết, Google sẽ có quyền điều khiển các thiết bị của bạn".
  2. 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, chứ 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.
  3. Bạn phải nêu rõ lời kêu gọi hành động trên màn hình đồng ý và sử dụng cụm từ "Đồng ý và liên kết" cho hành động liên kết. Điều này là do người dùng cần hiểu rõ những dữ liệu mà họ bắt buộc phải chia sẻ với Google để liên kết tài khoản.
  4. Bạn phải cung cấp cho người dùng một cách để quay lại, từ chối hoặc huỷ nếu họ chọn không liên kết. Sử dụng từ "Huỷ" cho thao tác huỷ.
  5. Bạn phải triển khai quy trình này: Sau khi nhấp vào "Đồng ý và liên kết", bạn phải cho thấy trạng thái liên kết thành công và tự động chuyển hướng người dùng trở lại ứng dụng Google Home. Giờ đây, người dùng sẽ thấy thiết bị được liên kết trên ứng dụng Google Home cùng với thao tác của bạn. Sau khi nhấp vào "Huỷ", bạn nên chuyển hướng người dùng trở lại ứng dụng Google Home.

Đề xuất

Bạn nên thực hiện những điều sau:

  1. Hiển thị Chính sách quyền riêng tư của Google. Thê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 xin phép.

  2. Dữ liệu sẽ được chia sẻ. Dùng ngôn ngữ rõ ràng và súc tích để cho người dùng biết Google yêu cầu dữ liệu nào của họ và lý do tại sao.

  3. Có thể huỷ liên kết. Cung cấp một cơ chế để người dùng huỷ liên kết, chẳng hạn như một URL đến phần 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ể thêm một đườ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 của họ.

  4. Có thể thay đổi tài khoản người dùng. Đề xuất mộ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 một lỗi có thể khôi phục đến 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.

  5. Thêm biểu trưng của bạn. Hiển thị biểu trưng công ty của bạn trên màn hình đồng ý. Sử dụng nguyên tắc về phong cách để đặt biểu trưng. Nếu bạn cũng muốn hiển thị biểu trưng của Google, hãy xem phần Biểu trưng và nhãn hiệu.

Hình này minh hoạ một ví dụ về màn hình yêu cầu sự đồng ý có chú thích cho từng yêu cầu và đề xuất mà bạn cần tuân thủ khi thiết kế màn hình yêu cầu sự đồng ý của người dùng.
Hình 1: Nguyên tắc thiết kế màn hình đồng ý liên kết tài khoản.

Thiết lập cho App Flip dựa trên OAuth

Các phần sau đây mô tả các điều kiện tiên quyết cho tính năng Lật ứng dụng dựa trên OAuth và cách định cấu hình dự án Lật ứng dụng trong Google Home Developer Console.

Tạo một chế độ tích hợp Cloud-to-cloud và thiết lập máy chủ OAuth 2.0

Trước khi có thể định cấu hình App Flip, bạn cần làm như sau:

Định cấu hình tính năng lật ứng dụng trong Developer Console

Phần sau đây mô tả cách định cấu hình tính năng lật ứng dụng trong Developer Console.

  1. Điền vào tất cả các trường bắt buộc(*) trong phần Liên kết tài khoản. (Nếu lật ứng dụng không được hỗ trợ, OAuth thông thường sẽ được dùng làm phương án dự phòng.)
  2. Cung cấp URL cho URL thực hiện trên đám mây. URL thực hiện trên đám mây được dùng để xử lý ý định nhà thông minh của bạn. Kiểm tra Thực hiện tại địa phương.
  3. Trong phần App Flip (optional) (Lật ứng dụng (không bắt buộc)), hãy đánh dấu vào Android app (Ứng dụng Android).
  4. Điền vào các trường sau:
    • Mã ứng dụng. Mã ứng dụng là mã nhận dạng duy nhất mà bạn đặt cho ứng dụng của mình.
    • Chữ ký ứng dụng. Ứng dụng Android phải được "ký" bằng chứng chỉ khoá công khai trước khi có thể cài đặt. Để biết thông tin về cách lấy chữ ký ứng dụng, hãy xem bài viết Xác thực ứng dụng của bạn.
    • Ý định uỷ quyền. Trong trường này, hãy nhập một chuỗi chỉ định hành động theo ý định của bạn.
  5. Nếu bạn muốn định cấu hình ứng dụng(không bắt buộc), hãy thêm phạm vi rồi nhấp vào Thêm phạm vi trong phần Phạm vi (không bắt buộc).
  6. Nếu ứng dụng khách của bạn yêu cầu, hãy chọn Yêu cầu Google truyền mã ứng dụng khách và mật khẩu ứng dụng khách qua tiêu đề xác thực cơ bản HTTP.

Giờ đây, bạn có thể tiếp tục chuyển sang phần tiếp theo để triển khai App Flip trong ứng dụng Android.

Triển khai App Flip trong ứng dụng gốc

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

Tính năng liên kết lật ứng dụng dựa trên OAuth (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 thông thường yêu cầu người dùng nhập thông tin đăng nhập của họ vào trình duyệt. Việc sử dụng tính năng lật ứng dụng sẽ trì hoãn việc đăng nhập của người dùng vào ứng dụng Android của bạn, cho phép bạn tận dụng các quyền uỷ quyền hiện có. Nếu người dùng đã đăng nhập vào ứng dụng của bạn, họ không cần phải nhập lại thông tin đăng nhập để liên kết tài khoản. Bạn chỉ cần thay đổi một lượng mã tối thiểu để triển khai tính năng Lật ứng dụng trên ứng dụng Android của mình.

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.

Dùng thử mẫu

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

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

Cách hoạt động

Bạn cần thực hiện các bước sau để tích hợp tính năng Lật ứng dụng:

  1. Ứng dụng Google kiểm tra xem ứng dụng của bạn có được cài đặt trên thiết bị hay không bằng cách sử dụng tên gói của ứng dụ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 một ý định để bắt đầu một hoạt động được chỉ định trong ứng dụng của bạn. Ý định này bao gồm dữ liệu bổ sung cần thiết cho việc liên kết. Ứng dụng 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 phân giải ý định này thông qua khung Android.
  4. Ứng dụng của bạn xác thực rằng yêu cầu đến từ ứng dụng Google. Để làm việc này, ứng dụng của bạn sẽ kiểm tra chữ ký gói và mã ứng dụng khách được 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, hệ thống sẽ trả về mã uỷ quyền hoặc lỗi cho ứ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 mã uỷ quyền được cung cấp, thì quá trình trao đổi mã thông báo sẽ diễn ra giữa các máy chủ, giống như trong quy trình liên kết OAuth dựa trên trình duyệt.

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

Để hỗ trợ tính năng Lật ứng dụng, hãy thực hiện các thay đổi sau đây về mã cho ứ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 trong 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 điện.

    Bạn cần so khớp tên gói và chữ ký cho mọi ứng dụng Google mà người dùng có thể sử dụng để liên kết tài khoản. Ví dụ: để liên kết với các ứng dụng Google Home và Tìm kiếm, hãy thêm tên gói và chữ ký của các ứng dụng đó:

    • Tên gói: com.google.android.apps.chromecast.app
    • Chứng chỉ gốc SHA-256: 3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A
    • Chứng chỉ SHA-256 đã xoay vòng của tính năng Ký ứng dụng của Play: 5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6

    và

    • Tên gói: com.google.android.googlequicksearchbox
    • Chữ ký: F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91:04:80:AD:6B:2D:60:DB:83

    Yêu cầu liên kết nhà thông minh được khởi tạo trực tiếp bởi Google Home app (GHA). Nếu ứng dụng của bạn hạn chế phương thức gọi và trước đây chỉ cho phép ứng dụng Google Tìm kiếm, thì bạn phải thêm com.google.android.apps.chromecast.app và chứng chỉ SHA-256 của ứng dụng đó vào danh sách cho phép để tính năng Lật ứng dụng tiếp tục hoạt động.

    private fun verifyFingerprint(
    expectedPackage: String,
    expectedFingerprints: List<String>
): Boolean {
    val callingPackage = callingActivity?.packageName ?: return false
    if (callingPackage != expectedPackage) return false
    return expectedFingerprints.any { hex ->
        val sha256Bytes =
            hex.split(":").map { it.toInt(16).toByte() }.toByteArray()
        packageManager.hasSigningCertificate(
            callingPackage,
            sha256Bytes,
            PackageManager.CERT_INPUT_SHA256
        )
    }
}

  3. Trích xuất mã ứng dụng khách từ các tham số ý định và xác minh rằng mã ứ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 = "com.google.android.apps.chromecast.app"
// Original lineage certificate (3D:7A...) and active rotated
// Play App Signing certificate (5A:AD...)
private val EXPECTED_FINGERPRINTS = listOf(
    "3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A",
    "5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6"
)
...

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val clientId = intent.getStringExtra("CLIENT_ID")

    if (clientId == EXPECTED_CLIENT &&
        verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINTS)) {

        // ...authorize the user...
    }
}

  4. Sau khi uỷ quyền thành công, hãy trả lại mã uỷ quyền thu được 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 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 của dữ liệu phản hồi

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

  • AUTHORIZATION_CODE (String): Giá trị mã uỷ 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ã uỷ quyền được trả về.
    • Activity.RESULT_CANCELLED: Lỗi có thể khôi phục. Cho biết người dùng đã huỷ quy 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 một lần nữa 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ẽ cố gắng liên kết tài khoản bằng URL uỷ quyền.
    • 2: Lỗi không thể khôi phục: Ứng dụng Google huỷ 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 đại diện cho 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 mà con người có thể đọc được, mô tả lỗi.

Bạn cần cung cấp giá trị cho AUTHORIZATION_CODE khi resultCode == Activity.RESULT_OK. Trong tất cả các trường hợp khác, giá trị của AUTHORIZATION_CODE phải để 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à cho biết lỗi đó có thể khôi phục được hay là lỗi không thể khôi phục:

Mã lỗi Ý nghĩa Có thể khôi phục Không thể phục hồi
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ả mã lỗi, bạn phải trả về kết quả lỗi thông qua setResult để đảm bảo kích hoạt phương án dự phòng thích hợp.

Kiểm thử App Flip trên thiết bị của bạn

Giờ đây, khi đã tạo một chế độ tích hợp từ đám mây với đám mây và định cấu hình tính năng Lật ứng dụng trên bảng điều khiển cũng như 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 của mình. Bạn có thể dùng ứng dụng Google Home để thử nghiệm tính năng lật ứng dụng.

Để kiểm thử App Flip trong ứng dụng Google Home, hãy làm theo các bước sau:

  1. Chuyển đến Developer Console rồi chọn dự án của bạn.
  2. Chuyển đến Cloud-to-cloud > Test (Đám mây với đám mây > Thử nghiệm).
  3. Kích hoạt quy trình liên kết tài khoản từ ứng dụng Home:
    1. Mở Google Home app (GHA).
    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 một số nội dung?
    5. Chọn chế độ tích hợp Cloud-to-cloud trong danh sách nhà cung cấp. Tên này sẽ có tiền tố "[test]" trong danh sách. Khi bạn chọn chế độ tích hợp [test] trong danh sách, ứng dụng của bạn sẽ mở ra.
    6. Xác minh rằng ứng dụng của bạn đã được khởi chạy và bắt đầu thử nghiệm quy trình uỷ quyền.
Trước
Tạo chế độ tích hợp Cloud-to-cloud
Tiếp
iOS