دليل دمج حزمة Engage SDK للتلفزيون

تستفيد ميزة "مواصلة المشاهدة" من مجموعة "المحتوى الذي يمكن مواصلة مشاهدته" لعرض الفيديوهات غير المكتملة والحلقات التالية من الموسم التلفزيوني نفسه، وذلك من تطبيقات متعددة في مجموعة واحدة من واجهة المستخدم. يمكنك عرض عناصرهم في مجموعة الاستمرار هذه. اتّبِع هذا الدليل لمعرفة كيفية تحسين تفاعل المستخدمين من خلال تجربة "مواصلة المشاهدة" باستخدام Engage SDK.

العمل التحضيري

قبل البدء، أكمل الخطوات التالية:

  1. تحديث إلى المستوى 19 أو مستوى أحدث لواجهة برمجة التطبيقات المستهدَف

  2. أضِف مكتبة com.google.android.engage إلى تطبيقك باتّباع الخطوات التالية:

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

    الأجهزة الجوّالة

    
  dependencies {
    implementation 'com.google.android.engage:engage-core:1.5.5
  }

    تلفزيون

    
  dependencies {
    implementation 'com.google.android.engage:engage-tv:1.0.2
  }

  3. اضبط بيئة خدمة Engage على الإنتاج في ملف AndroidManifest.xml.

    الأجهزة الجوّالة

    
<meta-data
    android:name="com.google.android.engage.service.ENV"
    android:value="PRODUCTION" />

    تلفزيون

    
<meta-data
    android:name="com.google.android.engage.service.ENV"
    android:value="PRODUCTION" />

  4. إضافة إذن لـ WRITE_EPG_DATA لملف APK الخاص بالتلفزيون

    <uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />

  5. يمكنك التحقّق من نشر المحتوى بشكل موثوق من خلال استخدام خدمة تعمل في الخلفية، مثل androidx.work، لتحديد المواعيد.

  6. لتقديم تجربة مشاهدة سلسة، يجب نشر بيانات &quot;مواصلة المشاهدة&quot; عند حدوث الأحداث التالية:

    1. تسجيل الدخول لأول مرة: عند تسجيل دخول المستخدم لأول مرة، يجب نشر البيانات لضمان توفّر سجل المشاهدة على الفور.
    2. إنشاء الملف الشخصي أو التبديل بين الملفات الشخصية (التطبيقات التي تتيح استخدام ملفات شخصية متعددة): إذا كان تطبيقك يتيح استخدام ملفات شخصية متعددة، يجب نشر البيانات عندما ينشئ المستخدم ملفًا شخصيًا أو يبدّل بين الملفات الشخصية.
    3. انقطاع تشغيل الفيديو: لمساعدة المستخدمين في استئناف المشاهدة من حيث توقّفوا، يجب نشر البيانات عندما يوقفون الفيديو مؤقتًا أو يوقفونه، أو عندما يخرجون من التطبيق أثناء تشغيل الفيديو.
    4. تعديلات على شريط &quot;مواصلة المشاهدة&quot; (في حال توفّره): عندما يزيل المستخدم محتوًى من شريط &quot;مواصلة المشاهدة&quot;، يجب عرض هذا التغيير من خلال نشر بيانات معدَّلة.
    5. إكمال الفيديو:
      1. بالنسبة إلى الأفلام، أزِل الفيلم المكتمل من شريط "مواصلة المشاهدة". إذا كان الفيلم جزءًا من سلسلة، أضِف الفيلم التالي للحفاظ على تفاعل المستخدم.
      2. بالنسبة إلى الحلقات، أزِل الحلقة المكتملة وأضِف الحلقة التالية في السلسلة، إذا كانت متاحة، لتشجيع المشاهدة المتواصلة.

التكامل

AccountProfile

للسماح بتجربة مخصّصة لميزة "متابعة المشاهدة" على Google TV، يجب تقديم معلومات الحساب والملف الشخصي. استخدِم AccountProfile لتقديم ما يلي:

  1. معرّف الحساب: هو معرّف فريد يمثّل حساب المستخدِم داخل تطبيقك. يمكن أن يكون هذا هو رقم تعريف الحساب الفعلي أو نسخة معدَّلة بشكل مناسب.

  2. معرّف الملف الشخصي (اختياري): إذا كان تطبيقك يتيح استخدام ملفات شخصية متعدّدة ضمن حساب واحد، قدِّم معرّفًا فريدًا لملف المستخدم الشخصي المحدّد (مرة أخرى، يجب أن يكون المعرّف حقيقيًا أو مشوّهًا).

// If your app only supports account
val accountProfile = AccountProfile.Builder()
    .setAccountId("your_users_account_id")
    .build()

