بدء استخدام Ambient API

تتيح Ambient API لتطبيقك ربط الأجهزة المزوّدة بميزة "العرض على الشاشة" بحساب "صور Google" الخاص بالمستخدم وعرض صوره التي اختارها.

مسار Ambient API

في ما يلي تفاصيل عن آلية عمل Ambient API لربط جهاز ثم استرداد عناصر الوسائط وعرضها:

1. البحث عن جهاز حالي (إجراء يُنصح به): قبل إنشاء جهاز جديد، ننصح بالتحقّق ممّا إذا كان هناك جهاز للمستخدم الحالي. يجب أن يحافظ تطبيقك على تعيين بين المستخدم الداخلي وdeviceId الذي تقدّمه Google لأي أجهزة ينشئها من خلال تطبيقك. إذا تم العثور علىdeviceId للمستخدم، يمكنك المتابعة لإعادة تحميل الرمز المميّز المخصص له (إذا لزم الأمر).

2. بدء عملية تفويض OAuth 2.0 (وإنشاء جهاز اختياريًا): ابدأ مسار OAuth 2.0 للتلفزيون وأجهزة الإدخال ذات الوظائف المحدودة بطلب رمز التفويض.

   ملاحظة: تتيح Ambient API خيار تضمين المَعلمة state في طلب التفويض. سيؤدي ذلك إلى توجيه Ambient API إلى محاولة إنشاء جهاز جديد أيضًا بعد اكتمال عملية التفويض بنجاح.

3. إنشاء جهاز جديد: ينشئ تطبيقك جهازًا في حساب أحد المستخدمين على "صور Google" من خلال استدعاء CreateDevice وتقديم معرّف UUID صالح من الإصدار 4.

   بعد إنشاء الجهاز بنجاح، ستُرجع واجهة برمجة التطبيقات AmbientDevice عنصرًا يحتوي على deviceId تم تعيينه من قِبل Google. من الضروري أن يخزن تطبيقك هذا deviceId ويربطه بالمستخدمين.

4. عرض settingsUri: يتضمّن كائن AmbientDevice settingsUri. قدِّم هذا المعرّف المميّز للمستخدم، عادةً في شكل رمز استجابة سريعة يمكنه مسحه ضوئيًا باستخدام جهازه الجوّال. يوجّه عنوان URL هذا المستخدم إلى تطبيق "صور Google" حيث يمكنه ضبط مصادر الوسائط (مثل الألبومات) التي يريد عرضها على جهازه المخصّص للعرض.

5. الاستعلام عن mediaSourcesSet: يجب أن يستدعي تطبيقك بشكل دوري GetDevice، مع تقديم deviceId، للتحقّق من حالة الجهاز المحيطي. راقِب حقل mediaSourcesSet في استجابة AmbientDevice. ستكون القيمة false في البداية.

   بعد أن يختار المستخدم مصادر الوسائط بنجاح في تطبيق "صور Google"، سيتم تغيير هذا الحقل إلى true.

   يتضمّن استجابة AmbientDevice pollingConfig مع pollInterval يجب استخدامه كدليل لتحديد كثافة قياس الأداء.

6. استرداد عناصر الوسائط: عندما يعرض mediaSourcesSet القيمة true، يمكن لتطبيقك بدء جلب عناصر الوسائط التي اختارها المستخدم.

   استخدِم طريقة ListMediaItems مع تقديم deviceId. ستعرِض واجهة برمجة التطبيقات ListMediaItemsResponse يحتوي على قائمة بAmbientMediaItem كائنات. يتضمّن كل AmbientMediaItem تفاصيل مثل id و createTime وMediaFile مع بيانات وصفية إضافية. يحتوي العنصر MediaFile على عنصر baseUrl يمكنك استخدامه لجلب البايتات الفعلية لعنصر وسائط. راجِع دليل إدراج عناصر الوسائط واستردادها للاطّلاع على تفاصيل حول مَعلمات baseUrl الإضافية.

7. عرض عناصر الوسائط: استخدِم baseUrl من MediaFile لتنزيل محتوى الوسائط و عرضه على الجهاز المخصّص للعرض السينمائي.

اعتبارات مهمة

الحد الأقصى لعدد الأجهزة وإدارتها:

• حدود الأجهزة: يُرجى العِلم أنّ الحد الأقصى المسموح به هو 100 جهاز لكل مستخدم في تطبيقك.
• نشاط الجهاز والرموز المميّزة: ستحتاج إلى إدارة دورة حياة الأجهزة ورموز التفويض الخاصة بالمستخدمين. ننصحك بالتفكير في المدة التي تظل فيها الأجهزة نشطة و كيفية معالجة عمليات إعادة تحميل الرموز المميّزة أو إعادة التفويض إذا أصبح الجهاز غير نشط أو انتهت صلاحية الرمز المميّز.

يتضمّن دليل إنشاء الأجهزة وإدارتها تفاصيل إضافية.

العمل مع عناصر الوسائط:

• استخدام عنصر الوسائط: فهم كيفية جلب محتوى baseUrl ومعالجته بشكل صحيح باستخدام baseUrl، بما في ذلك أي مَعلمات أو مصادقة ضرورية
• معالجة الأخطاء: يجب تنفيذ معالجة فعّالة للأخطاء في طلبات البيانات من واجهة برمجة التطبيقات، بما في ذلك السيناريوهات مثل NOT_FOUND للأجهزة، وFAILED_PRECONDITION في حال عدم ضبط مصادر الوسائط، وRESOURCE_EXHAUSTED في حال بلوغ الحدود القصوى المسموح بها للأجهزة.

يتضمّن دليل إدراج عناصر الوسائط واستردادها تفاصيل إضافية.

الخطوات التالية

• ضبط إعدادات تطبيقك: تأكَّد من توفُّر بيانات الاعتماد اللازمة ومن ضبط إعدادات تطبيقك لاستخدام بروتوكول OAuth 2.0 للتلفزيون وأجهزة الإدخال المحدود.
• مراجعة المستندات المرجعية لواجهة برمجة التطبيقات Ambient API: يمكنك الاطّلاع على المستندات المرجعية المفصّلة لجميع ال methods المتاحة ومَعلمات الطلب والاستجابة ورمز الخطأ.