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

توفّر حزمة تطوير البرامج (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. اتّبِع هذه الخطوات للاستعداد لإجراء طلب بيانات من واجهة برمجة التطبيقات مفوَّض.

مجموعة نشر المتابعة

لنشر بيانات Engage، أرسِل طلب 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"
      }
    }
  ]
}

حذف بيانات Engage

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

لحذف بيانات مجموعة استمرار النشاط، أرسِل طلب 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.

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