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

تصمم Google مساحة على الجهاز لتنظيم تطبيقات المستخدمين حسب الفئات وتقديم تجربة غامرة وجديدة تتيح لهم الاطّلاع على محتوى التطبيقات واستكشافه بطريقة مخصصة. وتوفّر تجربة ملء الشاشة هذه للشركاء المطوّرين فرصة لعرض أفضل محتوى وافٍ في قناة مخصّصة خارج التطبيق.

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

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

المصطلحات

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

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

  تأخذ توصياتك البنية التالية:

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

    

    الشكل 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.4.0'
}

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

ملخّص

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

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

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

ملاحظة مهمة: حلّت حزمة تطوير البرامج (SDK) لـ Engage SDK محل صفحة الوسائط الرئيسية التي تم إيقافها نهائيًا الآن. إذا كان لديك دمج حالي لصفحة Media Home، اتّبِع التعليمات الواردة في الخطوة 0 لنقل المحتوى إلى حزمة تطوير البرامج Engage SDK، ما يسمح بنشر المحتوى على المزيد من الأجهزة وأشكال الأجهزة. يمكنك التواصل معنا على [e-mail]. وفي حال عدم توفر عملية دمج حالية للصفحة الرئيسية للوسائط، يمكنك التخطّي إلى الخطوة 1.

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

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

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

مكافئ دمج MediaHomeVideoContract	مكافئ دمج حزمة تطوير البرامج (SDK) في Engage
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

السمة	المتطلب	Notes
الاسم	مطلوبة
صور الملصق	مطلوبة	يجب توفّر صورة واحدة على الأقل، ويجب توفيره بنسبة عرض إلى ارتفاع. (يُفضَّل استخدام الوضع الأفقي، ولكن يُنصح بتمرير الصور العمودية والأفقية في سيناريوهات مختلفة.) يمكنك الاطّلاع على مواصفات الصور للحصول على إرشادات.
تشغيل معرّف الموارد المنتظم (URI)	مطلوبة	رابط لصفحة معيّنة في تطبيق مقدّم الخدمة لبدء تشغيل الفيلم ملاحظة: يمكنك استخدام الروابط لصفحات في التطبيق من أجل تحديد المصدر. يمكنك الرجوع إلى هذه الأسئلة الشائعة.
معرّف الموارد المنتظم (URI) لصفحة المعلومات	إجراء اختياري	رابط لموضع معيّن يؤدي إلى تطبيق مقدّم الخدمة لعرض تفاصيل عن الفيلم. ملاحظة: يمكنك استخدام الروابط لصفحات في التطبيق من أجل تحديد المصدر. يمكنك الرجوع إلى هذه الأسئلة الشائعة.
تاريخ الإصدار	مطلوبة	بالمللي ثانية من الحقبة
مدى توفّر الخدمة	مطلوبة	AVAILABLE: المحتوى متاح للمستخدم بدون اتخاذ أي إجراء آخر. FREE_WITH_SUBSCRIPTION: يصبح المحتوى متاحًا بعد أن يشتري المستخدم اشتراكًا. PAID_CONTENT: يتطلّب المحتوى من المستخدم شراء المحتوى أو استئجاره. تم الشراء: تم شراء أو استئجار المحتوى من قِبل المستخدم.
سعر العرض	إجراء اختياري	حقل التعبئة النصّية الحرّة
المدة	مطلوبة	بالمللي ثانية.
النوع	مطلوبة	حقل التعبئة النصّية الحرّة
تقييمات المحتوى	مطلوبة	نص مجاني، يرجى اتباع معايير الصناعة. (مثال)
مشاهدة النوع التالي	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة، كما يجب أن يكون أحد الأنواع الأربعة التالية: متابعة: سبق أن شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى. ميزة جديدة: شاهد المستخدم جميع الحلقات المتوفرة من بعض المحتوى المقسّم إلى حلقات، ولكن أصبحت هناك حلقة جديدة متاحة وهناك حلقة واحدة لم تتم مشاهدتها. يصلح هذا الخيار للبرامج التلفزيونية ومباريات كرة القدم المسجّلة ضمن مسلسلات وما إلى ذلك. التالي: شاهد المستخدم حلقة كاملة أو أكثر من بعض المحتوى المقسّم إلى حلقات، ولكن يتبقى إما أكثر من حلقة واحدة أو حلقة واحدة فقط إذا كانت الحلقة الأخيرة غير "جديدة" وتم إطلاقها قبل أن يبدأ المستخدم مشاهدة المحتوى المقسّم إلى حلقات. قائمة المشاهدة: اختار المستخدم بشكل صريح إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم المحتوى الذي يريد مشاهدته تاليًا.
آخر مرة تفاعل	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة. بالمللي ثانية من البداية.
وقت آخر موضع تشغيل	مطلوب بشكل مشروط	يجب توفير هذه السمة عندما يكون العنصر في مجموعة Continuation (مجموعة المتابعة) ويكون WatchNextType هو "متابعة". بالمللي ثانية من الحقبة

