Google đang chuyển đổi quy trình liên kết tài khoản nhà thông minh bên thứ ba để được xử lý hoàn toàn và độc lập trong ứng dụng Google Home. Bạn có thể cần cập nhật chế độ tích hợp trước ngày 30 tháng 10 năm 2026. Để biết thêm thông tin, hãy xem Hướng dẫn di chuyển tính năng liên kết tài khoản.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Lật ứng dụng cho iOS

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 iOS liên kết nhanh hơn 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ọ. 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 iOS.

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

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".
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.
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.
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ỷ.
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:

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.
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.
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ọ.
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.
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:

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 bài viết Triển khai máy chủ OAuth 2.0.
Tạo một chế độ tích hợp từ đám mây sang đám mây. Để tạo một công cụ tích hợp, hãy làm theo hướng dẫn trong phần Tạo công cụ tích hợp từ đám mây với đám mây.

Đị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.

Điền vào tất cả các trường trong phần Thông tin về ứng dụng OAuth. (Nếu App Flip không được hỗ trợ, OAuth thông thường sẽ được dùng làm phương án dự phòng.)
Trong phần Sử dụng ứng dụng của bạn để liên kết tài khoản(không bắt buộc), hãy đánh dấu vào Bật cho iOS.
Điền vào trường Đường liên kết phổ quát. Để biết thêm thông tin về đường liên kết phổ quát, hãy xem bài viết Cho phép ứng dụng và trang web liên kết đến nội dung của bạn.
Nếu bạn muốn định cấu hình ứng dụng khách (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 Định cấu hình ứng dụng khách (không bắt buộc).
Nhấp vào Lưu.

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 iOS.

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ẽ mở ứng dụng iOS của bạn từ một ứng dụng Google để giúp người dùng ứng dụng Google liên kết tài khoản của họ dễ dàng hơn. Bạn cần thực hiện những thay đổi nhỏ về mã đối với ứng dụng iOS để triển khai tính năng này.

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

Dùng thử mẫu

Ứng dụng mẫu App Flip minh hoạ một quy trình tích hợp liên kết tài khoản trên iOS tương thích với App Flip. Bạn có thể dùng ứng dụng này để xác minh cách phản hồi đường liên kết phổ quát 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 iOS. Bạn có thể dùng công cụ này để xác minh việc tích hợp ứng dụng iOS 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 đường liên kết phổ quát được kích hoạt bởi các ứng dụng di động của Google khi tính năng Lật ứng dụng được bật.

Cách hoạt động

Sau đây là các bước trong quy trình mà ứng dụng Google và ứng dụng của bạn thực hiện khi tính năng Lật ứng dụng diễn ra:

Ứng dụng Google cố gắng mở đường liên kết phổ quát của ứng dụng. Hệ thống có thể mở ứng dụng của bạn nếu ứng dụng đó được cài đặt trên thiết bị của người dùng và liên kết với đường liên kết phổ quát. Hãy xem bài viết Hỗ trợ đường liên kết phổ quát để biết thông tin chi tiết.
Ứng dụng của bạn kiểm tra để đảm bảo tham số client_id và redirect_uri được mã hoá trong URL đến khớp với đường liên kết phổ quát dự kiến của Google.
Ứng dụng của bạn yêu cầu mã uỷ quyền từ máy chủ OAuth2. Khi kết thúc quy trình này, ứng dụng của bạn sẽ trả về mã uỷ quyền hoặc lỗi cho ứng dụng Google. Để làm việc này, ứng dụng sẽ mở đường liên kết phổ quát của Google có thêm các tham số cho mã uỷ quyền hoặc lỗi.
Ứng dụng Google xử lý đường liên kết phổ quát của Google và tiếp tục với phần còn lại của quy trình. Nếu bạn cung cấp mã uỷ quyền, thì quá trình liên kết sẽ hoàn tất ngay lập tức. Quá trình trao đổi mã thông báo 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. Nếu hệ thống trả về mã lỗi, quy trình liên kết sẽ tiếp tục với các lựa chọn thay thế.

Sửa đổi ứng dụng iOS để 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 đối với mã trong ứng dụng iOS:

Xử lý NSUserActivityTypeBrowsingWeb trong Thực thể đại diện của ứng dụng.
Thu thập các tham số redirect_uri và state từ URL để sử dụng sau.

Kiểm tra để đảm bảo redirect_uri khớp với định dạng sau:

https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID

Xác minh rằng mã ứng dụng khách khớp với giá trị dự kiến. Sử dụng mã mẫu sau:

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([Any]?) -> Void) -> Bool
{
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL,
        let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: false),
        let params = components.queryItems else {
            return false
    }

    if let clientId = params.filter({$0.name == "client_id"}).first?.value,
        let state = params.filter({$0.name == "state"}).first?.value,
        let redirectUri = params.filter({$0.name == "redirect_uri"}).first?.value {

        // Save the redirect_uri and state for later...

        // Verify the client id
        return (clientId == GOOGLE_CLIENT_ID)
    } else {
        // Missing required parameters
        return false
    }
}

