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

Luồng Ambient API

Sau đây là thông tin 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 dùng): 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à người dùng 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ến hành làm mới mã thông báo uỷ quyền của họ (nếu cần).

  2. Bắt đầu 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 hạn chế 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. Điều quan trọng là ứ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 một settingsUri. Xuất hiện 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 của họ. 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ị 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ị 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 có 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ề 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 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ề 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 một baseUrl mà bạn có thể dùng để tìm nạp các byte thực 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 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ị 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 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ị 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 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 nội dung của mục nội dung nghe nhìn bằng cách sử dụng baseUrl, bao gồm mọi thông số hoặc hoạt động 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ả những trường hợp như NOT_FOUND cho thiết bị, FAILED_PRECONDITION nếu nguồn nội dung nghe nhìn chưa được đặt 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à bộ lọc.

Các bước tiếp theo