Định cấu hình ứng dụng của bạn cho Ambient API

Để bắt đầu sử dụng Ambient API, hãy định cấu hình dự án của bạn bằng cách bật API trong Google API Console và thiết lập mã ứng dụng OAuth 2.0. Ambient API sử dụng OAuth 2.0 cho TV và Ứng dụng thiết bị đầu vào có giới hạn.

Ứng dụng của bạn tương tác với API môi trường xung quanh thay mặt cho người dùng API môi trường xung quanh. Người dùng uỷ quyền cho các yêu cầu API này bằng giao thức OAuth 2.0.

Mã ứng dụng khách OAuth 2.0 cho phép người dùng ứng dụng đăng nhập, xác thực và nhờ đó sử dụng Ambient API. Ambient API không hỗ trợ tài khoản dịch vụ; để sử dụng các API này, người dùng phải đăng nhập vào một Tài khoản Google hợp lệ.

Định cấu hình ứng dụng

Trước tiên, hãy bật API, sau đó yêu cầu mã ứng dụng khách OAuth 2.0.

Bật API

Trước khi có thể sử dụng Ambient API, bạn phải bật API này trong dự án.

Truy cập vào Google API Console.
Trên thanh trình đơn, hãy chọn một dự án hoặc tạo dự án mới.
Để mở một trong các API của Google Photos, trong trình đơn Điều hướng, hãy chọn API và dịch vụ > Thư viện.
Tìm "Ambient API". Chọn Ambient API rồi nhấp vào Bật.

Yêu cầu mã ứng dụng khách OAuth 2.0

Làm theo các bước sau để yêu cầu mã ứng dụng khách OAuth và định cấu hình mã đó cho ứng dụng của bạn. API môi trường xung quanh sử dụng OAuth 2.0 cho TV và Ứng dụng thiết bị đầu vào có giới hạn.

Chuyển đến Google API Console rồi chọn dự án của bạn.
Trong trình đơn, hãy chọn API và dịch vụ > Thông tin xác thực.
Trên trang Thông tin xác thực, hãy nhấp vào Tạo thông tin xác thực > Mã ứng dụng khách OAuth.

Lưu ý: Nếu đang thiết lập một dự án mới, bạn có thể được nhắc định cấu hình màn hình xin phép của dự án.
Chọn Loại ứng dụng. Trong ví dụ này, loại ứng dụng là TV và thiết bị đầu vào có giới hạn.
Nhập tên cho ứng dụng khách OAuth 2.0 rồi nhấp vào Tạo.
Trong hộp thoại ứng dụng khách OAuth thu được, hãy sao chép nội dung sau:
- ID khách hàng
- Mật khẩu ứng dụng khách

Ứng dụng của bạn có thể truy cập vào các API của Google đã bật bằng các giá trị này.

Trước khi bạn có thể phát hành một ứng dụng công khai truy cập vào Ambient API, ứng dụng của bạn phải được Google xem xét. Thông báo "Ứng dụng chưa được xác minh" sẽ xuất hiện trên màn hình khi bạn kiểm thử ứng dụng cho đến khi ứng dụng đó được xác minh.

Sau khi định cấu hình ứng dụng, bạn đã sẵn sàng bắt đầu. Bạn có thể khám phá các tài nguyên sau hoặc đọc thêm về quy trình xác thực đơn giản cho Ambient API.

Thay đổi mã ứng dụng khách

Bạn chỉ có thể truy cập hoặc chỉnh sửa các tài nguyên được tạo thông qua bất kỳ API Google Photos nào bằng mã ứng dụng ban đầu dùng để tạo các tài nguyên đó. Ví dụ: nếu bạn tạo một session trong API bộ chọn bằng một mã ứng dụng cụ thể và sau đó thay đổi mã ứng dụng đó trong ứng dụng, thì ứng dụng của bạn sẽ mất quyền truy cập vào mọi tài nguyên API được tạo bằng mã ứng dụng trước đó.

Hãy lập kế hoạch cẩn thận và chọn đúng loại mã ứng dụng cho API Photos mà bạn đang sử dụng. Chỉ thay đổi mã ứng dụng nếu thực sự cần thiết để tránh các vấn đề về quyền truy cập.

