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

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

قبل البدء

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

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

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

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

إنشاء جلسات

يمكنك إنشاء جلسة ليتمكّن المستخدمون من اختيار الصور بأمان مباشرةً من تطبيق "صور Google" ومشاركتها مع تطبيقك.

تنشئ sessions.create جلسة جديدة، وتعرض pickerUri فريدًا يمكنك تقديمه للمستخدمين. تظل الجلسة نشطة إلى أن يختار المستخدم ملفات وسائط بنجاح أو تنتهي مهلة الجلسة. بالنسبة إلى التطبيقات المستندة إلى الويب، يمكنك إضافة /autoclose إلى pickerUri لإغلاق نافذة "صور Google" أو علامتها تلقائيًا بعد أن يكمل المستخدم عملية الاختيار. يمكنك الاطّلاع على اختيار الصور: ما يراه المستخدمون للحصول على التفاصيل.

حدود الجلسات

انتبه إلى حدود الجلسة. تفرض واجهة برمجة التطبيقات 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: تكون القيمة true إذا انتهى المستخدم من اختيار ملفات الوسائط
  • ‫pollingConfig.pollInterval: الوقت المقترَح للانتظار قبل إجراء الاستطلاع التالي
  • ‫pollingConfig.timeoutIn: إجمالي الوقت الذي يجب انتظاره قبل انتهاء المهلة

إذا كانت قيمة mediaItemsSet هي false ولم يتم الوصول إلى قيمة timeoutIn، انتظِر إلى أن يحين الوقت pollInterval ثم أرسِل طلبًا مرة أخرى.

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

في حال الوصول إلى timeoutIn، يجب التعامل مع انتهاء المهلة بشكل سليم.