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

يمكنك زيادة التفاعل مع تطبيقك من خلال الوصول إلى المستخدمين أينما كانوا. يمكنك دمج حزمة Engage SDK لتقديم محتوى "مواصلة المشاهدة" والاقتراحات المخصّصة مباشرةً للمستخدمين على مساحات عرض متعددة على الجهاز فقط، مثل المجموعات ومساحة الترفيه و"متجر Google Play". تضيف عملية الدمج أقل من 50 كيلوبايت (مضغوطة) إلى متوسط حجم حزمة APK، وتستغرق معظم التطبيقات حوالي أسبوع من وقت المطوّر. يمكنك الاطّلاع على مزيد من المعلومات في موقعنا الإلكتروني المخصّص للأنشطة التجارية.

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

الفئات ومساحات العرض المتوافقة

تستند أهلية مساحة عرض حزمة Engage SDK إلى فئة محتوى تطبيقك. استخدِم الجدول التالي لتحديد أهليتك للظهور على مساحات عرض معيّنة:

الحالة فئة المحتوى أو حالة الاستخدام مساحات العرض المتوافقة
متاحة
(مؤهَّلة على جميع مساحات العرض)
  • بث أفلام وبرامج تلفزيونية
  • بث تلفزيوني مباشر / رياضة
  • مقاطع فيديو عند الطلب
  • الفيديوهات الرياضية
  • مسلسلات درامية بحلقات قصيرة
  • بودكاست فيديو
  • المجموعات
  • مساحة الترفيه
  • علامة التبويب "التطبيقات" في "متجر Google Play"
  • علامة التبويب "أنت" في "متجر Google Play"
  • صفحة بطاقة بيانات المتجر في "متجر Google Play"
مسموح بها جزئيًا
(مؤهّلة للعرض على بعض مساحات العرض)
  • مقاطع فيديو من تطبيقات الأخبار
  • المجموعات
  • مساحة الترفيه
غير متاح
  • وحدات التحكّم عن بُعد
  • تطبيقات تنزيل الفيديوهات وتشغيلها وتعديلها
  • مراجعات الأفلام والبرامج التلفزيونية
  • تذاكر الأفلام
  • أدلة البرامج التلفزيونية
  • مكالمات الفيديو وغرف المحادثة

تفاصيل عملية الدمج

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

المصطلحات

يتضمّن هذا الدمج أنواع المجموعات الثلاثة التالية: اقتراح ومتابعة ومميّز.

  • تعرض مجموعات الاقتراحات اقتراحات مخصّصة للمحتوى الذي يمكن مشاهدته من شريك مطوّر فردي.

    تتّبع الاقتراحات البنية التالية:

    • مجموعة الاقتراحات: هي طريقة عرض في واجهة المستخدم تحتوي على مجموعة من الاقتراحات من الشريك المطوّر نفسه.

      الشكل 1: واجهة مستخدم "مساحة الترفيه" تعرض مجموعة اقتراحات من شريك واحد
    • الكيان: عنصر يمثّل عنصرًا واحدًا في مجموعة. يمكن أن يكون الكيان فيلمًا أو برنامجًا تلفزيونيًا أو مسلسلاً تلفزيونيًا أو فيديو مباشرًا أو غير ذلك. يمكنك الاطّلاع على قسم تقديم بيانات الكيانات للحصول على قائمة بأنواع الكيانات المتوافقة.

      الشكل 2. واجهة مستخدم "مساحة الترفيه" تعرض كيانًا واحدًا ضمن مجموعة اقتراحات لشريك واحد
  • تعرض مجموعة المتابعة الفيديوهات غير المكتملة والحلقات ذات الصلة التي تم إصدارها حديثًا من عدة شركاء مطوّرين في مجموعة واحدة ضمن واجهة المستخدم. سيُسمح لكل شريك مطوّر ببث 10 كيانات كحد أقصى في مجموعة المتابعة. أظهرت الأبحاث أنّ الاقتراحات المخصّصة إلى جانب محتوى المتابعة المخصّص يحقّقان أفضل تفاعل للمستخدمين.

    الشكل 3. واجهة مستخدم في "مساحة الترفيه" تعرض مجموعة "متابعة المشاهدة" مع اقتراحات غير مكتملة من شركاء متعددين (يظهر اقتراح واحد فقط حاليًا).
  • تعرض مجموعة المحتوى المميّز مجموعة مختارة من العناصر من عدة شركاء مطوّرين في مجموعة واحدة في واجهة المستخدم. ستكون هناك مجموعة واحدة مميّزة تظهر بالقرب من أعلى واجهة المستخدم مع موضع ذي أولوية فوق جميع مجموعات الاقتراحات. سيُسمح لكل شريك مطوّر ببث ما يصل إلى 10 عناصر في مجموعة "المحتوى المميّز".

    الشكل 4. واجهة مستخدم لمساحة الترفيه تعرض مجموعة مميّزة مع اقتراحات من شركاء متعددين (يظهر اقتراح واحد فقط حاليًا).

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

الحدّ الأدنى لمستوى واجهة برمجة التطبيقات: 19