TvShowEntity

السمة	المتطلب	Notes
الاسم	مطلوبة
صور الملصق	مطلوبة	يجب توفّر صورة واحدة على الأقل، ويجب توفيره بنسبة عرض إلى ارتفاع. (يُفضَّل استخدام الوضع الأفقي، ولكن يُنصح بتمرير الصور العمودية والأفقية في سيناريوهات مختلفة.) يمكنك الاطّلاع على مواصفات الصور للحصول على إرشادات.
معرّف الموارد المنتظم (URI) لصفحة المعلومات	مطلوبة	رابط لصفحة معيّنة في تطبيق مقدّم الخدمة لعرض تفاصيل البرنامج التلفزيوني. ملاحظة: يمكنك استخدام الروابط لصفحات في التطبيق من أجل تحديد المصدر. يمكنك الرجوع إلى هذه الأسئلة الشائعة.
تشغيل معرّف الموارد المنتظم (URI)	إجراء اختياري	هذا الرابط لصفحة معيّنة في تطبيق مقدّم الخدمة لبدء تشغيل البرنامج التلفزيوني. ملاحظة: يمكنك استخدام الروابط لصفحات في التطبيق من أجل تحديد المصدر. يمكنك الرجوع إلى هذه الأسئلة الشائعة.
تاريخ بث الحلقة الأولى	مطلوبة	بالمللي ثانية من الحقبة
آخر تاريخ بث مباشر للحلقة	إجراء اختياري	بالمللي ثانية من الحقبة
مدى توفّر الخدمة	مطلوبة	AVAILABLE: المحتوى متاح للمستخدم بدون اتخاذ أي إجراء آخر. FREE_WITH_SUBSCRIPTION: يصبح المحتوى متاحًا بعد أن يشتري المستخدم اشتراكًا. PAID_CONTENT: يتطلّب المحتوى من المستخدم شراء المحتوى أو استئجاره. تم الشراء: تم شراء أو استئجار المحتوى من قِبل المستخدم.
سعر العرض	إجراء اختياري	حقل التعبئة النصّية الحرّة
عدد المواسم	مطلوبة	عدد صحيح موجب
النوع	مطلوبة	حقل التعبئة النصّية الحرّة
تقييمات المحتوى	مطلوبة	نص مجاني، يرجى اتباع معايير الصناعة. (مثال)
مشاهدة النوع التالي	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة، كما يجب أن يكون أحد الأنواع الأربعة التالية: متابعة: سبق أن شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى. ميزة جديدة: شاهد المستخدم جميع الحلقات المتوفرة من بعض المحتوى المقسّم إلى حلقات، ولكن أصبحت هناك حلقة جديدة متاحة وهناك حلقة واحدة لم تتم مشاهدتها. يصلح هذا الخيار للبرامج التلفزيونية ومباريات كرة القدم المسجّلة ضمن مسلسلات وما إلى ذلك. التالي: شاهد المستخدم حلقة كاملة أو أكثر من بعض المحتوى المقسّم إلى حلقات، ولكن يتبقى إما أكثر من حلقة واحدة أو حلقة واحدة فقط إذا كانت الحلقة الأخيرة غير "جديدة" وتم إطلاقها قبل أن يبدأ المستخدم مشاهدة المحتوى المقسّم إلى حلقات. قائمة المشاهدة: اختار المستخدم بشكل صريح إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم المحتوى الذي يريد مشاهدته تاليًا.
آخر مرة تفاعل	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة. بالمللي ثانية من البداية.
وقت آخر موضع تشغيل	مطلوب بشكل مشروط	يجب توفير هذه السمة عندما يكون العنصر في مجموعة Continuation (مجموعة المتابعة) ويكون WatchNextType هو "متابعة". بالمللي ثانية من الحقبة