Sau khi uỷ quyền thành công, hãy gọi URI chuyển hướng bằng mã uỷ quyền. Sử dụng mã mẫu sau:

func returnAuthCode(code: String, state: String, redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramAuthCode = URLQueryItem(name: "code", value: code)
    let paramState = URLQueryItem(name: "state", value: state)
    components?.queryItems = [paramAuthCode, paramState]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

Nếu xảy ra lỗi, hãy đính kèm kết quả lỗi vào URI chuyển hướng. Sử dụng mã mẫu sau:

func returnError(redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramError = URLQueryItem(name: "error", value: "invalid_request")
    let paramDescription = URLQueryItem(name: "error_description", value: "Invalid Request")
    components?.queryItems = [paramError, paramDescription]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

Tham số truy vấn cho đường liên kết phổ quát của ứng dụng

Khi được ứng dụng Google mở, đường liên kết phổ quát của ứng dụng sẽ bao gồm các tham số truy vấn sau:

client_id (String): client_id của Google được đăng ký trong ứng dụng của bạn.
scope (List of String): Danh sách các phạm vi được yêu cầu, phân tách bằng dấu cách.
state (String): Một số chỉ dùng một lần mà Google sử dụng để xác minh rằng kết quả uỷ quyền là để phản hồi yêu cầu gửi đi của Google.
redirect_uri (String): Đường liên kết phổ quát của Google. URI "flip" để mở ứng dụng Google và truyền kết quả.

Tham số truy vấn cho đường liên kết phổ quát của Google

Các tham số được sử dụng khi kết quả uỷ quyền được trả về thành công:

code (String): Giá trị của mã uỷ quyền, nếu có.
state (String): Giá trị chính xác nhận được từ đường liên kết phổ quát đến.

Các tham số được dùng khi kết quả uỷ quyền không thành công:

error (String), với các giá trị sau:
- cancelled: 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. Một số ví dụ là người dùng không đăng nhập được, thiết bị không có mạng hoặc kết nối hết thời gian chờ.
- unrecoverable: Lỗi không thể khôi phục. Ví dụ: Người dùng cố gắng liên kết với một tài khoản bị vô hiệu hoá.Ứng dụng Google sẽ huỷ quy trình liên kết tài khoản.
- invalid_request: Tham số yêu cầu không hợp lệ hoặc bị thiếu. Đây là 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.
- access_denied: Người dùng từ chối yêu cầu đồng ý. Đây là lỗi không thể khôi phục; ứng dụng Google sẽ huỷ liên kết.
error_description (String, không bắt buộc): Thông báo lỗi thân thiện với người dùng.

Lưu ý: Để biết thêm thông tin về các lỗi có thể xảy ra và nội dung không bắt buộc của trường error_description, hãy xem tiêu chuẩn OAuth 2.0.

Đối với tất cả các loại lỗi, bạn phải trả về dữ liệu phản hồi cho REDIRECT_URI được chỉ định để đảm bảo kích hoạt phương án dự phòng thích hợp.

Sửa đổi điểm cuối uỷ quyền để hỗ trợ tính năng Lật ứng dụng

Định cấu hình nền tảng của bạn để chấp nhận các yêu cầu sử dụng URL chuyển hướng của tính năng lật ứng dụng của Google:

Ứng dụng Google Home

https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast

Ứng dụng Trợ lý Google

https://oauth-redirect.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.OPA
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA

Đối với Google Home app (GHA), tính năng liên kết tài khoản Nhà thông minh sử dụng URL chuyển hướng com.google.Chromecast. Hãy đảm bảo máy chủ uỷ quyền của bạn cho phép các URL chuyển hướng này.

Kiểm tra để đảm bảo client_id và URL do tham số redirect_uri chỉ định khớp với các giá trị dự kiến khi nhận được yêu cầu. Nếu quy trình xác minh ứng dụng không thành công, hãy trả về lỗi invalid_request cho redirect_uri.

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 dụ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:

Chuyển đến Developer Console rồi chọn dự án của bạn.
Chuyển đến Cloud-to-cloud > Test (Đám mây với đám mây > Thử nghiệm).
Kích hoạt quy trình liên kết tài khoản từ ứng dụng Home:

Mở Google Home app (GHA).
Nhấp vào nút +.
Nhấp vào Thiết lập thiết bị.
Nhấp vào Bạn đã thiết lập một số nội dung?
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.
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.

Android

Tiếp

Xác định và đồng bộ hoá