أضِف مكتبة com.google.android.engage:engage-core إلى تطبيقك:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.6.0'
}

لمزيد من المعلومات، يُرجى الاطّلاع على مستوى ظهور الحِزم في Android 11.

ملخّص

يستند التصميم إلى تنفيذ خدمة ربط.

تخضع البيانات التي يمكن للعميل نشرها للحدود التالية لأنواع المجموعات المختلفة:

نوع المجموعة حدود المجموعات الحدود القصوى للكيانات في المجموعة العنقودية
مجموعات الاقتراحات 7 على الأكثر ‫50 على الأكثر
مجموعة المتابعة ‫1 كحدّ أقصى ‫20 على الأكثر
مجموعة "المحتوى المميّز" ‫1 كحدّ أقصى ‫20 على الأكثر

الخطوة 0: نقل البيانات من عملية دمج حزمة تطوير البرامج (SDK) الحالية لـ Media Home

يوضّح هذا القسم كيفية نقل نماذج بيانات Media Home SDK الحالية وطلبات البيانات من واجهة برمجة التطبيقات إلى Engage SDK.

ربط نماذج البيانات من عملية دمج حالية

إذا كنت بصدد نقل البيانات من عملية دمج حالية مع Media Home، يوضّح الجدول التالي كيفية ربط نماذج البيانات في حِزم تطوير البرامج (SDK) الحالية بحزمة Engage SDK الجديدة:

ما يعادل دمج MediaHomeVideoContract ما يعادل دمج حزمة Engage SDK
com.google.android.mediahome.video.PreviewChannel com.google.android.engage.common.datamodel.RecommendationCluster
com.google.android.mediahome.video.PreviewChannel.Builder com.google.android.engage.common.datamodel.RecommendationCluster.Builder
com.google.android.mediahome.video.PreviewChannelHelper com.google.android.engage.video.service.AppEngageVideoClient
com.google.android.mediahome.video.PreviewProgram مُقسَّمة إلى فئات منفصلة: EventVideo وLiveStreamingVideo وMovie وTvEpisode وTvSeason وTvShow وVideoClipEntity
com.google.android.mediahome.video.PreviewProgram.Builder تنقسم إلى أدوات إنشاء في فئات منفصلة: EventVideo وLiveStreamingVideo وMovie وTvEpisode وTvSeason وTvShow وVideoClipEntity
com.google.android.mediahome.video.VideoContract لم تعُد هناك حاجة إليه.
com.google.android.mediahome.video.WatchNextProgram تم تقسيمها إلى سمات في فئات منفصلة: EventVideoEntity وLiveStreamingVideoEntity وMovieEntity وTvEpisodeEntity وTvSeasonEntity وTvShowEntity وVideoClipEntity
com.google.android.mediahome.video.WatchNextProgram.Builder تم تقسيمها إلى سمات في فئات منفصلة: EventVideoEntity وLiveStreamingVideoEntity وMovieEntity وTvEpisodeEntity وTvSeasonEntity وTvShowEntity وVideoClipEntity

مقارنة بين نشر المجموعات في حزمة Media Home SDK وحزمة Engage SDK

باستخدام حزمة Media Home SDK، تم نشر المجموعات والكيانات من خلال واجهات برمجة تطبيقات منفصلة:

// 1. Fetch existing channels
List<PreviewChannel> channels = PreviewChannelHelper.getAllChannels();

// 2. If there are no channels, publish new channels
long channelId = PreviewChannelHelper.publishChannel(builder.build());

// 3. If there are existing channels, decide whether to update channel contents
PreviewChannelHelper.updatePreviewChannel(channelId, builder.build());

// 4. Delete all programs in the channel
PreviewChannelHelper.deleteAllPreviewProgramsByChannelId(channelId);

// 5. publish new programs in the channel
PreviewChannelHelper.publishPreviewProgram(builder.build());

باستخدام حزمة Engage SDK، يتم دمج نشر المجموعات والكيانات في طلب واحد من واجهة برمجة التطبيقات. يتم نشر جميع الكيانات التي تنتمي إلى مجموعة مع هذه المجموعة:

Kotlin

RecommendationCluster.Builder()
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .setTitle("Top Picks For You")
            .build()

Java

new RecommendationCluster.Builder()
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .setTitle("Top Picks For You")
                        .build();

الخطوة 1: تقديم بيانات الجهة

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

  1. MovieEntity
  2. TvShowEntity
  3. TvSeasonEntity
  4. TvEpisodeEntity
  5. LiveStreamingVideoEntity
  6. VideoClipEntity

يوضّح الجدول التالي السمات والمتطلبات لكل نوع.

MovieEntity

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

للحصول على إرشادات، يُرجى الاطّلاع على مواصفات الصور.

معرّف الموارد المنتظم (URI) للتشغيل مطلوبة للأجهزة الجوّالة

الرابط العميق لتطبيق مقدّم الخدمة لبدء تشغيل الفيلم

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

معرّفات الموارد المنتظمة (URI) الخاصة بالتشغيل على منصة معيّنة اختياري للأجهزة الجوّالة ومطلوب لأجهزة Google TV