Quy trình xác thực đơn giản cho Ambient API

Quy trình xác thực API môi trường xung quanh tiêu chuẩn yêu cầu người dùng quét 2 mã QR:

Đăng nhập vào Tài khoản Google của họ lần đầu tiên (nếu họ chưa đăng nhập).
Một đường liên kết thứ hai liên kết đến thiết bị Ambient mới tạo trong tài khoản Google Photos của họ, nơi họ có thể chọn các mục nội dung nghe nhìn để hiển thị.

Quy trình đơn giản này cho phép bạn cung cấp một mã QR duy nhất cho người dùng bằng cách truyền thông số state bổ sung với lệnh gọi xác thực ban đầu.

Khi yêu cầu mã thiết bị và mã người dùng trong OAuth cho các thiết bị đầu vào có giới hạn, hãy thêm tham số state bổ sung vào yêu cầu của bạn. Thêm nội dung sau vào tham số state:

Thông số

Thông số
`requestId`	`string` Bắt buộc. Giá trị nhận dạng duy nhất do ứng dụng khách cung cấp cho yêu cầu này. Phương thức này dùng để giảm thiểu tình trạng trùng lặp tài nguyên trong trường hợp xảy ra lỗi mạng. Mã nhận dạng này phải có định dạng chuỗi UUID (phiên bản 4) và tuân thủ các yêu cầu sau: Không được chứa bất kỳ thông tin nhận dạng nhạy cảm nào về người dùng. Phải chứa 32 ký tự hệ thập lục phân được chia thành 5 nhóm, phân tách nhau bằng dấu gạch nối, theo định dạng "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (hoặc 8-4-4-4-12).
`displayName`	`string` Không bắt buộc. Tên hiển thị do người dùng xác định cho thiết bị này. Người dùng sẽ thấy thông tin này trong phần cài đặt của ứng dụng Google Photos nhưng chỉ có thể chỉnh sửa thông tin này thông qua API này. Tên hiển thị hợp lệ phải có từ 1 đến 100 ký tự (bao gồm cả hai giá trị này).

requestId

string

Bắt buộc. Giá trị nhận dạng duy nhất do ứng dụng khách cung cấp cho yêu cầu này. Phương thức này dùng để giảm thiểu tình trạng trùng lặp tài nguyên trong trường hợp xảy ra lỗi mạng.

Mã nhận dạng này phải có định dạng chuỗi UUID (phiên bản 4) và tuân thủ các yêu cầu sau:

Không được chứa bất kỳ thông tin nhận dạng nhạy cảm nào về người dùng.
Phải chứa 32 ký tự hệ thập lục phân được chia thành 5 nhóm, phân tách nhau bằng dấu gạch nối, theo định dạng "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (hoặc 8-4-4-4-12).

displayName

string

Không bắt buộc. Tên hiển thị do người dùng xác định cho thiết bị này.

Người dùng sẽ thấy thông tin này trong phần cài đặt của ứng dụng Google Photos nhưng chỉ có thể chỉnh sửa thông tin này thông qua API này.

Tên hiển thị hợp lệ phải có từ 1 đến 100 ký tự (bao gồm cả hai giá trị này).

Ví dụ: hãy xem khối mã sau:

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

Một phản hồi thành công sẽ bao gồm user_code và verification_url mà bạn hiển thị cho người dùng (rất có thể là mã QR) để họ có thể điều hướng đến đó trên một thiết bị riêng biệt. Bằng cách thêm tham số state, sau này khi gọi createDevice bằng API môi trường xung quanh, bạn có thể bỏ qua việc hiển thị settingsUri trong mã QR thứ hai, vì bước cuối cùng trong luồng OAuth sẽ tự động chuyển hướng đến vị trí này.

Để biết toàn bộ thông tin chi tiết, chúng tôi đã cung cấp thêm nội dung giải thích kỹ lưỡng hơn. Bạn cũng có thể xem lại mã trong ứng dụng mẫu của chúng tôi để biết ví dụ về cách sử dụng tham số state trong OAuth cho các thiết bị đầu vào bị hạn chế bằng API môi trường xung quanh.

