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 mà họ đã chọn.

Quy trình API môi trường xung quanh

Dưới đây là thông tin chi tiết về cách hoạt động của Ambient API để 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 thiết bị mới, bạn nên kiểm tra xem thiết bị cho người dùng hiện tại đã tồn tại 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ã thông báo uỷ quyền của họ (nếu cần).

  2. Bắt đầu quy trình uỷ quyền OAuth 2.0 (và tuỳ ý tạo thiết bị): Bắt đầu quy trình OAuth 2.0 cho TV và Thiết bị đầu vào có giới hạn bằng cách yêu cầu mã uỷ quyền.

  3. Tạo 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 một 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 cần 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 một settingsUri. Trình bày 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 để 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ị ở chế độ môi trường xung quanh.

  5. Thăm dò ý kiến về mediaSourcesSet: Ứng dụng của bạn phải đị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. Ban đầu, giá trị này 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ẽ thay đổi thành true.

    Phản hồi AmbientDevice bao gồm một pollingConfig với pollInterval mà bạn nên sử 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 đa phương tiện: Khi mediaSourcesSet trả về giá trị true, ứng dụng của bạn có thể bắt đầu tìm nạp các mục nội dung đa phương tiện do người dùng chọn.

    Gọi phương thức ListMediaItems, cung cấp deviceId. API sẽ trả về một 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 số byte thực tế của một mục nội dung nghe nhìn. Xem lại 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 khác.

  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.
  • Hoạt động và mã thông báo của thiết bị: Bạn cần quản lý vòng đời của thiết bị và mã thông báo uỷ quyền của người dùng. Hãy cân nhắc thời gian thiết bị vẫn hoạt động và cách bạn sẽ 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ị không hoạt động hoặc mã thông báo hết hạn.

Hướng dẫn 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:

  • Sử dụng mục nội dung nghe nhìn: Tìm hiểu cách tìm nạp và xử lý nội dung của mục nội dung nghe nhìn một cách chính xác bằng baseUrl, bao gồm mọi thông số hoặc thông tin xác thực cần thiết.
  • Xử lý lỗi: Triển khai tính năng 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 không đặ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 Liệt kê và truy xuất mục nội dung nghe nhìn có thêm thông tin chi tiết.

Các bước tiếp theo