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

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

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

**ملاحظة مهمة:** يجب إبداء الاهتمام بالتطوير باستخدام Engage.

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

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

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

1. يجب توفّر رقم تعريف عميل Google Workspace. إذا لم يكن متوفّرًا، قد تحتاج إلى إعداد Google Workspace وأي حسابات Google تريد استخدامها للاتصال بواجهة برمجة التطبيقات.
2. يمكنك إعداد حساب باستخدام Google Cloud Console باستخدام عنوان بريد إلكتروني مرتبط بـ Google Workspace.
3. يمكنك إنشاء مشروع جديد.
4. يمكنك إنشاء حساب خدمة لمصادقة واجهة برمجة التطبيقات. بعد إنشاء حساب الخدمة، سيتوفّر لديك عنصران:
   • رقم تعريف حساب الخدمة
   • ملف JSON يحتوي على مفتاح حساب الخدمة يجب الحفاظ على أمان هذا الملف. ستحتاج إليه لاحقًا لمصادقة عميلك على واجهة برمجة التطبيقات.
5. يمكن لمساحة العمل وحسابات 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 أو LiveStreamingVideoEntity أو VideoClipEntity. هذا الحقل إلزامي.

نص الطلب

الحقل	النوع	مطلوبة	الوصف
entities	قائمة بكائنات MediaEntity	نعم	قائمة بعناصر المحتوى بحدّ أقصى 5 عناصر سيتم الاحتفاظ بأول خمسة عناصر فقط وسيتم حذف الباقي. يُسمح بقائمة فارغة للإشارة إلى أنّ المستخدم قد انتهى من مشاهدة جميع العناصر.

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

الحقل	النوع	الوصف
movieEntity	MovieEntity	كائن يمثّل فيلمًا ضمن ContinuationCluster
tvEpisodeEntity	TvEpisodeEntity	كائن يمثّل حلقة تلفزيونية ضمن ContinuationCluster
liveStreamingVideoEntity	LiveStreamingVideoEntity	كائن يمثّل فيديو بث مباشر ضمن ContinuationCluster
videoClipEntity	VideoClipEntity	كائن يمثّل مقطع فيديو ضمن ContinuationCluster

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

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

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
        {
          "uri": "https://www.example.com/movie_entity_uri_for_android",
          "platforms": [
            "PLATFORM_ANDROID_TV",
            "PLATFORM_ANDROID"
          ]
        },
        {
          "uri": "https://www.example.com/movie_entity_uri_for_iOS",
          "platforms": [
            "PLATFORM_IOS"
          ]
        }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/movie1_img1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Movie 1 HD poster"
          },
          {
            "url": "http://www.example.com/movie1_imag2.png",
            "width": 640,
            "height": 360,
            "accessibility_text": "Movie 1 SD poster"
          }
        ],
        "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": [
        {
          "uri": "https://www.example.com/episode_entity_uri_for_android_mobile",
          "platforms": [
            "PLATFORM_ANDROID"
          ]
        },
        {
          "uri": "https://www.example.com/episode_entity_uri_for_android_tv",
          "platforms": [
            "PLATFORM_ANDROID_TV"
          ]
        },
        {
          "uri": "https://www.example.com/episode_entity_uri_for_iOS",
          "platforms": [
            "PLATFORM_IOS"
          ]
        }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/episode1_img1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Episode 1 HD poster"
          },
          {
            "url": "http://www.example.com/episode1_imag2.png",
            "width": 640,
            "height": 360,
            "accessibility_text": "Episode 1 SD poster"
          }
        ],
        "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"
      }
    },
    {
      "liveStreamingVideoEntity": {
        "name": "Live Sports Championship",
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "last_engagement_time_millis": 1780978284000,
        "last_play_back_position_time_millis": 1800000,
        "duration_millis": 7200000,
        "platform_specific_playback_uris": [
          {
            "uri": "https://www.example.com/live_streaming_entity_uri_for_android_tv",
            "platforms": ["PLATFORM_ANDROID_TV"]
          }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/live_stream_image1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Live Sports Championship Cover Image"
          }
        ],
        "start_time_epoch_millis": 1780976484000,
        "broadcaster": "Global Sports Network",
        "broadcaster_icon": {
          "url": "https://www.example.com/gsports.jpg",
          "width": 512,
          "height": 512,
          "accessibility_text": "Global Sports Network Logo"
        }
      }
    },
    {
      "videoClipEntity": {
        "name": "How to Brew the Perfect Espresso",
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "last_engagement_time_millis": 1780978284000,
        "last_play_back_position_time_millis": 120000,
        "duration_millis": 600000,
        "platform_specific_playback_uris": [
          {
            "uri": "https://www.example.com/video_clip_entity_uri_for_android_tv",
            "platforms": ["PLATFORM_ANDROID_TV"]
          }
        ],
        "poster_images": [
          {
            "url": "http://www.example.com/video_clip_image1.png",
            "width": 1920,
            "height": 1080,
            "accessibility_text": "Espresso Tutorial Cover Image"
          }
        ],
        "created_time_epoch_millis": 1780900000000,
        "creator": "Coffee Enthusiast John",
        "creator_image": {
          "url": "https://www.example.com/image/thumb/creators/john_avatar.jpg",
          "width": 256,
          "height": 256,
          "accessibility_text": "John's Avatar"
        }
      }
    }
  ]
}

حذف بيانات 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.

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