TvSeasonEntity

السمة	المتطلب	Notes
الاسم	مطلوبة
صور الملصق	مطلوبة	يجب توفّر صورة واحدة على الأقل، ويجب توفيره بنسبة عرض إلى ارتفاع. (يُفضَّل استخدام الوضع الأفقي، ولكن يُنصح بتمرير الصور العمودية والأفقية في سيناريوهات مختلفة.) يمكنك الاطّلاع على مواصفات الصور للحصول على إرشادات.
معرّف الموارد المنتظم (URI) لصفحة المعلومات	مطلوبة	رابط لصفحة معيّنة في تطبيق مقدّم الخدمة لعرض تفاصيل موسم البرنامج التلفزيوني. ملاحظة: يمكنك استخدام الروابط لصفحات في التطبيق من أجل تحديد المصدر. يمكنك الرجوع إلى هذه الأسئلة الشائعة.
تشغيل معرّف الموارد المنتظم (URI)	إجراء اختياري	رابط لموضع معيّن يؤدي إلى تطبيق مقدّم الخدمة لبدء تشغيل موسم البرنامج التلفزيوني. ملاحظة: يمكنك استخدام الروابط لصفحات في التطبيق من أجل تحديد المصدر. يمكنك الرجوع إلى هذه الأسئلة الشائعة.
رقم الموسم المعروض	اختيارية متوفّرة في الإصدار 1.3.1	سلسلة
تاريخ بث الحلقة الأولى	مطلوبة	بالمللي ثانية من الحقبة
آخر تاريخ بث مباشر للحلقة	إجراء اختياري	بالمللي ثانية من الحقبة
مدى توفّر الخدمة	مطلوبة	AVAILABLE: المحتوى متاح للمستخدم بدون اتخاذ أي إجراء آخر. FREE_WITH_SUBSCRIPTION: يصبح المحتوى متاحًا بعد أن يشتري المستخدم اشتراكًا. PAID_CONTENT: يتطلّب المحتوى من المستخدم شراء المحتوى أو استئجاره. تم الشراء: تم شراء أو استئجار المحتوى من قِبل المستخدم.
سعر العرض	إجراء اختياري	حقل التعبئة النصّية الحرّة
عدد الحلقات	مطلوبة	عدد صحيح موجب
النوع	مطلوبة	حقل التعبئة النصّية الحرّة
تقييمات المحتوى	مطلوبة	نص مجاني، يرجى اتباع معايير الصناعة. (مثال)
مشاهدة النوع التالي	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة، كما يجب أن يكون أحد الأنواع الأربعة التالية: متابعة: سبق أن شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى. ميزة جديدة: شاهد المستخدم جميع الحلقات المتوفرة من بعض المحتوى المقسّم إلى حلقات، ولكن أصبحت هناك حلقة جديدة متاحة وهناك حلقة واحدة لم تتم مشاهدتها. يصلح هذا الخيار للبرامج التلفزيونية ومباريات كرة القدم المسجّلة ضمن مسلسلات وما إلى ذلك. التالي: شاهد المستخدم حلقة كاملة أو أكثر من بعض المحتوى المقسّم إلى حلقات، ولكن يتبقى إما أكثر من حلقة واحدة أو حلقة واحدة فقط إذا كانت الحلقة الأخيرة غير "جديدة" وتم إطلاقها قبل أن يبدأ المستخدم مشاهدة المحتوى المقسّم إلى حلقات. قائمة المشاهدة: اختار المستخدم بشكل صريح إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم المحتوى الذي يريد مشاهدته تاليًا.
آخر مرة تفاعل	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة. بالمللي ثانية من البداية.
وقت آخر موضع تشغيل	مطلوب بشكل مشروط	يجب توفير هذه السمة عندما يكون العنصر في مجموعة Continuation (مجموعة المتابعة) ويكون WatchNextType هو "متابعة". بالمللي ثانية من الحقبة