روابط لصفحات معيّنة في تطبيق مقدّم الخدمة خاصة بالنظام الأساسي لبدء تشغيل الفيلم

معرّف الموارد المنتظم (URI) لصفحة المعلومات اختياري

الرابط العميق لتطبيق مقدّم الخدمة لعرض تفاصيل عن الفيلم

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

تاريخ الإصدار اختياري بالمللي ثانية منذ تاريخ بدء حساب الفترة
مدى التوفّر اختياري

AVAILABLE: المحتوى متاح للمستخدم بدون أي إجراء آخر.

‫FREE_WITH_SUBSCRIPTION: يتوفّر المحتوى بعد أن يشتري المستخدم اشتراكًا.

PAID_CONTENT: يتطلّب المحتوى من المستخدم الشراء أو الاستئجار.

PURCHASED: تم شراء المحتوى أو استئجاره من قِبل المستخدم.

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

يجب تقديم هذه السمة عندما يكون العنصر في مجموعة &quot;المتابعة&quot;، ويجب أن تكون من أحد الأنواع الأربعة التالية:

CONTINUE: شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى.

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

NEXT: شاهد المستخدم حلقة كاملة أو أكثر من محتوى يتألف من حلقات، ولكن لا تزال هناك أكثر من حلقة واحدة متبقية أو حلقة واحدة بالضبط متبقية، حيث لا تكون الحلقة الأخيرة "جديدة" وتم إصدارها قبل أن يبدأ المستخدم في مشاهدة المحتوى الذي يتألف من حلقات.

WATCHLIST: اختار المستخدم صراحةً إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم ما يريد مشاهدته بعد ذلك يدويًا.

وقت آخر تفاعل مطلوب بشروط يجب تقديم هذه السمة عندما يكون المنتج في مجموعة "مواصلة". بالملي ثانية منذ بداية العصر
وقت آخر موضع تشغيل مطلوب بشروط يجب تقديم هذه السمة عندما يكون العنصر في مجموعة "المتابعة" ويكون WatchNextType هو CONTINUE. بالمللي ثانية منذ تاريخ بدء حساب الفترة

TvShowEntity

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

للحصول على إرشادات، يُرجى الاطّلاع على مواصفات الصور.

معرّف الموارد المنتظم (URI) لصفحة المعلومات مطلوبة

الرابط لصفحة معيّنة في تطبيق مقدّم الخدمة لعرض تفاصيل البرنامج التلفزيوني

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

معرّف الموارد المنتظم (URI) للتشغيل اختياري

الرابط لصفحة معيّنة في تطبيق مقدّم الخدمة لبدء تشغيل البرنامج التلفزيوني

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

معرّفات الموارد المنتظمة (URI) الخاصة بالتشغيل على منصة معيّنة اختياري للأجهزة الجوّالة ومطلوب لأجهزة Google TV

روابط لصفحات معيّنة خاصة بالنظام الأساسي تؤدي إلى تطبيق مقدّم الخدمة لبدء تشغيل البرنامج التلفزيوني

تاريخ بث الحلقة الأولى اختياري بالمللي ثانية منذ تاريخ بدء حساب الفترة
تاريخ بث الحلقة الأخيرة اختياري بالمللي ثانية منذ تاريخ بدء حساب الفترة
مدى التوفّر اختياري

AVAILABLE: المحتوى متاح للمستخدم بدون أي إجراء آخر.

‫FREE_WITH_SUBSCRIPTION: يتوفّر المحتوى بعد أن يشتري المستخدم اشتراكًا.

PAID_CONTENT: يتطلّب المحتوى من المستخدم الشراء أو الاستئجار.

PURCHASED: تم شراء المحتوى أو استئجاره من قِبل المستخدم.

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

يجب تقديم هذه السمة عندما يكون العنصر في مجموعة &quot;المتابعة&quot;، ويجب أن تكون من أحد الأنواع الأربعة التالية:

CONTINUE: شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى.

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

NEXT: شاهد المستخدم حلقة كاملة أو أكثر من محتوى يتألف من حلقات، ولكن لا تزال هناك أكثر من حلقة واحدة متبقية أو حلقة واحدة بالضبط متبقية، حيث لا تكون الحلقة الأخيرة "جديدة" وتم إصدارها قبل أن يبدأ المستخدم في مشاهدة المحتوى الذي يتألف من حلقات.

WATCHLIST: اختار المستخدم صراحةً إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم ما يريد مشاهدته بعد ذلك يدويًا.

وقت آخر تفاعل مطلوب بشروط يجب تقديم هذه السمة عندما يكون المنتج في مجموعة "مواصلة". بالملي ثانية منذ بداية العصر
وقت آخر موضع تشغيل مطلوب بشروط يجب تقديم هذه السمة عندما يكون العنصر في مجموعة "المتابعة" ويكون WatchNextType هو CONTINUE. بالمللي ثانية منذ تاريخ بدء حساب الفترة

TvSeasonEntity

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

للحصول على إرشادات، يُرجى الاطّلاع على مواصفات الصور.