// If your app supports both account and profile
val accountProfile = AccountProfile.Builder()
    .setAccountId("your_users_account_id")
    .setProfileId("your_users_profile_id")
    .build()

إنشاء كيانات

حدّدت حزمة تطوير البرامج (SDK) عناصر مختلفة لتمثيل كل نوع من أنواع العناصر. تتيح مجموعة استمرار المحادثة الكيانات التالية:

  1. MovieEntity
  2. TvEpisodeEntity
  3. LiveStreamingVideoEntity
  4. VideoClipEntity

حدِّد معرّفات الموارد الموحّدة الخاصة بالمنصة وصور الملصقات لهذه الكيانات.

عليك أيضًا إنشاء معرّفات URI للتشغيل لكل نظام أساسي، مثل Android TV أو Android أو iOS، إذا لم يسبق لك ذلك. وبالتالي، عندما يواصل المستخدم مشاهدة المحتوى على كل منصة، يستخدم التطبيق معرّف موارد منتظم (URI) مستهدفًا لتشغيل محتوى الفيديو.

// Required. Set this when you want continue watching entities to show up on
// Google TV
val playbackUriTv = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_TV)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
    .build()

// Required. Set this when you want continue watching entities to show up on
// Google TV Android app, Entertainment Space, Playstore Widget
val playbackUriAndroid = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
    .build()

// Optional. Set this when you want continue watching entities to show up on
// Google TV iOS app
val playbackUriIos = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_IOS)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
    .build()

val platformSpecificPlaybackUris =
    Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)

تتطلّب صور الملصقات معرّف موارد موحّد وأبعادًا بالبكسل (الارتفاع والعرض). استهدِف عوامل شكل مختلفة من خلال تقديم عدة صور ملصقات، ولكن تأكَّد من أنّ جميع الصور تحافظ على نسبة عرض إلى ارتفاع تبلغ 16:9 وارتفاع يبلغ 200 بكسل على الأقل لعرض كيان "مواصلة المشاهدة" بشكل صحيح، خاصةً في Entertainment Space من Google. قد لا يتم عرض الصور التي يقل ارتفاعها عن 200 بكسل.

val images = Arrays.asList(
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image1.png"))
        .setImageHeightInPixel(300)
        .setImageWidthInPixel(169)
        .build(),
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image2.png"))
        .setImageHeightInPixel(640)
        .setImageWidthInPixel(360)
        .build()
    // Consider adding other images for different form factors
)
MovieEntity

يوضّح هذا المثال كيفية إنشاء MovieEntity مع جميع الحقول المطلوبة:

val movieEntity = MovieEntity.Builder()
   .setWatchNextType(WatchNextType.TYPE_CONTINUE)
   .setName("Movie name")
   .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
   .addPosterImages(images)
   // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
   .setLastEngagementTimeMillis(1701388800000)
   // Suppose the duration is 2 hours, it is 72000000 in milliseconds
   .setDurationMills(72000000)
   // Suppose last playback offset is 1 hour, 36000000 in milliseconds
   .setLastPlayBackPositionTimeMillis(36000000)
   .build()

من خلال تقديم تفاصيل مثل الأنواع وتقييمات المحتوى، يصبح بإمكان Google TV عرض المحتوى الخاص بك بطرق أكثر ديناميكية وربطه بالمشاهدين المناسبين.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val movieEntity = MovieEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .build()

تبقى الكيانات متاحة تلقائيًا لمدة 60 يومًا ما لم تحدّد وقت انتهاء صلاحية أقصر. لا تضبط مدة انتهاء صلاحية مخصّصة إلا إذا كنت بحاجة إلى إزالة العنصر قبل هذه المدة التلقائية.

// Set the expiration time to be now plus 30 days in milliseconds
val expirationTime = DisplayTimeWindow.Builder()
    .setEndTimestampMillis(now().toMillis()+2592000000).build()
val movieEntity = MovieEntity.Builder()
    ...
    .addAvailabilityTimeWindow(expirationTime)
    .build()
TvEpisodeEntity

يوضّح هذا المثال كيفية إنشاء TvEpisodeEntity مع جميع الحقول المطلوبة:

val tvEpisodeEntity = TvEpisodeEntity.Builder()
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Episode name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) // 2 hours in milliseconds
    // 45 minutes and 15 seconds in milliseconds is 2715000
    .setLastPlayBackPositionTimeMillis(2715000)
    .setEpisodeNumber("2")
    .setSeasonNumber("1")
    .setShowTitle("Title of the show")
    .build()