Thông tin chi tiết về quy trình xác thực được tinh giản

Để hiểu đầy đủ về quy trình OAuth được tinh giản cho Ambient API, bạn cần hiểu cả quy trình OAuth 2.0 cho TV và Ứng dụng thiết bị có phương thức nhập hạn chế cũng như quy trình Ambient API tiêu chuẩn. Sau đây là các bước cho từng luồng.

OAuth 2.0 cho ứng dụng TV và thiết bị có phương thức nhập hạn chế:

Ứng dụng của bạn sẽ gửi một yêu cầu đến máy chủ uỷ quyền của Google để xác định các phạm vi mà ứng dụng của bạn sẽ yêu cầu quyền truy cập.
Máy chủ phản hồi bằng một số thông tin được dùng trong các bước tiếp theo, chẳng hạn như mã thiết bị và mã người dùng.
Bạn hiển thị thông tin mà người dùng có thể nhập trên một thiết bị riêng để uỷ quyền cho ứng dụng của bạn.
Ứng dụng của bạn bắt đầu thăm dò ý kiến máy chủ uỷ quyền của Google để xác định xem người dùng đã uỷ quyền cho ứng dụng của bạn hay chưa.
Người dùng chuyển sang một thiết bị có nhiều chức năng nhập hơn, chạy một trình duyệt web, chuyển đến URL hiển thị ở bước 3 và nhập một mã cũng hiển thị ở bước 3. Sau đó, người dùng có thể cấp (hoặc từ chối) quyền truy cập vào ứng dụng của bạn.
Phản hồi tiếp theo cho yêu cầu thăm dò ý kiến của bạn chứa các mã thông báo mà ứng dụng của bạn cần để uỷ quyền cho các yêu cầu thay mặt cho người dùng. (Nếu người dùng từ chối quyền truy cập vào ứng dụng của bạn, thì phản hồi sẽ không chứa mã thông báo.)

Luồng API môi trường xung quanh:

Kiểm tra mã thông báo OAuth hiện có rồi làm mới mã thông báo hoặc yêu cầu mã thông báo mới.
Sau khi lấy mã thông báo OAuth, hãy tạo một thiết bị mới.
Hiển thị settingsUri cho người dùng và bắt đầu thăm dò ý kiến thiết bị cho đến khi mediaSourcesSet trả về giá trị true.
Người dùng chuyển đến settingsUri và chọn những bức ảnh họ muốn chia sẻ với ứng dụng của bạn.
Sau khi mediaSourcesSet trả về true, hãy truy xuất danh sách mediaItems.
Bây giờ, bạn có thể bắt đầu trình chiếu hoặc trải nghiệm môi trường xung quanh khác.

Cả hai luồng đều có một bước mà bạn hiển thị URL cho người dùng và người dùng sẽ điều hướng đến URL đó trên thiết bị đầu vào phong phú hơn. Bằng cách đưa tham số state vào lệnh gọi OAuth ban đầu, bạn có thể tránh việc phải hiển thị URL thứ hai.

Điều này hoạt động vì bước cuối cùng của quy trình OAuth 2.0 cho TV và Ứng dụng thiết bị có phương thức nhập hạn chế thường chuyển hướng người dùng đến một trang có nội dung "Bạn hiện có thể quay lại thiết bị của mình". Bằng cách đưa tham số trạng thái vào, bước cuối cùng của luồng sẽ cố gắng chuyển hướng bạn đến settingsUri. Ứng dụng của bạn vẫn sẽ nhận được mã thông báo OAuth. Bạn nên sử dụng mã thông báo này để gọi createDevice bằng cùng một requestId. Sau khi tạo một thiết bị có cùng mã nhận dạng, quy trình OAuth ban đầu sẽ chuyển hướng người dùng đến đúng trang trên thiết bị đa năng trong ứng dụng Photos.

Hãy nhớ những điểm sau:

Bạn vẫn nên hiển thị settingsUri trong trường hợp có bất kỳ vấn đề nào về việc xác thực.
Bạn vẫn có thể sử dụng settingsUri trong các trường hợp khác, chẳng hạn như khi người dùng muốn cập nhật lựa chọn ảnh của họ.