תחילת השימוש ב-Ambient API

‫Ambient API מאפשר לאפליקציה שלכם לחבר מכשירים עם תצוגה סביבתית לחשבון Google Photos של המשתמש ולהציג את התמונות שהוא בחר.

תהליך ה-API של Ambient

כך פועל Ambient API כדי לחבר מכשיר, ואז לאחזר ולהציג קובצי מדיה:

1. בדיקה אם המכשיר כבר קיים (מומלץ): לפני שיוצרים מכשיר חדש, מומלץ לבדוק אם כבר קיים מכשיר למשתמש הנוכחי. האפליקציה צריכה לשמור על מיפוי בין המשתמש הפנימי לבין ה-deviceId ש-Google סיפקה לכל המכשירים שהמשתמש יוצר דרך האפליקציה. אם נמצא deviceId למשתמש, אפשר להמשיך לרענון של אסימון ההרשאה שלו (במקרה הצורך).

2. מתחילים הרשאה באמצעות OAuth 2.0: מתחילים את התהליך של OAuth 2.0 לטלוויזיה ולמכשירים עם יכולות קלט מוגבלות על ידי בקשת קוד הרשאה.

   הערה: ב-Ambient API יש תמיכה בהוספת הפרמטר state לבקשת ההרשאה כדי להפעיל את תהליך האימות הפשוט.

3. יצירת מכשיר חדש: האפליקציה יוצרת מכשיר בחשבון Google Photos של המשתמש באמצעות קריאה ל-CreateDevice ומתן UUID חוקי בגרסה 4.

   אחרי שהמכשיר נוצר בהצלחה, ה-API יחזיר AmbientDevice אובייקט שמכיל deviceId שהוקצה על ידי Google. חשוב מאוד שהאפליקציה שלכם תשמור את deviceId ותקשר אותו למשתמשים.

4. הצגת settingsUri: אובייקט AmbientDevice כולל settingsUri. מציגים את ה-URI הזה למשתמש, בדרך כלל כקוד QR, שהמשתמש יכול לסרוק באמצעות המכשיר הנייד שלו. ה-URI הזה מפנה את המשתמש לאפליקציית Google Photos, שבה הוא יכול להגדיר את מקורות המדיה (למשל, אלבומים) שהוא רוצה להציג במכשיר עם תצוגת אווירה.

5. דגימה של mediaSourcesSet: האפליקציה צריכה לקרוא מדי פעם ל-method‏ GetDevice, ולספק את deviceId, כדי לבדוק את הסטטוס של המכשיר בסביבה. עוקבים אחרי השדה mediaSourcesSet בתשובה של AmbientDevice. בהתחלה הערך יהיה false.

   אחרי שהמשתמש יבחר מקורות מדיה באפליקציית Google Photos, השדה הזה ישתנה ל-true.

   התגובה של AmbientDevice כוללת pollingConfig עם pollInterval, שצריך להשתמש בו כהנחיה לתדירות הסקרים.

6. אחזור של קובצי מדיה: כש-mediaSourcesSet מחזיר את הערך True, האפליקציה יכולה להתחיל לאחזר את קובצי המדיה שהמשתמש בחר.

   מבצעים קריאה ל-ListMediaItems ומספקים את deviceId. ה-API יחזיר ListMediaItemsResponse שמכיל רשימה של אובייקטים מסוג AmbientMediaItem. כל AmbientMediaItem כולל פרטים כמו id, createTime ואובייקט MediaFile עם מטא-נתונים נוספים. השדה MediaFile מכיל baseUrl שבו אפשר להשתמש כדי לאחזר את הבייטים בפועל של קובץ מדיה. במדריך הצגה ושליפה של קובצי מדיה מפורטים פרמטרים נוספים של baseUrl.

7. הצגת קובצי מדיה: משתמשים בלחצן baseUrl מתוך MediaFile כדי להוריד ולהציג את תוכן המדיה במכשיר הסביבתי.

שיקולים חשובים

מגבלת מכשירים וניהול:

• מגבלות על מכשירים: שימו לב למגבלה של 100 מכשירים לכל משתמש באפליקציה.
• פעילות במכשיר וטוקנים: תצטרכו לנהל את מחזור החיים של המכשירים ושל טוקני ההרשאות של המשתמשים. חשוב להביא בחשבון את משך הזמן שבו המכשירים נשארים פעילים, ואיך תטפלו ברענון של טוקנים או באישור מחדש אם מכשיר הופך ללא פעיל או אם פג התוקף של הטוקן.

פרטים נוספים זמינים במדריך יצירה וניהול של מכשירים.

עבודה עם קובצי מדיה:

• שימוש בקובץ מדיה: צריך להבין איך לאחזר ולטפל בתוכן של קובץ המדיה בצורה נכונה באמצעות baseUrl, כולל כל האימותים או הפרמטרים הנדרשים.
• טיפול בשגיאות: מטמיעים טיפול יעיל בשגיאות בקריאות ל-API, כולל תרחישים כמו NOT_FOUND למכשירים, FAILED_PRECONDITION אם מקורות המדיה לא מוגדרים ו-RESOURCE_EXHAUSTED אם הגעתם למגבלות המכשירים.

במדריך הצגה ואחזור של קובצי מדיה יש פרטים נוספים, כולל מידע על מדיניות תוכן וסינון.

השלבים הבאים

• מגדירים את האפליקציה: מוודאים שיש לכם את פרטי הכניסה הדרושים והגדרתם את האפליקציה לשימוש ב-OAuth 2.0 לטלוויזיות ולמכשירים עם יכולות קלט מוגבלות.
• מעיינים במסמכי התיעוד של Ambient API: במסמכי התיעוד המפורטים מפורטים כל ה-methods הזמינים, הפרמטרים של הבקשות והתגובות וקודי השגיאה.