سيتم توسيع سلسلة رقم الحلقة (مثل "2") وسلسلة رقم الموسم (مثل "1") إلى الشكل المناسب قبل عرضها على بطاقة "متابعة المشاهدة". يجب أن تكون سلسلة رقمية، ولا تضع "e2" أو "الحلقة 2" أو "s1" أو "الموسم 1".

إذا كان برنامج تلفزيوني معيّن يتضمّن موسمًا واحدًا، اضبط رقم الموسم على 1.

لزيادة فرص عثور المشاهدين على المحتوى الخاص بك على Google TV، ننصحك بتقديم بيانات إضافية، مثل الأنواع وتقييمات المحتوى وفترات التوفّر، لأنّ هذه التفاصيل يمكن أن تحسّن خيارات العرض والفلترة.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val tvEpisodeEntity = TvEpisodeEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .setSeasonTitle("Season Title")
    .setShowTitle("Show Title")
    .build()
VideoClipEntity

في ما يلي مثال على إنشاء VideoClipEntity مع جميع الحقول المطلوبة.

يمثّل VideoClipEntity مقطعًا من إنشاء المستخدمين، مثل فيديو على YouTube.

val videoClipEntity = VideoClipEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Video clip name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(600000) //10 minutes in milliseconds
    .setLastPlayBackPositionTimeMillis(300000) //5 minutes in milliseconds
    .addContentRating(contentRating)
    .build()

يمكنك اختياريًا ضبط معلومات المنشئ أو صورة المنشئ أو وقت الإنشاء بالملّي ثانية أو فترة التوفّر .

LiveStreamingVideoEntity

في ما يلي مثال على إنشاء LiveStreamingVideoEntity مع جميع الحقول المطلوبة.

val liveStreamingVideoEntity = LiveStreamingVideoEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Live streaming name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) //2 hours in milliseconds
    .setLastPlayBackPositionTimeMillis(36000000) //1 hour in milliseconds
    .addContentRating(contentRating)
    .build()

يمكنك اختياريًا ضبط وقت البدء أو المذيع أو رمز المذيع أو فترة التوفّر لكيان البث المباشر.

للحصول على معلومات تفصيلية حول السمات والمتطلبات، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.

توفير بيانات مجموعة استمرار

تتحمّل AppEngagePublishClient مسؤولية نشر مجموعة "المتابعة". يمكنك استخدام الطريقة publishContinuationCluster() لنشر الكائن ContinuationCluster.

عليك أولاً استخدام isServiceAvailable() للتحقّق مما إذا كانت الخدمة متاحة للتكامل.

client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .addEntity(movieEntity1)
                .addEntity(movieEntity2)
                .addEntity(tvEpisodeEntity1)
                .addEntity(tvEpisodeEntity2)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

عندما تتلقّى الخدمة الطلب، يتم تنفيذ الإجراءات التالية ضمن معاملة واحدة:

  • تتم إزالة بيانات ContinuationCluster الحالية من حساب المطوّر الشريك.
  • يتم تحليل البيانات الواردة من الطلب وتخزينها في ContinuationCluster المعدَّل.

في حال حدوث خطأ، يتم رفض الطلب بأكمله ويتم الحفاظ على الحالة الحالية.

واجهات برمجة التطبيقات الخاصة بالنشر هي واجهات برمجة تطبيقات لإجراء عمليات إدراج وتعديل، وهي تستبدل المحتوى الحالي. إذا كنت بحاجة إلى تعديل كيان معيّن في ContinuationCluster، عليك إعادة نشر جميع الكيانات.

يجب تقديم بيانات ContinuationCluster لحسابات البالغين فقط. يتم النشر فقط عندما يكون AccountProfile تابعًا لشخص بالغ.

المزامنة على جميع الأجهزة

يتحكّم العلامة SyncAcrossDevices في ما إذا كانت بيانات ContinuationCluster الخاصة بالمستخدم تتم مزامنتها على جميع الأجهزة، مثل التلفزيون والهاتف والأجهزة اللوحية وما إلى ذلك. تكون المزامنة على جميع الأجهزة غير مفعّلة تلقائيًا.

القيم:

  • true: تتم مشاركة بيانات ContinuationCluster على جميع أجهزة المستخدم لتوفير تجربة مشاهدة سلسة. ننصحك بشدة باستخدام هذا الخيار للحصول على أفضل تجربة على جميع الأجهزة.
  • false: تقتصر بيانات ContinuationCluster على الجهاز الحالي.

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

// Example to allow cross device syncing.
client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