معرّف الموارد المنتظم (URI) لصفحة المعلومات مطلوبة

الرابط لصفحة معيّنة في تطبيق مقدّم الخدمة لعرض تفاصيل موسم البرنامج التلفزيوني

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

معرّف الموارد المنتظم (URI) للتشغيل اختياري

الرابط لصفحة معيّنة في تطبيق مقدّم الخدمة لبدء تشغيل موسم البرنامج التلفزيوني

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

عرض رقم الموسم

اختياري

متوفّر في الإصدار 1.3.1

سلسلة
تاريخ بث الحلقة الأولى اختياري بالمللي ثانية منذ تاريخ بدء حساب الفترة
تاريخ بث الحلقة الأخيرة اختياري بالمللي ثانية منذ تاريخ بدء حساب الفترة
مدى التوفّر اختياري

AVAILABLE: المحتوى متاح للمستخدم بدون أي إجراء آخر.

‫FREE_WITH_SUBSCRIPTION: يتوفّر المحتوى بعد أن يشتري المستخدم اشتراكًا.

PAID_CONTENT: يتطلّب المحتوى من المستخدم الشراء أو الاستئجار.

PURCHASED: تم شراء المحتوى أو استئجاره من قِبل المستخدم.

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

يجب تقديم هذه السمة عندما يكون العنصر في مجموعة &quot;المتابعة&quot;، ويجب أن تكون من أحد الأنواع الأربعة التالية:

CONTINUE: شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى.

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

NEXT: شاهد المستخدم حلقة كاملة أو أكثر من محتوى يتألف من حلقات، ولكن لا تزال هناك أكثر من حلقة واحدة متبقية أو حلقة واحدة بالضبط متبقية، حيث لا تكون الحلقة الأخيرة "جديدة" وتم إصدارها قبل أن يبدأ المستخدم في مشاهدة المحتوى الذي يتألف من حلقات.

WATCHLIST: اختار المستخدم صراحةً إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم ما يريد مشاهدته بعد ذلك يدويًا.

وقت آخر تفاعل مطلوب بشروط يجب تقديم هذه السمة عندما يكون المنتج في مجموعة "مواصلة". بالملي ثانية منذ بداية العصر
وقت آخر موضع تشغيل مطلوب بشروط يجب تقديم هذه السمة عندما يكون العنصر في مجموعة "المتابعة" ويكون WatchNextType هو CONTINUE. بالمللي ثانية منذ تاريخ بدء حساب الفترة

TvEpisodeEntity

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

للحصول على إرشادات، يُرجى الاطّلاع على مواصفات الصور.

معرّف الموارد المنتظم (URI) للتشغيل مطلوبة للأجهزة الجوّالة

الرابط العميق لتطبيق مقدّم الخدمة لبدء تشغيل الحلقة

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

معرّفات الموارد المنتظمة (URI) الخاصة بالتشغيل على منصة معيّنة اختياري للأجهزة الجوّالة ومطلوب لأجهزة Google TV

روابط لصفحات معيّنة خاصة بالنظام الأساسي تؤدي إلى تطبيق مقدّم الخدمة لبدء تشغيل الحلقة

معرّف الموارد المنتظم (URI) لصفحة المعلومات اختياري

الرابط لصفحة معيّنة في تطبيق مقدّم الخدمة لعرض تفاصيل عن حلقة البرنامج التلفزيوني

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

عنوان البرنامج التلفزيوني اختياري للأجهزة الجوّالة، ومطلوب لميزة "متابعة المشاهدة" على Google TV عنوان البرنامج التلفزيوني الرئيسي للحلقة
رقم الموسم اختياري للأجهزة الجوّالة، ومطلوب لميزة "متابعة المشاهدة" على Google TV سلسلة
عرض رقم الحلقة

اختياري للأجهزة الجوّالة، ومطلوب لميزة "متابعة المشاهدة" على Google TV

متوفّر في الإصدار 1.3.1

سلسلة
تاريخ البث المباشر اختياري بالمللي ثانية منذ تاريخ بدء حساب الفترة
مدى التوفّر اختياري

AVAILABLE: المحتوى متاح للمستخدم بدون أي إجراء آخر.

‫FREE_WITH_SUBSCRIPTION: يتوفّر المحتوى بعد أن يشتري المستخدم اشتراكًا.

PAID_CONTENT: يتطلّب المحتوى من المستخدم الشراء أو الاستئجار.

PURCHASED: تم شراء المحتوى أو استئجاره من قِبل المستخدم.

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

يجب تقديم هذه السمة عندما يكون العنصر في مجموعة &quot;المتابعة&quot;، ويجب أن تكون من أحد الأنواع الأربعة التالية:

CONTINUE: شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى.

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

NEXT: شاهد المستخدم حلقة كاملة أو أكثر من محتوى يتألف من حلقات، ولكن لا تزال هناك أكثر من حلقة واحدة متبقية أو حلقة واحدة بالضبط متبقية، حيث لا تكون الحلقة الأخيرة "جديدة" وتم إصدارها قبل أن يبدأ المستخدم في مشاهدة المحتوى الذي يتألف من حلقات.

