תחילת השימוש ב-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 תקין מגרסה 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, האפליקציה יכולה להתחיל לאחזר את פריטי המדיה שבחר המשתמש.

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

  7. הצגת פריטים של מדיה: משתמשים ב-baseUrl מ-MediaFile כדי להוריד את תוכן המדיה ולהציג אותו במכשיר האווירה.

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

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

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

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

עבודה עם פריטי מדיה:

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

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

השלבים הבאים