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

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

התהליך של Ambient API

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

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

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

   הערה: ב-Ambient API יש תמיכה באפשרות לכלול את הפרמטר state בבקשת ההרשאה. הפעולה הזו תגרום ל-Ambient API לנסות ליצור מכשיר חדש גם אחרי אישור מוצלח.

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

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

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

5. ביצוע בדיקה חוזרת של mediaSourcesSet: האפליקציה צריכה להפעיל את השיטה 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 הזמינים, פרמטרים של בקשות ותגובות וקודי שגיאה.