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

تُعدّ الجلسات عنصرًا أساسيًا في 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، عليك التعامل مع مهلة الانتظار بشكلٍ مناسب.