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

تقع الجلسات في صميم واجهة برمجة التطبيقات 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. استخدِم أداة الاستطلاع الموصى بها من 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، يُرجى الانتظار حتى pollInterval ثم الاستطلاع مرة أخرى.

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

إذا تم الوصول إلى timeoutIn، تعامل مع المهلة بسلاسة.