TvEpisodeEntity

السمة	المتطلب	Notes
الاسم	مطلوبة
صور الملصق	مطلوبة	يجب توفّر صورة واحدة على الأقل، ويجب توفيره بنسبة عرض إلى ارتفاع. (يُفضَّل استخدام الوضع الأفقي، ولكن يُنصح بتمرير الصور العمودية والأفقية في سيناريوهات مختلفة.) يمكنك الاطّلاع على مواصفات الصور للحصول على إرشادات.
تشغيل معرّف الموارد المنتظم (URI)	مطلوبة	رابط لصفحة معيّنة في تطبيق مقدّم الخدمة لبدء تشغيل الحلقة ملاحظة: يمكنك استخدام الروابط لصفحات في التطبيق من أجل تحديد المصدر. يمكنك الرجوع إلى هذه الأسئلة الشائعة.
معرّف الموارد المنتظم (URI) لصفحة المعلومات	إجراء اختياري	رابط لصفحة معيّنة في تطبيق مقدّم الخدمة لعرض تفاصيل حول حلقة البرنامج التلفزيوني. ملاحظة: يمكنك استخدام الروابط لصفحات في التطبيق من أجل تحديد المصدر. يمكنك الرجوع إلى هذه الأسئلة الشائعة.
عرض رقم الحلقة	اختيارية متوفّرة في الإصدار 1.3.1	سلسلة
تاريخ البث المباشر	مطلوبة	بالمللي ثانية من الحقبة
مدى توفّر الخدمة	مطلوبة	AVAILABLE: المحتوى متاح للمستخدم بدون اتخاذ أي إجراء آخر. FREE_WITH_SUBSCRIPTION: يصبح المحتوى متاحًا بعد أن يشتري المستخدم اشتراكًا. PAID_CONTENT: يتطلّب المحتوى من المستخدم شراء المحتوى أو استئجاره. تم الشراء: تم شراء أو استئجار المحتوى من قِبل المستخدم.
سعر العرض	إجراء اختياري	حقل التعبئة النصّية الحرّة
المدة	مطلوبة	يجب أن تكون قيمة موجبة بالمللي ثانية.
النوع	مطلوبة	حقل التعبئة النصّية الحرّة
تقييمات المحتوى	مطلوبة	نص مجاني، يرجى اتباع معايير الصناعة. (مثال)
مشاهدة النوع التالي	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة، كما يجب أن يكون أحد الأنواع الأربعة التالية: متابعة: سبق أن شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى. ميزة جديدة: شاهد المستخدم جميع الحلقات المتوفرة من بعض المحتوى المقسّم إلى حلقات، ولكن أصبحت هناك حلقة جديدة متاحة وهناك حلقة واحدة لم تتم مشاهدتها. يصلح هذا الخيار للبرامج التلفزيونية ومباريات كرة القدم المسجّلة ضمن مسلسلات وما إلى ذلك. التالي: شاهد المستخدم حلقة كاملة أو أكثر من بعض المحتوى المقسّم إلى حلقات، ولكن يتبقى إما أكثر من حلقة واحدة أو حلقة واحدة فقط إذا كانت الحلقة الأخيرة غير "جديدة" وتم إطلاقها قبل أن يبدأ المستخدم مشاهدة المحتوى المقسّم إلى حلقات. قائمة المشاهدة: اختار المستخدم بشكل صريح إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم المحتوى الذي يريد مشاهدته تاليًا.
آخر مرة تفاعل	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة. بالمللي ثانية من البداية.
وقت آخر موضع تشغيل	مطلوب بشكل مشروط	يجب توفير هذه السمة عندما يكون العنصر في مجموعة Continuation (مجموعة المتابعة) ويكون WatchNextType هو "متابعة". بالمللي ثانية من الحقبة

