دمج ميزة "مواصلة المشاهدة" باستخدام REST API

book_path: /distribute/other-docs/_book.yaml project_path: /distribute/other-docs/_project.yaml

توفّر حزمة تطوير البرامج (SDK) الخاصة بمنصة Engage واجهة برمجة تطبيقات REST لتوفير تجربة متّسقة لميزة "متابعة المشاهدة" على منصات غير Android، مثل iOS وRoku TV. تتيح واجهة برمجة التطبيقات للمطوّرين تعديل حالة "مواصلة المشاهدة" للمستخدمين الذين وافقوا على المشاركة من منصات غير Android.

المتطلّبات الأساسية

• يجب أولاً إكمال عملية الدمج المستندة إلى حزمة Engage SDK على الجهاز. تُنشئ هذه الخطوة المهمة الربط اللازم بين رقم تعريف المستخدم في Google وAccountProfile في تطبيقك.
• الوصول إلى واجهة برمجة التطبيقات والمصادقة: لعرض واجهة برمجة التطبيقات وتفعيلها في مشروعك على Google Cloud، عليك اجتياز عملية الإدراج في القائمة المسموح بها. يجب مصادقة جميع طلبات واجهة برمجة التطبيقات.

الحصول على الإذن بالوصول

للحصول على إذن بعرض واجهة برمجة التطبيقات وتفعيلها في Google Cloud Console، يجب تسجيل حسابك.

1. يجب أن يتوفّر رقم تعريف عميل Google Workspace. إذا لم تكن متاحة، قد تحتاج إلى إعداد حساب على Google Workspace بالإضافة إلى أي حسابات على Google تريد استخدامها للاتصال بواجهة برمجة التطبيقات.
2. أنشئ حسابًا على Google Cloud Console باستخدام عنوان بريد إلكتروني مرتبط بحساب Google Workspace.
3. أنشئ مشروعًا جديدًا.
4. أنشئ حساب خدمة للمصادقة على واجهة برمجة التطبيقات. بعد إنشاء حساب الخدمة، سيتوفّر لك عنصران:
   • معرّف حساب خدمة
   • ملف JSON يحتوي على مفتاح حساب الخدمة يجب الحفاظ على أمان هذا الملف. ستحتاج إليه لاحقًا لمصادقة العميل على واجهة برمجة التطبيقات.
5. يمكن الآن لحسابات Workspace وحسابات Google المرتبطة بها استخدام واجهات برمجة التطبيقات REST. بعد أن يتم نشر التغيير، سيصلك إشعار يوضّح ما إذا كانت واجهة برمجة التطبيقات جاهزة ليتم استدعاؤها من خلال حسابات الخدمة.
6. اتّبِع هذه الخطوات للاستعداد لإجراء طلب بيانات من واجهة برمجة التطبيقات مفوَّض.

نشر مجموعة مواصلة

لنشر بيانات "إعلانات Video discovery"، أرسِل طلب POST إلى واجهة برمجة التطبيقات publishContinuationCluster باستخدام البنية التالية.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster

المكان:

• ‫package_name: اسم حزمة موفّر الوسائط
• accountId: المعرّف الفريد لحساب المستخدم في نظامك. يجب أن يتطابق مع accountId المستخدَم في المسار على الجهاز.
• profileId: المعرّف الفريد للملف الشخصي للمستخدم ضمن الحساب في نظامك. ويجب أن يتطابق مع profileId المستخدَم في المسار على الجهاز.

عنوان URL للحساب بدون ملف شخصي هو:

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster

يتم تمثيل الحمولة في الطلب في الحقل entities. يمثّل entities قائمة بكيانات المحتوى التي يمكن أن تكون MovieEntity أو TVEpisodeEntity. هذا الحقل إلزامي.

نص الطلب

يحتوي الحقل entities على movieEntity وtvEpisodeEntity فرديين.

يجب أن يكون كل عنصر في مصفوفة الكيانات أحد أنواع MediaEntity المتاحة، أي MovieEntity وTvEpisodeEntity، بالإضافة إلى الحقول الشائعة والحقول الخاصة بالنوع.

يعرض مقتطف الرمز التالي حمولة نص الطلب لواجهة برمجة التطبيقات publishContinuationCluster.

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/movie1_img1.png",
          "http://www.example.com/movie1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 5400000,
        "last_play_back_position_time_millis": 3241111
      }
    },
    {
      "tvEpisodeEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "TV SERIES EPISODE 1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/episode1_img1.png",
          "http://www.example.com/episode1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 1800000,
        "last_play_back_position_time_millis": 2141231,
        "episode_display_number": "1",
        "season_number": "1",
        "show_title": "title"
      }
    }
  ]
}

حذف بيانات "الفيديوهات المقترَحة"

استخدِم واجهة برمجة التطبيقات clearClusters لإزالة بيانات "اكتشاف الفيديوهات".

لحذف بيانات مجموعة استمرار المحادثة، أرسِل طلب POST إلى واجهة برمجة التطبيقات clearClusters باستخدام البنية التالية.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearClusters

المكان:

• package_name: اسم حزمة موفّر الوسائط
• accountId: المعرّف الفريد لحساب المستخدم في نظامك. يجب أن يتطابق مع accountId المستخدَم في المسار على الجهاز.
• profileId: المعرّف الفريد للملف الشخصي للمستخدم ضمن الحساب في نظامك. ويجب أن يتطابق مع profileId المستخدَم في المسار على الجهاز.

لا تحتوي البيانات الأساسية لواجهة برمجة التطبيقات clearClusters إلا على حقل واحد، وهو reason، الذي يتضمّن DeleteReason يحدّد سبب إزالة البيانات.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

الاختبار

بعد نشر البيانات بنجاح، استخدِم حسابًا تجريبيًا للمستخدمين للتأكّد من ظهور المحتوى المتوقّع في صف "متابعة المشاهدة" على مساحات عرض Google المستهدَفة، مثل Google TV وتطبيقات Google TV للأجهزة الجوّالة على Android وiOS.

أثناء الاختبار، اسمح بتأخير معقول في الانتشار لبضع دقائق والتزِم بمتطلبات المشاهدة، مثل مشاهدة جزء من فيلم أو إنهاء حلقة. راجِع إرشادات "ما التالي" لمطوّري التطبيقات للحصول على التفاصيل.