WATCHLIST: اختار المستخدم صراحةً إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم ما يريد مشاهدته بعد ذلك يدويًا.

وقت آخر تفاعل مطلوب بشروط يجب تقديم هذه السمة عندما يكون المنتج في مجموعة "مواصلة". بالملي ثانية منذ بداية العصر
وقت آخر موضع تشغيل مطلوب بشروط يجب تقديم هذه السمة عندما يكون العنصر في مجموعة "المتابعة" ويكون WatchNextType هو CONTINUE. بالمللي ثانية منذ تاريخ بدء حساب الفترة

LiveStreamingVideoEntity

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

للحصول على إرشادات، يُرجى الاطّلاع على مواصفات الصور.

معرّف الموارد المنتظم (URI) للتشغيل مطلوبة للأجهزة الجوّالة

الرابط العميق لتطبيق مقدّم الخدمة لبدء تشغيل الفيديو

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

معرّفات الموارد المنتظمة (URI) الخاصة بالتشغيل على منصة معيّنة اختياري للأجهزة الجوّالة ومطلوب لأجهزة Google TV

روابط لصفحات معيّنة خاصة بالنظام الأساسي تؤدي إلى تطبيق مقدّم الخدمة لبدء تشغيل الفيديو

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

يجب تقديم هذه السمة عندما يكون العنصر في مجموعة &quot;المتابعة&quot;، ويجب أن تكون من أحد الأنواع الأربعة التالية:

CONTINUE: شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى.

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

NEXT: شاهد المستخدم حلقة كاملة أو أكثر من محتوى يتألف من حلقات، ولكن لا تزال هناك أكثر من حلقة واحدة متبقية أو حلقة واحدة بالضبط متبقية، حيث لا تكون الحلقة الأخيرة "جديدة" وتم إصدارها قبل أن يبدأ المستخدم في مشاهدة المحتوى الذي يتألف من حلقات.

WATCHLIST: اختار المستخدم صراحةً إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم ما يريد مشاهدته بعد ذلك يدويًا.

وقت آخر تفاعل مطلوب بشروط يجب تقديم هذه السمة عندما يكون المنتج في مجموعة "مواصلة". بالملي ثانية منذ بداية العصر
وقت آخر موضع تشغيل مطلوب بشروط يجب تقديم هذه السمة عندما يكون العنصر في مجموعة "المتابعة" ويكون WatchNextType هو CONTINUE. بالمللي ثانية منذ تاريخ بدء حساب الفترة

VideoClipEntity

يمثّل العنصر VideoClipEntity كيان فيديو وارد من وسائل التواصل الاجتماعي، مثل TikTok أو YouTube.

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

للحصول على إرشادات، يُرجى الاطّلاع على مواصفات الصور.

معرّف الموارد المنتظم (URI) للتشغيل مطلوبة للأجهزة الجوّالة

الرابط العميق لتطبيق مقدّم الخدمة لبدء تشغيل الفيديو

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

معرّفات الموارد المنتظمة (URI) الخاصة بالتشغيل على منصة معيّنة اختياري للأجهزة الجوّالة ومطلوب لأجهزة Google TV

روابط لصفحات معيّنة خاصة بالنظام الأساسي تؤدي إلى تطبيق مقدّم الخدمة لبدء تشغيل الفيديو

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

يجب تقديم هذه السمة عندما يكون العنصر في مجموعة &quot;المتابعة&quot;، ويجب أن تكون من أحد الأنواع الأربعة التالية:

CONTINUE: شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى.

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

NEXT: شاهد المستخدم حلقة كاملة أو أكثر من محتوى يتألف من حلقات، ولكن لا تزال هناك أكثر من حلقة واحدة متبقية أو حلقة واحدة بالضبط متبقية، حيث لا تكون الحلقة الأخيرة "جديدة" وتم إصدارها قبل أن يبدأ المستخدم في مشاهدة المحتوى الذي يتألف من حلقات.

WATCHLIST: اختار المستخدم صراحةً إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم ما يريد مشاهدته بعد ذلك يدويًا.

وقت آخر تفاعل مطلوب بشروط يجب تقديم هذه السمة عندما يكون المنتج في مجموعة "مواصلة". بالملي ثانية منذ بداية العصر
وقت آخر موضع تشغيل مطلوب بشروط يجب تقديم هذه السمة عندما يكون العنصر في مجموعة "المتابعة" ويكون WatchNextType هو CONTINUE. بالمللي ثانية منذ تاريخ بدء حساب الفترة

مواصفات الصور

يعرض الجدول التالي المواصفات المطلوبة لمواد عرض الصور:

