Bắt đầu sử dụng Ambient API

Ambient API cho phép ứng dụng của bạn kết nối các thiết bị môi trường xung quanh với Tài khoản Google Photos của người dùng và hiển thị những bức ảnh mà họ chọn.

Quy trình Ambient API

Dưới đây là phần phân tích chi tiết về cách Ambient API hoạt động để kết nối một thiết bị, sau đó truy xuất và hiển thị các mục nội dung nghe nhìn:

  1. Kiểm tra thiết bị hiện có (nên làm): Trước khi tạo một thiết bị mới, bạn nên kiểm tra xem người dùng hiện tại đã có thiết bị hay chưa. Ứng dụng của bạn phải duy trì mối liên kết giữa người dùng nội bộ và deviceId do Google cung cấp cho mọi thiết bị mà họ tạo thông qua ứng dụng của bạn. Nếu tìm thấy deviceId cho người dùng, bạn có thể tiếp tục làm mới mã uỷ quyền của họ (nếu cần).

  2. Bắt đầu uỷ quyền OAuth 2.0: Bắt đầu quy trình OAuth 2.0 cho TV và Thiết bị đầu vào hạn chế bằng cách yêu cầu mã uỷ quyền.

  3. Tạo một thiết bị mới: Ứng dụng của bạn tạo một thiết bị trong Tài khoản Google Photos của người dùng bằng cách gọi CreateDevice và cung cấp UUID v4 hợp lệ.

    Sau khi tạo thiết bị thành công, API sẽ trả về một đối tượng AmbientDevice chứa deviceId do Google chỉ định. Ứng dụng của bạn phải lưu trữ deviceId này và liên kết với người dùng.

  4. Hiển thị settingsUri: đối tượng AmbientDevice bao gồm settingsUri. Hãy cung cấp URI này cho người dùng, thường là dưới dạng mã QR mà người dùng có thể quét bằng thiết bị di động. URI này sẽ chuyển hướng người dùng đến ứng dụng Google Photos, nơi họ có thể định cấu hình các nguồn nội dung nghe nhìn (ví dụ: album) mà họ muốn hiển thị trên thiết bị môi trường xung quanh.

  5. Thăm dò ý kiến về mediaSourcesSet: Ứng dụng của bạn nên định kỳ gọi phương thức GetDevice, cung cấp deviceId để kiểm tra trạng thái của thiết bị môi trường xung quanh. Theo dõi trường mediaSourcesSet trong phản hồi AmbientDevice. Trường này ban đầu sẽ là false.

    Sau khi người dùng chọn thành công các nguồn nội dung nghe nhìn trong ứng dụng Google Photos, trường này sẽ chuyển thành true.

    Phản hồi AmbientDevice bao gồm pollingConfig với pollInterval mà bạn nên dùng làm nguyên tắc cho tần suất thăm dò ý kiến.

  6. Truy xuất các mục nội dung nghe nhìn: Khi mediaSourcesSet trả về true, ứng dụng của bạn có thể bắt đầu tìm nạp các mục nội dung nghe nhìn do người dùng chọn.

    Gọi phương thức ListMediaItems, cung cấp deviceId. API sẽ trả về ListMediaItemsResponse chứa danh sách các đối tượng AmbientMediaItem. Mỗi AmbientMediaItem bao gồm các thông tin chi tiết như id, createTime và đối tượng MediaFile có siêu dữ liệu bổ sung. MediaFile chứa baseUrl mà bạn có thể dùng để tìm nạp các byte thực tế của một mục nội dung nghe nhìn. Hãy xem hướng dẫn về cách Liệt kê và truy xuất các mục nội dung nghe nhìn để biết thông tin chi tiết về các tham số baseUrl bổ sung.

  7. Hiển thị các mục nội dung nghe nhìn: Sử dụng baseUrl từ MediaFile để tải xuống và hiển thị nội dung nghe nhìn trên thiết bị môi trường xung quanh.

Cân nhắc quan trọng

Giới hạn và quản lý thiết bị:

  • Giới hạn thiết bị: Hãy lưu ý đến giới hạn 100 thiết bị cho mỗi người dùng ứng dụng của bạn.
  • Hoạt động trên thiết bị và mã thông báo: Bạn cần quản lý vòng đời của thiết bị và mã uỷ quyền của người dùng. Hãy cân nhắc thời gian thiết bị duy trì trạng thái hoạt động và cách bạn xử lý việc làm mới mã thông báo hoặc uỷ quyền lại nếu thiết bị chuyển sang trạng thái không hoạt động hoặc mã thông báo hết hạn.

Hướng dẫn về cách Tạo và quản lý thiết bị có thêm thông tin chi tiết.

Làm việc với các mục nội dung nghe nhìn:

  • Cách sử dụng mục nội dung nghe nhìn: Tìm hiểu cách tìm nạp và xử lý đúng cách nội dung của mục nội dung nghe nhìn bằng baseUrl, bao gồm mọi tham số hoặc quy trình xác thực cần thiết.
  • Xử lý lỗi: Triển khai quy trình xử lý lỗi mạnh mẽ cho các lệnh gọi API, bao gồm các trường hợp như NOT_FOUND cho thiết bị, FAILED_PRECONDITION nếu chưa đặt nguồn nội dung nghe nhìn và RESOURCE_EXHAUSTED nếu đạt đến giới hạn thiết bị.

Hướng dẫn về cách Liệt kê và truy xuất các mục nội dung nghe nhìn có thêm thông tin chi tiết, bao gồm cả thông tin về chính sách nội dung và tính năng lọc.

Các bước tiếp theo