LiveStreamingVideoEntity

السمة	المتطلب	Notes
الاسم	مطلوبة
صور الملصق	مطلوبة	يجب توفّر صورة واحدة على الأقل، ويجب توفيره بنسبة عرض إلى ارتفاع. (يُفضَّل استخدام الوضع الأفقي، ولكن يُنصح بتمرير الصور العمودية والأفقية في سيناريوهات مختلفة.) يمكنك الاطّلاع على مواصفات الصور للحصول على إرشادات.
تشغيل معرّف الموارد المنتظم (URI)	مطلوبة	رابط لصفحة معيّنة في تطبيق مقدّم الخدمة لبدء تشغيل الفيديو ملاحظة: يمكنك استخدام الروابط لصفحات في التطبيق من أجل تحديد المصدر. يمكنك الرجوع إلى هذه الأسئلة الشائعة.
محطة البث	مطلوبة	حقل التعبئة النصّية الحرّة
وقت البدء	إجراء اختياري	بالمللي ثانية من الحقبة
وقت الانتهاء	إجراء اختياري	بالمللي ثانية من الحقبة
عدد المشاهدات	إجراء اختياري	يجب أن يكون النص المجاني مترجَمًا.
مشاهدة النوع التالي	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة، كما يجب أن يكون أحد الأنواع الأربعة التالية: متابعة: سبق أن شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى. ميزة جديدة: شاهد المستخدم جميع الحلقات المتوفرة من بعض المحتوى المقسّم إلى حلقات، ولكن أصبحت هناك حلقة جديدة متاحة وهناك حلقة واحدة لم تتم مشاهدتها. يصلح هذا الخيار للبرامج التلفزيونية ومباريات كرة القدم المسجّلة ضمن مسلسلات وما إلى ذلك. التالي: شاهد المستخدم حلقة كاملة أو أكثر من بعض المحتوى المقسّم إلى حلقات، ولكن يتبقى إما أكثر من حلقة واحدة أو حلقة واحدة فقط إذا كانت الحلقة الأخيرة غير "جديدة" وتم إطلاقها قبل أن يبدأ المستخدم مشاهدة المحتوى المقسّم إلى حلقات. قائمة المشاهدة: اختار المستخدم بشكل صريح إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم المحتوى الذي يريد مشاهدته تاليًا.
آخر مرة تفاعل	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة. بالمللي ثانية من البداية.
وقت آخر موضع تشغيل	مطلوب بشكل مشروط	يجب توفير هذه السمة عندما يكون العنصر في مجموعة Continuation (مجموعة المتابعة) ويكون WatchNextType هو "متابعة". بالمللي ثانية من الحقبة

VideoClipEntity

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