نسبة العرض إلى الارتفاع المجموعات المتوافقة الحدّ الأدنى لعدد وحدات البكسل وحدات البكسل المقترَحة
أفقية (16:9، 1.91x1) المحتوى المميّز والمحتوى الذي تتم متابعته والمحتوى المقترَح (يُفضَّل استخدام نسبة العرض إلى الارتفاع 16:9) ‫640x360 (16:9) / ‏600x314 (1.91x1) ‫1264x712 (16:9) / ‏1200x628 (1.91x1)
صورة عمودية (9:16) اقتراح (المجال: VideoClipEntity) ‫‎360 x 640 ‫720x1280
عمودية (4x5 و2x3) الاقتراحات والمتابعة (تم اقتصاصها في بطاقات المتابعة والاقتراحات على الهاتف) ‫480×600 (4×5) / ‏400×600 (2×3) ‫‎960x1200 (4x5) / ‎800x1200 (2x3)
مربّعة (1 × 1) الاقتراح 300 × 300 ‫1200 × 1200

تنسيقات الملفات

‫PNG أو JPG أو GIF ثابت أو WebP

الحد الأقصى لحجم الملف

‫5,120 كيلوبايت

اقتراحات إضافية

  • المنطقة الآمنة للصور: ضَع المحتوى المهم في الوسط بحيث يشغل %80 من الصورة.

مثال

Kotlin

var movie = MovieEntity.Builder()
    .setName("Avengers")
    .addPosterImage(Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
    .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
    .setReleaseDateEpochMillis(1633032895L)
    .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
    .setDurationMillis(12345678L)
    .addGenre("action")
    .addContentRating("R")
    .setWatchNextType(WatchNextType.TYPE_NEW)
    .setLastEngagementTimeMillis(1664568895L)
    .setCallToActionText("Watch Now")
    .addTag("Action")
    .build()

Java

MovieEntity movie = new MovieEntity.Builder()
                  .setName("Avengers")
                  .addPosterImage(
                      new Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
                  .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
                  .setReleaseDateEpochMillis(1633032895L)
                  .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
                  .setDurationMillis(12345678L)
                  .addGenre("action")
                  .addContentRating("R")
                  .setWatchNextType(WatchNextType.TYPE_NEW)
                  .setLastEngagementTimeMillis(1664568895L)
                  .setCallToActionText("Watch Now")
                  .addTag("Action")
                  .build();

الخطوة 2: تقديم بيانات المجموعة

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

‫AppEngagePublishClient مسؤول عن نشر المجموعات. تتوفّر واجهات برمجة التطبيقات التالية في العميل:

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishContinuationCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteContinuationCluster
  • deleteUserManagementCluster
  • deleteClusters

isServiceAvailable

تُستخدَم واجهة برمجة التطبيقات هذه للتحقّق مما إذا كانت الخدمة متاحة للدمج وما إذا كان يمكن عرض المحتوى على الجهاز.

يمكنك التحقّق من توفّر الخدمة لكل نوع مجموعة تريد نشرها. تقبل واجهة برمجة التطبيقات isServiceAvailable عنصر طلب، ServiceAvailabilityRequest، يحتوي على أنواع المجموعات التي يجب التحقّق من مدى توفّر الخدمة لها. يمكنك العثور على قيم التعداد ClusterType المطلوبة لـ ServiceAvailabilityRequest من الجدول التالي.

نوع المجموعة ثابت نوع المجموعة قيمة العدد الصحيح
غير معروف TYPE_UNKNOWN 0
مجموعة الاقتراحات TYPE_RECOMMENDATION 1
مجموعة "المحتوى المميّز" TYPE_FEATURED 2
مجموعة المتابعة TYPE_CONTINUATION 3
مجموعة إدارة المستخدمين TYPE_ENGAGEMENT 8
مجموعة الاشتراكات TYPE_SUBSCRIPTION 12

Kotlin

val request = ServiceAvailabilityRequest.Builder()
    .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
    .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
    .build()

client.isServiceAvailable(request).addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val availabilityMap = task.result
        if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
            // Proceed with publishing continuation content
        }
        if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
}

Java

ServiceAvailabilityRequest request =
    new ServiceAvailabilityRequest.Builder()
        .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
        .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
        .build();

client.isServiceAvailable(request).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        Map<Integer, Boolean> availabilityMap = task.getResult();
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
            // Proceed with publishing continuation content
        }
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
});
ميزة "توفّر الخدمة المشروط"

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

Starting with v1.6.0, the Engage SDK allows checking availability for specific cluster types. إذا كان تطبيقك يستخدم ميزة "الاستيعاب المتقطّع":

  • تظل مجموعات المتابعة (مثل "مواصلة المشاهدة") مفعَّلة تلقائيًا على جميع الأجهزة المتوافقة.
  • يتم تفعيل أنواع المجموعات الأخرى (مثل الاقتراحات) وإيقافها بشكل متقطّع.

إذا لم تكن هذه الإعدادات التلقائية مناسبة لاحتياجاتك، يُرجى التواصل مع engage-developers@google.com.

بالنسبة إلى إصدارات حزمة SDK الأقدم من 1.6.0 (متوقفة نهائيًا)

Kotlin

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

publishRecommendationClusters

تُستخدَم واجهة برمجة التطبيقات هذه لنشر قائمة بعناصر RecommendationCluster.

Kotlin

