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

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

مسار Ambient API

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

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

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

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

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

  4. عرض settingsUri: يتضمّن العنصر AmbientDevice settingsUri. اعرض عنوان URI هذا للمستخدم، عادةً كرمز استجابة سريعة، يمكن للمستخدم مسحه ضوئيًا باستخدام جهازه الجوّال. يوجه معرّف الموارد الموحّد هذا المستخدم إلى تطبيق "صور 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 إذا تم بلوغ الحدود القصوى للأجهزة.

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

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