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

توفّر حزمة Engage SDK واجهة برمجة تطبيقات REST API لتقديم تجربة متابعة مشاهدة متّسقة على المنصات غير نظام 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. يمكن الآن لمساحة العمل وحسابات 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: المعرّف الفريد للملف الشخصي الخاص بالمستخدم ضمن الحساب في نظامك ويجب أن يتطابق مع معرّف الملف الشخصي المستخدَم في المسار على الجهاز فقط.

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

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

يتم تمثيل الحمولة في الطلب في الحقل entities. يمثّل entities قائمة بكيانات المحتوى، والتي يمكن أن تتألف من عنصر واحد أو أكثر من العناصر التالية: MovieEntity أو TVEpisodeEntity أو LiveStreamingVideoEntity أو VideoClipEntity. هذا الحقل إلزامي.

نص الطلب

الحقل

النوع

مطلوبة

الوصف

كيانات

قائمة بعناصر 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

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

لحذف بيانات مجموعة المتابعة، يمكنك إرسال طلب POST إلى واجهة برمجة التطبيقات clearCluster باستخدام الصيغة التالية.

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

المكان:

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

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

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

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

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

الاختبار

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

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