client.publishRecommendationClusters(
      PublishRecommendationClustersRequest.Builder()
        .addRecommendationCluster(
          RecommendationCluster.Builder()
            .addEntity(entity1)
            .addEntity(entity2)
            .setTitle("Top Picks For You")
            .build()
        )
        .build()
    )

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Top Picks For You")
                        .build())
                .build());

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

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

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

publishFeaturedCluster

تُستخدَم واجهة برمجة التطبيقات هذه لنشر قائمة بعناصر FeaturedCluster.

Kotlin

client.publishFeaturedCluster(
    PublishFeaturedClusterRequest.Builder()
      .setFeaturedCluster(
        FeaturedCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

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

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

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

publishContinuationCluster

تُستخدَم واجهة برمجة التطبيقات هذه لنشر عنصر ContinuationCluster.

Kotlin

client.publishContinuationCluster(
    PublishContinuationClusterRequest.Builder()
      .setContinuationCluster(
        ContinuationCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishContinuationCluster(
            new PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    new ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

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

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

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

publishUserAccountManagementRequest

تُستخدَم واجهة برمجة التطبيقات هذه لنشر بطاقة تسجيل دخول . يوجه إجراء تسجيل الدخول المستخدمين إلى صفحة تسجيل الدخول في التطبيق حتى يتمكن التطبيق من نشر المحتوى (أو تقديم محتوى أكثر تخصيصًا)

البيانات الوصفية التالية هي جزء من بطاقة تسجيل الدخول:

السمة المتطلبات الوصف
معرّف الموارد المنتظم (URI) للإجراء مطلوب رابط لصفحة معيّنة يؤدي إلى إجراء (مثل الانتقال إلى صفحة تسجيل الدخول إلى التطبيق)
صورة اختياري: يجب تقديم العنوان في حال عدم توفيره

الصورة المعروضة على البطاقة

صور بنسبة عرض إلى ارتفاع 16x9 وبدرجة دقة 1264x712

العنوان اختياري: يجب تقديم صورة في حال عدم توفير هذا الحقل العنوان على البطاقة
نص الإجراء اختياري النص الذي يظهر في عبارة الحث على اتخاذ إجراء (مثل "تسجيل الدخول")
العنوان الفرعي اختياري عنوان فرعي اختياري على البطاقة

Kotlin

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

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

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

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

updatePublishStatus

إذا لم يتم نشر أي من المجموعات لأي سبب داخلي يتعلّق بالنشاط التجاري، ننصح بشدة بتعديل حالة النشر باستخدام واجهة برمجة التطبيقات updatePublishStatus. هذا مهم لأنّ :

  • من المهم توفير الحالة في جميع السيناريوهات، حتى عندما يكون المحتوى منشورًا (STATUS == PUBLISHED)، وذلك لملء لوحات البيانات التي تستخدم هذه الحالة الصريحة لعرض حالة التكامل ومقاييس أخرى.
  • إذا لم يتم نشر أي محتوى ولكن حالة الدمج ليست معطّلة (STATUS == NOT_PUBLISHED)، يمكن لـ Google تجنُّب إرسال تنبيهات في لوحات بيانات سلامة التطبيق. ويؤكّد أنّ المحتوى لم يتم نشره بسبب حالة متوقّعة من وجهة نظر مقدّم الخدمة.
  • ويساعد المطوّرين في تقديم إحصاءات حول وقت نشر البيانات مقابل عدم نشرها.
  • قد تستخدم Google رموز الحالة لتشجيع المستخدم على تنفيذ إجراءات معيّنة في التطبيق ليتمكّن من الاطّلاع على محتوى التطبيق أو تجاوز المشكلة.

في ما يلي قائمة برموز حالة النشر المؤهَّلة :

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

إذا لم يتم نشر المحتوى بسبب عدم تسجيل المستخدم الدخول، ستنصح Google بنشر بطاقة تسجيل الدخول. إذا لم يتمكّن مقدّمو الخدمات لأي سبب من نشر "بطاقة تسجيل الدخول"، ننصح باستدعاء واجهة برمجة التطبيقات updatePublishStatus باستخدام رمز الحالة NOT_PUBLISHED_REQUIRES_SIGN_IN

Kotlin

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

deleteRecommendationsClusters

تُستخدَم واجهة برمجة التطبيقات هذه لحذف محتوى مجموعات الاقتراحات.

Kotlin

client.deleteRecommendationsClusters()

Java

client.deleteRecommendationsClusters();

عندما تتلقّى الخدمة الطلب، تزيل البيانات الحالية من مجموعات الاقتراحات. في حال حدوث خطأ، يتم رفض الطلب بالكامل ويتم الاحتفاظ بالحالة الحالية.

deleteFeaturedCluster

تُستخدَم واجهة برمجة التطبيقات هذه لحذف محتوى "المجموعة المميّزة".

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

عندما تتلقّى الخدمة الطلب، تزيل البيانات الحالية من &quot;المجموعة المميّزة&quot;. في حال حدوث خطأ، يتم رفض الطلب بالكامل ويتم الاحتفاظ بالحالة الحالية.

deleteContinuationCluster

تُستخدَم واجهة برمجة التطبيقات هذه لحذف محتوى مجموعة المتابعة.

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

عندما تتلقّى الخدمة الطلب، تزيل البيانات الحالية من &quot;مجموعة المتابعة&quot;. في حال حدوث خطأ، يتم رفض الطلب بالكامل ويتم الاحتفاظ بالحالة الحالية.

deleteUserManagementCluster

تُستخدَم واجهة برمجة التطبيقات هذه لحذف محتوى مجموعة UserAccountManagement.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

عندما تتلقّى الخدمة الطلب، تزيل البيانات الحالية من مجموعة UserAccountManagement. في حال حدوث خطأ، يتم رفض الطلب بالكامل ويتم الاحتفاظ بالحالة الحالية.

deleteClusters

تُستخدَم واجهة برمجة التطبيقات هذه لحذف محتوى نوع مجموعة معيّن.

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_CONTINUATION)
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_CONTINUATION)
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                .build());

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

معالجة الأخطاء

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

Kotlin

client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

Java

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

يتم عرض الخطأ على شكل AppEngageException مع تضمين السبب كرمز خطأ.

رمز الخطأ اسم الخطأ ملاحظة
1 SERVICE_NOT_FOUND الخدمة غير متاحة على الجهاز المحدّد.
2 SERVICE_NOT_AVAILABLE تتوفّر الخدمة على الجهاز المحدّد، ولكنّها غير متاحة في وقت المكالمة (على سبيل المثال، تم إيقافها صراحةً).
3 SERVICE_CALL_EXECUTION_FAILURE تعذّر تنفيذ المهمة بسبب مشاكل في سلاسل المحادثات. وفي هذه الحالة، يمكن إعادة المحاولة.
4 SERVICE_CALL_PERMISSION_DENIED لا يُسمح للمتصل بإجراء مكالمة الخدمة.
5 SERVICE_CALL_INVALID_ARGUMENT يحتوي الطلب على بيانات غير صالحة (على سبيل المثال، أكثر من العدد المسموح به من المجموعات).
6 SERVICE_CALL_INTERNAL حدث خطأ في الخدمة.
7 SERVICE_CALL_RESOURCE_EXHAUSTED يتم إجراء طلب الخدمة بشكل متكرر جدًا.

الخطوة 3: التعامل مع الأهداف التي يتم بثها

بالإضافة إلى إجراء طلبات بيانات من واجهة برمجة التطبيقات لنشر المحتوى من خلال مهمة، يجب أيضًا إعداد BroadcastReceiver لتلقّي طلب نشر المحتوى.

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

يجب إعداد BroadcastReceiver بالطريقتَين التاليتَين:

  • سجِّل ديناميكيًا مثيلاً من فئة BroadcastReceiver باستخدام Context.registerReceiver(). يتيح ذلك الاتصال من التطبيقات التي لا تزال نشطة في الذاكرة.

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
  // is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
  // Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
  // received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

Java

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents. ACTION_PUBLISH_RECOMMENDATION),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

}
  • يجب الإعلان بشكل ثابت عن عملية التنفيذ باستخدام علامة <receiver> في ملف AndroidManifest.xml. يسمح هذا للتطبيق بتلقي أهداف البث عندما لا يكون قيد التشغيل، ويسمح أيضًا للتطبيق بنشر المحتوى.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