السمة	المتطلب	Notes
الاسم	مطلوبة
صور الملصق	مطلوبة	يجب توفّر صورة واحدة على الأقل، ويجب توفيره بنسبة عرض إلى ارتفاع. (يُفضَّل استخدام الوضع الأفقي، ولكن يُنصح بتمرير الصور العمودية والأفقية في سيناريوهات مختلفة.) يمكنك الاطّلاع على مواصفات الصور للحصول على إرشادات.
تشغيل معرّف الموارد المنتظم (URI)	مطلوبة	رابط لصفحة معيّنة في تطبيق مقدّم الخدمة لبدء تشغيل الفيديو ملاحظة: يمكنك استخدام الروابط لصفحات في التطبيق من أجل تحديد المصدر. يمكنك الرجوع إلى هذه الأسئلة الشائعة.
تاريخ الإنشاء	مطلوبة	بالمللي ثانية من الحقبة
المدة	مطلوبة	يجب أن تكون قيمة موجبة بالمللي ثانية.
صانع المحتوى	مطلوبة	حقل التعبئة النصّية الحرّة
صورة صانع المحتوى	إجراء اختياري	صورة الصورة الرمزية لصانع المحتوى
عدد المشاهدات	إجراء اختياري	يجب أن يكون النص المجاني مترجَمًا.
مشاهدة النوع التالي	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة، كما يجب أن يكون أحد الأنواع الأربعة التالية: متابعة: سبق أن شاهد المستخدم أكثر من دقيقة واحدة من هذا المحتوى. ميزة جديدة: شاهد المستخدم جميع الحلقات المتوفرة من بعض المحتوى المقسّم إلى حلقات، ولكن أصبحت هناك حلقة جديدة متاحة وهناك حلقة واحدة لم تتم مشاهدتها. يصلح هذا الخيار للبرامج التلفزيونية ومباريات كرة القدم المسجّلة ضمن مسلسلات وما إلى ذلك. التالي: شاهد المستخدم حلقة كاملة أو أكثر من بعض المحتوى المقسّم إلى حلقات، ولكن يتبقى إما أكثر من حلقة واحدة أو حلقة واحدة فقط إذا كانت الحلقة الأخيرة غير "جديدة" وتم إطلاقها قبل أن يبدأ المستخدم مشاهدة المحتوى المقسّم إلى حلقات. قائمة المشاهدة: اختار المستخدم بشكل صريح إضافة فيلم أو حدث أو مسلسل إلى قائمة المشاهدة لتنظيم المحتوى الذي يريد مشاهدته تاليًا.
آخر مرة تفاعل	مطلوب بشكل مشروط	يجب توفيره عندما يكون العنصر في مجموعة المتابعة. بالمللي ثانية من البداية.
وقت آخر موضع تشغيل	مطلوب بشكل مشروط	يجب توفير هذه السمة عندما يكون العنصر في مجموعة Continuation (مجموعة المتابعة) ويكون WatchNextType هو "متابعة". بالمللي ثانية من الحقبة

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

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

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

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

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

5120 كيلوبايت

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

• المساحة الآمنة للصور: ضَع المحتوى المهم في الوسط بحيث يشغل 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)
    .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)
                  .build();

الخطوة 2: توفير بيانات المجموعة

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

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

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

isServiceAvailable

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

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.
    }
});

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

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 PublishFeaturedClustersRequest.Builder()
                .addFeaturedCluster(
                    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

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

تشكّل البيانات الوصفية التالية جزءًا من بطاقة تسجيل الدخول -

السمة	المتطلب	الوصف
يوري أدنيش	عنصر مطلوب	رابط لموضع معيّن يؤدي إلى إجراء (أي الانتقال إلى صفحة تسجيل الدخول إلى التطبيق)
صورة	اختياري: يجب تقديم العنوان في حال عدم تقديمه.	الصورة التي تظهر على البطاقة صور بنسبة عرض إلى ارتفاع تبلغ 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 == 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());

deleteRecommendationClusters

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

ملاحظة مهمة: يجب طلب حذف واجهات برمجة التطبيقات فقط في حال عدم توفّر محتوى لنشره. لا تطلب حذف واجهات برمجة التطبيقات وتنشرها لاحقًا لاستبدال المحتوى، لأنّ واجهات برمجة التطبيقات الخاصة بالنشر تُجري ذلك بطبيعتها. يُرجى التواصل مع partner-developers@ قبل استخدام واجهات برمجة التطبيقات المحذوفة.

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

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

ملاحظة: تتوفر واجهة برمجة التطبيقات هذه بدءًا من الإصدار 1.1.0 والإصدارات الأحدث.

