יצירה וניהול של סשנים

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

לפני שמתחילים

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

מחזור החיים של סשן

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

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

יצירת סשנים

אתם יכולים ליצור סשן כדי שהמשתמשים יוכלו לבחור תמונות באופן מאובטח ישירות מאפליקציית Google Photos ולשתף אותן בחזרה לאפליקציה שלכם.

‫sessions.create יוצר סשן חדש ומחזיר pickerUri ייחודי שאפשר להציג למשתמשים. הסשן נשאר פעיל עד שהמשתמש בוחר פריטי מדיה או עד שהזמן הקצוב לתפוגה של הסשן מסתיים. באפליקציות מבוססות-אינטרנט, אפשר להוסיף /autoclose ל-pickerUri כדי לסגור אוטומטית את החלון או הכרטיסייה של Google Photos אחרי שהמשתמש מסיים לבחור תמונות. לפרטים נוספים אפשר לעיין במאמר בחירת תמונות: מה המשתמשים רואים.

מגבלות של פעילות באתר

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

השתתפות בסקרים ומעקב אחרי סשנים

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

חשוב להשתמש בסקרים יעילים. התשובה sessions.get כוללת את האובייקט pollingConfig. כדי להימנע מקריאות מיותרות ולספק חוויית משתמש חלקה, כדאי להשתמש בשדות הבאים:

  • ‫pollInterval: אינטרוולים אופטימליים של שליחת בקשות
  • ‫timeoutIn: משך ההמתנה עד לפסק זמן

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

מחיקה וניקוי של סשנים

‫sessions.delete מסיר סשן. הפקודה הזו משמשת בדרך כלל לניקוי אחרי שהמשתמש סיים לבחור מדיה או אם הסשן הסתיים.

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

דוגמה לתהליך של סקר

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

  1. יצירת סשן: מתקשרים אל sessions.create כדי להתחיל סשן חדש ולקבל את pickerUri.
  2. מציגים את pickerUri למשתמש: מציגים את כתובת ה-URL או יוצרים קוד QR שהמשתמש יכול לסרוק. כדאי לקרוא סקירה כללית על חוויית הבחירה של המשתמשים.
  3. הפעלת סקר במפגש:
    1. משתמשים בערך המומלץ של pollInterval מ-pollingConfig.
    2. בודקת אם הערך של mediaItemsSet הוא True.
      1. אם מופיע הסמל true, ממשיכים לרשימת קובצי המדיה שנבחרו.
      2. אם false, ממשיכים לשלוח בקשות עד שמגיעים ל-timeoutIn.
    3. טיפול בזמנים קצובים לתפוגה ובביטולים בצורה חלקה.
GET https://photoslibrary.googleapis.com/v1/sessions/{sessionId}

זוהי דוגמה לתשובה:

{
  "id": string,
  "pickerUri": string,
  "pollingConfig": {
    object (PollingConfig)
  },
  "mediaItemsSet": boolean
}

מציגים את pickerUri למשתמש, ואז מתחילים לשלוח בקשות לנתונים מהסשן.

בודקים את התשובה כדי לוודא שהיא כוללת את הפרטים הבאים:

  • ‫mediaItemsSet: הערך הוא true אם המשתמש סיים לבחור פריטי מדיה
  • ‫pollingConfig.pollInterval: הזמן המומלץ להמתנה לפני הסקר הבא
  • ‫pollingConfig.timeoutIn: משך הזמן הכולל להמתנה לפני שחלף הזמן הקצוב לתפוגה

אם הערך של mediaItemsSet הוא false ולא הגיעו לערך של timeoutIn, צריך להמתין עד pollInterval ואז לשלוח שוב בקשת בדיקה.

אם הערך של mediaItemsSet הוא True, ממשיכים לרשימת פריטי המדיה שנבחרו.

אם מגיעים לערך timeoutIn, צריך לטפל בטיימ-אאוט בצורה תקינה.