إنشاء الجلسات وإدارتها

تُعدّ الجلسات عنصرًا أساسيًا في Picker API، إذ توفّر للمستخدمين أسلوبًا آمنًا ومُدارًا لاختيار الصور والفيديوهات من مكتبة "صور Google". يوضّح هذا الدليل كيفية إنشاء جلسات الاستطلاع وإدارتها وإجراء استطلاعات فعالة لتفعيل اختيار الصور بسلاسة في تطبيقك.

قبل البدء

  • ضبط إعدادات تطبيقك: فعِّل واجهة برمجة التطبيقات واضبط المصادقة. اطّلِع على ضبط تطبيقك للاطّلاع على الخطوات المفصّلة.
  • فهم العملية: راجِع البدء باستخدام Picker API للحصول على نظرة عامة على عملية اختيار الصور بالكامل.
  • مراجعة نطاقات التفويض المطلوبة: يتطلّب العمل مع الجلسات نطاق photospicker.mediaitems.readonly. لمزيد من المعلومات عن النطاقات، اطّلِع على نطاقات التفويض.

مراحل النشاط في الجلسة

توفّر Picker API طرقًا لإنشاء الجلسات واسترداد معلومات عنها ومحوها. بعد مصادقة المستخدمين، يمكنك استخدام الجلسات لإدارة رحلة اختيار الصور.

  1. أنشئ جلسة لتفعيل قدرة المستخدم على اختيار عناصر الوسائط.
  2. استخدِم الاستطلاع في الجلسة للتحقّق من وقت انتهاء المستخدم من تحديد عناصر الوسائط.
  3. إدراج عناصر الوسائط واستردادها
  4. تنظيف الجلسة من خلال حذفها

إنشاء جلسات

أنشئ جلسة ليختار المستخدمون الصور بأمان مباشرةً من تطبيق "صور Google"، ثم يشاركونها مرة أخرى مع تطبيقك.

يُنشئ sessions.create جلسة جديدة، ويعرض pickerUri فريدًا يمكنك تقديمه للمستخدمين. وتظل الجلسة نشطة إلى أن يختار المستخدِم عناصر الوسائط بنجاح أو تنتهي مهلة الجلسة.

حدود الجلسات

انتبه للحدود القصوى المسموح بها للجلسات. تفرض Picker API حدودًا على عدد الجلسات التي يمكنك إنشاؤها لضمان الاستخدام المسؤول ومنع إساءة الاستخدام. في ظل ظروف عادية، من غير المرجّح أن تصل إلى هذه الحدود. ومع ذلك، عليك تتبُّع الجلسات وتنظيفها بشكل استباقي لتجنُّب أي مشاكل.

الاستطلاعات ومراقبة الجلسات

بعد إنشاء جلسة، يتم إجراء استطلاع دوري لنقطة نهاية sessions.get للحصول على حالة الجلسة. تُعرِض السمة mediaItemsSet في الاستجابة قيمة true عندما يُكمل المستخدم اختياره.

احرص على استخدام طريقة فعّالة للاستطلاع. يتضمّن الردّ sessions.get عنصر pollingConfig. استخدِم الحقول التالية لمساعدتك في تجنُّب طلبات التعديل غير الضرورية وتقديم تجربة سلسة للمستخدم:

  • pollInterval: فواصل الاستطلاع المثلى
  • ‫timeoutIn: مدة الاستبعاد

اطّلِع على مثال على عملية الاستطلاع للحصول على مزيد من التفاصيل.

حذف الجلسات وتنظيمها

sessions.delete يزيل جلسة، ويُستخدَم عادةً للتنظيف بعد أن ينتهي المستخدِم من اختيار الوسائط أو إذا انتهت مهلة الجلسة.

من أفضل الممارسات حذف الجلسات بعد اختيار المستخدم لعناصر الوسائط واسترداد تطبيقك لعناصر الوسائط بايت.

مثال على مسار الاستطلاع

في ما يلي مثال على إنشاء جلسة وإجراء استطلاع لها. بعد مصادقة المستخدِم لأول مرة، أنشئ جلسة جديدة.

  1. إنشاء جلسة: اتصل بالرقم sessions.create لبدء جلسة جديدة و الحصول على pickerUri.
  2. عرض pickerUri على المستخدم: يمكنك عرض عنوان URL أو إنشاء رمز استجابة سريعة ليتمكّن المستخدم من مسحه ضوئيًا. اطّلِع على نظرة عامة على تجربة اختيار المستخدم.
  3. الاستطلاع في الجلسة:
    1. استخدِم القيمة المُقترَحة لفئة pollInterval من pollingConfig.
    2. تحقَّق مما إذا كان mediaItemsSet صحيحًا.
      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: صحيح إذا أنهى المستخدم اختيار عناصر الوسائط
  • pollingConfig.pollInterval: الوقت المُقترَح للانتظار قبل إجراء الاستطلاع التالي
  • ‫pollingConfig.timeoutIn: إجمالي الوقت الذي يجب الانتظار خلاله قبل انتهاء مهلة الانتظار

إذا كانت قيمة mediaItemsSet غير صحيحة ولم يتم الوصول إلى timeoutIn، انتظِر until pollInterval ثم أجرِ الاستطلاع مرة أخرى.

إذا كان mediaItemsSet صحيحًا، يمكنك المتابعة إلى إدراج عناصر الوسائط المحدّدة.

إذا تم الوصول إلى timeoutIn، عليك التعامل مع مهلة الانتظار بشكلٍ مناسب.