بدء استخدام 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 وتقديم معرّف فريد عالمي صالح للإصدار 4.

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

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

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

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

   يتضمّن الردّ AmbientDevice pollingConfig مع pollInterval يجب استخدامه كإرشادات بشأن معدّل تكرار الاستطلاع.

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

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

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

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

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

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

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

التعامل مع ملفات الوسائط:

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

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

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

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