deleteFeaturedCluster

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

ملاحظة مهمة: يجب طلب حذف واجهات برمجة التطبيقات فقط في حال عدم توفّر محتوى لنشره. لا تطلب حذف واجهات برمجة التطبيقات وتنشرها لاحقًا لاستبدال المحتوى، لأنّ واجهات برمجة التطبيقات الخاصة بالنشر تُجري ذلك بطبيعتها. يُرجى التواصل مع partner-developers@ قبل استخدام واجهات برمجة التطبيقات المحذوفة.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

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

ملاحظة: تتوفر واجهة برمجة التطبيقات هذه بدءًا من الإصدار 1.1.0 والإصدارات الأحدث.

deleteContinuationCluster

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

ملاحظة مهمة: يجب طلب حذف واجهات برمجة التطبيقات فقط في حال عدم توفّر محتوى لنشره. لا تطلب حذف واجهات برمجة التطبيقات وتنشرها لاحقًا لاستبدال المحتوى، لأنّ واجهات برمجة التطبيقات الخاصة بالنشر تُجري ذلك بطبيعتها. يُرجى التواصل مع partner-developers@ قبل استخدام واجهات برمجة التطبيقات المحذوفة.

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

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

ملاحظة: تتوفر واجهة برمجة التطبيقات هذه بدءًا من الإصدار 1.1.0 والإصدارات الأحدث.

deleteUserManagementCluster

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

ملاحظة مهمة: يجب طلب حذف واجهات برمجة التطبيقات فقط في حال عدم توفّر محتوى لنشره. لا تطلب حذف واجهات برمجة التطبيقات وتنشرها لاحقًا لاستبدال المحتوى، لأنّ واجهات برمجة التطبيقات الخاصة بالنشر تُجري ذلك بطبيعتها. يُرجى التواصل مع partner-developers@ قبل استخدام واجهات برمجة التطبيقات المحذوفة.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

ملاحظة: تتوفر واجهة برمجة التطبيقات هذه بدءًا من الإصدار 1.1.0 والإصدارات الأحدث.

deleteClusters

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

ملاحظة مهمة: يجب طلب حذف واجهات برمجة التطبيقات فقط في حال عدم توفّر محتوى لنشره. لا تطلب حذف واجهات برمجة التطبيقات وتنشرها لاحقًا لاستبدال المحتوى، لأنّ واجهات برمجة التطبيقات الخاصة بالنشر تُجري ذلك بطبيعتها. يُرجى التواصل مع partner-developers@ قبل استخدام واجهات برمجة التطبيقات المحذوفة.

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 مع تضمين السبب كرمز خطأ.

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

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

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

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

يجب إعداد 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))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION))
}

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));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}

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

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      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 عند تلقّي هذا الهدف.

سير عمل عملية الدمج

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

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

اطّلِع على الأسئلة الشائعة حول التفاعل مع حزمة تطوير البرامج (SDK) للحصول على الأسئلة الشائعة.

Contact

يُرجى التواصل معنا على [e-mail] إذا كانت لديك أي أسئلة خلال عملية الدمج.

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

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

• أرسل رسالة إلكترونية إلى [e-mail] وإرفاق حزمة APK المدمجة والجاهزة للاختبار من Google.
• تُجري Google عملية تحقق وتراجعها داخليًا للتأكد من أنّ عملية الدمج تعمل على النحو المتوقّع. وفي حال الحاجة إلى إجراء أي تغييرات، سيتواصل معك فريق Google لإطلاعك على أي تفاصيل ضرورية.
• عند اكتمال الاختبار وعدم الحاجة إلى إجراء أي تغييرات، تتواصل معك Google لإبلاغك بأنّه يمكنك بدء نشر حِزمة APK المعدّلة والمدمجة على متجر Play.
• بعد أن تؤكّد Google نشر حزمة APK المُحدّثة على "متجر Play"، قد يتم نشر مجموعات الاقتراحات والمميزة والمتابعة وجعلها مرئية للمستخدمين.