للاستفادة إلى أقصى حدّ من ميزة "استخدام أكثر من جهاز واحد"، تأكَّد من أنّ التطبيق يحصل على موافقة المستخدم وفعِّل SyncAcrossDevices إلى true. يتيح ذلك مزامنة المحتوى بسلاسة على جميع الأجهزة، ما يؤدي إلى تحسين تجربة المستخدم وزيادة التفاعل. على سبيل المثال، لاحظ أحد الشركاء الذين نفّذوا هذه الميزة زيادة بنسبة ‏40% في عدد النقرات على "متابعة المشاهدة" لأنّ المحتوى الخاص به ظهر على أجهزة متعددة.

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

لحذف بيانات المستخدم يدويًا من خادم Google TV قبل انتهاء فترة الاحتفاظ بالبيانات العادية البالغة 60 يومًا، استخدِم طريقة client.deleteClusters(). عند تلقّي الطلب، ستحذف الخدمة جميع بيانات العثور على الفيديوهات الحالية الخاصة بملف الحساب أو الحساب بأكمله.

يحدّد التعداد DeleteReason سبب حذف البيانات. يزيل الرمز التالي بيانات "مواصلة المشاهدة" عند تسجيل الخروج.


// If the user logs out from your media app, you must make the following call
// to remove continue watching data from the current google TV device,
// otherwise, the continue watching data will persist on the current
// google TV device until 60 days later.
client.deleteClusters(
    DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

الاختبار

استخدِم تطبيق التحقّق للتأكّد من أنّ عملية دمج حزمة تطوير البرامج Engage SDK تعمل بشكلٍ صحيح. يوفر هذا التطبيق على Android أدوات لمساعدتك في التحقّق من بياناتك والتأكّد من معالجة أغراض البث بشكل صحيح.

بعد استدعاء واجهة برمجة التطبيقات Publish API، تأكَّد من نشر بياناتك بشكل صحيح من خلال التحقّق من تطبيق التحقّق. من المفترض أن تظهر مجموعة استمراريتك كصف منفصل ضمن واجهة التطبيق.

  • اضبط علامة خدمة التفاعل على الإصدارات غير الإنتاجية فقط في ملف بيان Android الخاص بتطبيقك.
  • تثبيت تطبيق Engage Verify وفتحه
  • إذا كانت قيمة isServiceAvailable هي false، انقر على الزرّ "تبديل" للتفعيل.
  • أدخِل اسم حزمة تطبيقك لعرض البيانات المنشورة تلقائيًا بعد بدء النشر.
  • اختبِر الإجراءات التالية في تطبيقك:
    • سجِّل الدخول.
    • التبديل بين الملفات الشخصية(إذا كان ذلك منطبقًا)
    • بدء فيديو ثم إيقافه مؤقتًا أو الرجوع إلى الصفحة الرئيسية
    • أغلِق التطبيق أثناء تشغيل الفيديو.
    • إزالة فيلم أو برنامج تلفزيوني من صف "مواصلة المشاهدة" (في حال توفُّر هذه الميزة)
  • بعد كل إجراء، تأكَّد من أنّ تطبيقك قد استدعى واجهة برمجة التطبيقات publishContinuationClusters ومن عرض البيانات بشكل صحيح في تطبيق التحقّق.

  • سيعرض تطبيق التحقّق علامة صح خضراء "كل شيء على ما يرام" للكيانات التي تم تنفيذها بشكل صحيح.

    لقطة شاشة تبيّن نجاح عملية إثبات الملكية باستخدام التطبيق
    الشكل 1. نجاح عملية التحقّق من التطبيق

  • سيضع تطبيق التحقّق علامة على أي كيانات تتضمّن مشاكل.

    لقطة شاشة لخطأ في تطبيق التحقّق
    الشكل 2. خطأ في تطبيق التحقّق

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

    تفاصيل خطأ تطبيق التحقّق
    الشكل 3. تفاصيل خطأ تطبيق التحقّق

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

نشر مجموعة استمرار

لنشر بيانات "اكتشاف الفيديوهات"، أرسِل طلب 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. هذا الحقل إلزامي.

نص الطلب

الحقل

النوع

مطلوبة

الوصف

الكيانات

قائمة بكائنات MediaEntity

نعم

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

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

الحقل

النوع

مطلوبة

الوصف

movieEntity

MovieEntity

نعم

كائن يمثّل فيلمًا ضمن ContinuationCluster.

tvEpisodeEntity

TvEpisodeEntity

نعم

كائن يمثّل حلقة تلفزيونية ضمن ContinuationCluster

يجب أن يكون كل كائن في مصفوفة الكيانات أحد أنواع 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 لإزالة بيانات "الفيديوهات أثناء التصفّح".

استخدِم عنوان URL الخاص بطلبات POST لإزالة الكيانات من بيانات العثور على الفيديوهات. لحذف بيانات مجموعة استمرار المحادثة، أرسِل طلب 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.

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