เริ่มต้นใช้งาน Ambient API

Ambient API ช่วยให้แอปพลิเคชันของคุณเชื่อมต่ออุปกรณ์แอมเบียนท์กับบัญชี Google Photos ของผู้ใช้และแสดงรูปภาพที่ผู้ใช้เลือกได้

ขั้นตอนการทำงานของ Ambient API

ต่อไปนี้คือรายละเอียดเกี่ยวกับวิธีที่ Ambient API ทำงานเพื่อเชื่อมต่ออุปกรณ์ จากนั้นดึงและแสดงรายการสื่อ

  1. ตรวจสอบอุปกรณ์ที่มีอยู่ (แนะนำ): ก่อนสร้างอุปกรณ์ใหม่ เราขอแนะนำให้ตรวจสอบว่ามีอุปกรณ์สำหรับผู้ใช้ปัจจุบันอยู่แล้วหรือไม่ แอปพลิเคชันของคุณควรเก็บรักษาการแมประหว่างผู้ใช้ภายในกับ deviceId ที่ Google ให้มาสำหรับอุปกรณ์ใดก็ตามที่ผู้ใช้สร้างผ่านแอปของคุณ หากพบ deviceId ของผู้ใช้ คุณสามารถดำเนินการรีเฟรชโทเค็นการให้สิทธิ์ของผู้ใช้ (หากจำเป็น)

  2. เริ่มการให้สิทธิ์ OAuth 2.0: เริ่มขั้นตอนการทำงานของ OAuth 2.0 สำหรับทีวีและอุปกรณ์อินพุตแบบจำกัด โดยขอรหัสการให้สิทธิ์

  3. สร้างอุปกรณ์ใหม่: แอปของคุณสร้างอุปกรณ์ในบัญชี Google Photos ของผู้ใช้โดยเรียก CreateDevice และระบุ UUID v4 ที่ถูกต้อง

    เมื่อสร้างอุปกรณ์สำเร็จแล้ว API จะแสดงออบเจ็กต์ AmbientDevice ที่มี deviceId ซึ่ง Google กำหนด แอปพลิเคชันของคุณต้องจัดเก็บ deviceId นี้และเชื่อมโยงกับผู้ใช้

  4. แสดง settingsUri: ออบเจ็กต์ AmbientDevice มี settingsUri แสดง URI นี้แก่ผู้ใช้ โดยปกติจะแสดงเป็นคิวอาร์โค้ดที่ผู้ใช้สแกนได้โดยใช้อุปกรณ์เคลื่อนที่ URI นี้จะนำผู้ใช้ไปยังแอป Google Photos ซึ่งผู้ใช้สามารถกำหนดค่าแหล่งที่มาของสื่อ (เช่น อัลบั้ม) ที่ต้องการแสดงในอุปกรณ์แอมเบียนท์ได้

  5. สำรวจ mediaSourcesSet: แอปพลิเคชันของคุณควรเรียกใช้เมธอด GetDevice เป็นระยะๆ โดยระบุ deviceId เพื่อตรวจสอบสถานะของอุปกรณ์แอมเบียนท์ ตรวจสอบช่อง mediaSourcesSet ในการตอบกลับ AmbientDevice ซึ่งจะมีค่าเป็น "เท็จ" ในตอนแรก

    เมื่อผู้ใช้เลือกแหล่งที่มาของสื่อในแอป Google Photos ได้สำเร็จแล้ว ช่องนี้จะเปลี่ยนเป็น "จริง"

    การตอบกลับ AmbientDevice มี pollingConfig พร้อม pollInterval ที่คุณควรใช้เป็นแนวทางสำหรับความถี่ในการสำรวจ

  6. ดึงข้อมูลรายการสื่อ: เมื่อ mediaSourcesSet แสดงผลเป็น "จริง" แอปพลิเคชันของคุณจะเริ่มดึงข้อมูลรายการสื่อที่ผู้ใช้เลือกได้

    เรียกใช้เมธอด ListMediaItems โดยระบุ deviceId API จะแสดงผล ListMediaItemsResponse ที่มีรายการออบเจ็กต์ AmbientMediaItem AmbientMediaItem แต่ละรายการมีรายละเอียดต่างๆ เช่น id, createTime และออบเจ็กต์ MediaFile ที่มีข้อมูลเมตาเพิ่มเติม MediaFile มี baseUrl ซึ่งคุณใช้เพื่อดึงข้อมูลไบต์จริงของรายการสื่อได้ ดูรายละเอียดเกี่ยวกับพารามิเตอร์ baseUrl เพิ่มเติมได้ในคู่มือการแสดงและดึงข้อมูลรายการสื่อ

  7. แสดงรายการสื่อ: ใช้ baseUrl จาก MediaFile เพื่อดาวน์โหลดและแสดงเนื้อหาสื่อในอุปกรณ์แอมเบียนท์

สิ่งสำคัญที่ต้องคำนึงถึง

ข้อจำกัดและการจัดการอุปกรณ์:

  • ข้อจำกัดของอุปกรณ์: โปรดทราบว่าแอปพลิเคชันของคุณจำกัดอุปกรณ์ไว้ที่ 100 เครื่องต่อผู้ใช้
  • กิจกรรมในอุปกรณ์และโทเค็น: คุณจะต้องจัดการวงจรชีวิตของอุปกรณ์และโทเค็นการให้สิทธิ์ของผู้ใช้ พิจารณาว่าอุปกรณ์จะใช้งานได้นานเท่าใด และคุณจะจัดการการรีเฟรชโทเค็นหรือการให้สิทธิ์อีกครั้งอย่างไรหากอุปกรณ์ไม่ทำงานหรือโทเค็นหมดอายุ

ดูรายละเอียดเพิ่มเติมได้ในคู่มือการสร้างและจัดการอุปกรณ์มี

การทำงานกับรายการสื่อ:

  • การใช้รายการสื่อ: ทำความเข้าใจวิธีดึงและจัดการเนื้อหารายการสื่ออย่างถูกต้องโดยใช้ baseUrl รวมถึงการตรวจสอบสิทธิ์หรือพารามิเตอร์ที่จำเป็น
  • การจัดการข้อผิดพลาด: ใช้การจัดการข้อผิดพลาดที่มีประสิทธิภาพสำหรับการเรียก API ซึ่งรวมถึงสถานการณ์ต่างๆ เช่น NOT_FOUND สำหรับอุปกรณ์, FAILED_PRECONDITION หากไม่ได้ตั้งค่าแหล่งที่มาของสื่อ และ RESOURCE_EXHAUSTED หากถึงขีดจำกัดของอุปกรณ์

ดูรายละเอียดเพิ่มเติมได้ในคู่มือการแสดงและดึงข้อมูลรายการสื่อ ซึ่งรวมถึงข้อมูลเกี่ยวกับนโยบายเนื้อหาและ การกรอง

ขั้นตอนถัดไป