يتم إرسال الطلبات التالية من خلال الخدمة:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION ننصحك ببدء مكالمة على "publishRecommendationClusters" عند تلقّي هذا الطلب.
  • com.google.android.engage.action.PUBLISH_FEATURED يُنصح ببدء مكالمة publishFeaturedCluster عند تلقّي هذا الغرض.
  • com.google.android.engage.action.PUBLISH_CONTINUATION ننصح ببدء مكالمة publishContinuationCluster عند تلقّي هذا الطلب.

سير عمل الدمج

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

الأسئلة الشائعة

يمكنك الاطّلاع على الأسئلة الشائعة حول Engage SDK لمعرفة المزيد.

معلومات الاتصال

يُرجى التواصل مع engage-developers@google.com إذا كانت لديك أي أسئلة أثناء عملية الدمج.

الخطوات التالية

بعد إكمال عملية الدمج هذه، تكون خطواتك التالية كما يلي:

  • أرسِل رسالة إلكترونية إلى engage-developers@google.com وأرفِق حزمة APK المدمجة والجاهزة للاختبار من قِبل Google.
  • تُجري Google عملية تحقّق ومراجعات داخلية للتأكّد من أنّ عملية الدمج تعمل على النحو المتوقّع. إذا كانت هناك حاجة إلى إجراء تغييرات، ستتواصل معك Google لإطلاعك على أي تفاصيل ضرورية.
  • عند اكتمال الاختبار وعدم الحاجة إلى إجراء أي تغييرات، ستتواصل معك Google لإعلامك بأنّه يمكنك البدء في نشر حزمة APK المحدَّثة والمتكاملة على "متجر Play".
  • بعد أن تؤكّد Google نشر حزمة APK المعدَّلة على &quot;متجر Google Play&quot;، قد يتم نشر مجموعات الاقتراحات والمحتوى المميّز والمتابعة وإتاحتها للمستخدمين.