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

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

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

يحتوي هذا الدليل على تعليمات للشركاء المطوّرين حول كيفية تقديم محتوى التسوّق إلى مساحات عرض المحتوى في Engage.

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

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

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

مهارات Android

العرض على GitHub

دمج حزمة Engage SDK

استخدِم مهارة Android في حزمة Engage SDK لدمج حزمة SDK وتصحيح الأخطاء وحلّ مشاكل التنفيذ.

لتثبيت المهارة من Android CLI، شغِّل:

android skills add engage-sdk-integration

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

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

المصطلحات

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

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

تتّبع الاقتراحات البنية التالية:
- مجموعة الاقتراحات: هي طريقة عرض في واجهة المستخدم تحتوي على مجموعة من الاقتراحات من الشريك المطوّر نفسه.
- ‫ShoppingEntity: يمثّل هذا العنصر سلعة واحدة في مجموعة.
تعرض مجموعة المحتوى المميّز مجموعة مختارة من العناصر من عدة شركاء مطوّرين في مجموعة واحدة في واجهة المستخدم. ستكون هناك مجموعة واحدة مميّزة تظهر بالقرب من أعلى واجهة المستخدم مع موضع ذي أولوية فوق جميع مجموعات الاقتراحات. سيُسمح لكل شريك مطوّر ببث ما يصل إلى 10 عناصر في مجموعة "المحتوى المميّز".
تعرض مجموعة سلّة التسوّق نظرة سريعة على سلّات التسوّق من العديد من الشركاء المطوّرين في مجموعة واحدة ضمن واجهة المستخدم، ما يشجّع المستخدمين على إكمال سلّاتهم غير المكتملة. تتوفّر مجموعة واحدة من "سلّة التسوّق" تظهر بالقرب من أعلى واجهة المستخدم، مع موضع ذي أولوية فوق جميع مجموعات الاقتراحات. يُسمح لكل شريك مطوّر ببث ما يصل إلى 3 مثيلات ShoppingCart في مجموعة "سلّة التسوّق".

تتّبع سلة التسوّق البنية التالية:
- مجموعة سلة التسوّق: هي طريقة عرض في واجهة المستخدم تحتوي على مجموعة من معاينات سلة التسوّق من العديد من الشركاء المطوّرين.
- ShoppingCart: عنصر يمثّل معاينة سلة التسوّق لشريك مطوّر واحد، ويتم عرضه في مجموعة سلة التسوّق. يجب أن يعرض ShoppingCart إجمالي عدد السلع في سلة التسوّق، وقد يتضمّن أيضًا صورًا لبعض السلع في سلة تسوّق المستخدم.
تعرض مجموعة قائمة التسوّق نظرة سريعة على قوائم التسوّق من عدة شركاء مطوّرين في مجموعة واحدة ضمن واجهة المستخدم، ما يشجّع المستخدمين على العودة إلى التطبيق المعني لتعديل قوائمهم وإكمالها. هناك مجموعة واحدة لقائمة التسوّق.
تعرض مجموعة إعادة الطلب نظرة سريعة على الطلبات السابقة من شركاء مطوّرين متعدّدين في مجموعة واحدة ضمن واجهة المستخدم، ما يشجّع المستخدمين على إعادة الطلب. هناك مجموعة واحدة من "إعادة الطلب".
- يجب أن تعرض مجموعة إعادة الطلب إجمالي عدد السلع في طلب المستخدم السابق، ويجب أن تتضمّن أيضًا أحد العناصر التالية:
  - صور لسلع عددها X في طلب المستخدم السابق
  - تصنيفات لعدد X من السلع في طلب المستخدم السابق
تعرض مجموعة تتبُّع طلبات Shopping نظرة سريعة على طلبات Shopping المعلّقة أو المكتملة مؤخرًا من العديد من الشركاء المطوّرين في مجموعة واحدة ضمن واجهة المستخدم، ما يتيح للمستخدمين تتبُّع طلباتهم.

تظهر مجموعة ShoppingOrderTracking واحدة بالقرب من أعلى واجهة المستخدم، مع موضع ذي أولوية فوق جميع مجموعات الاقتراحات. يُسمح لكل شريك مطوّر ببث عدة عناصر من ShoppingOrderTrackingEntity في مجموعة تتبُّع طلبات Shopping.
- تتّبع ShoppingOrderTrackingCluster البنية التالية:
  - مجموعة ShoppingOrderTracking: هي طريقة عرض في واجهة المستخدم تحتوي على مجموعة من معاينات تتبُّع الطلبات من العديد من الشركاء المطوّرين
  - ‫ShoppingOrderTrackingEntity: يمثّل هذا العنصر معاينة لتتبُّع طلبات التسوّق لشريك مطوّر واحد، ويتم عرضه في مجموعة تتبُّع طلبات التسوّق. يجب أن يعرض ShoppingOrderTrackingEntity حالة الطلب ووقته. ننصح بشدة بملء وقت التسليم المتوقّع لـ ShoppingOrderTrackingEntity، لأنّه يتم عرضه للمستخدمين عند توفيره.
  ملاحظة: يجب تقديم عدة عناصر ShoppingOrderTrackingEntity إذا تم تقسيم الطلب إلى عدة شحنات.

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

الحدّ الأدنى لمستوى واجهة برمجة التطبيقات: 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 `ShoppingEntity` كحدّ أقصى
مجموعة "المحتوى المميّز"	‫1 كحدّ أقصى	‫`ShoppingEntity` كحدّ أقصى
مجموعة سلة التسوّق	‫1 كحدّ أقصى	‫3 `ShoppingCart` كحدّ أقصى لا يُتوقّع استخدام سلات تسوّق متعددة إلا في التطبيقات التي تتضمّن سلات تسوّق منفصلة لكل تاجر.
مجموعة قائمة التسوّق	‫1 كحدّ أقصى	‫3 `ShoppingList` كحدّ أقصى
مجموعة إعادة الطلب في Shopping	‫1 كحدّ أقصى	‫`ReorderEntity` واحد كحدّ أقصى
مجموعة تتبُّع طلبات التسوّق	‫3 على الأكثر	‫3 `ShoppingOrderTrackingEntity` كحدّ أقصى

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

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

ShoppingEntity
ShoppingCart
ShoppingList
Reorder
ShoppingOrderTracking

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

`ShoppingEntity`

يمثّل العنصر ShoppingEntity منتجًا أو عرضًا ترويجيًا أو صفقة أو اشتراكًا أو حدثًا يريد الشركاء المطوّرون نشره.

`ShoppingEntity`

السمة	المتطلبات	الوصف	التنسيق
صور الملصقات	مطلوبة	يجب تقديم صورة واحدة على الأقل.	يُرجى الاطّلاع على مواصفات الصور للحصول على إرشادات.
معرّف الموارد المنتظم (URI) للإجراء	مطلوبة	الرابط العميق لصفحة في التطبيق تعرض تفاصيل عن الكيان ملاحظة: يمكنك استخدام الروابط العميقة لتحديد المصدر. يُرجى الرجوع إلى هذه الأسئلة الشائعة	معرّف موارد منتظم (URI)
العنوان	اختياري	اسم الكيان	حقل التعبئة النصّية الحرّة حجم النص المقترَح: أقل من 90 حرفًا (قد يظهر النص الطويل جدًا بعلامات حذف)
السعر - الحالي	مطلوب بشروط	السعر الحالي للكيان يجب تقديمها في حال تقديم السعر الأصلي المشطوب.	حقل التعبئة النصّية الحرّة
السعر - نص مشطوب	اختياري	السعر الأصلي للكيان، والذي يظهر في واجهة المستخدم ويتوسّطه خط	حقل التعبئة النصّية الحرّة
وسيلة الشرح	اختياري	وسيلة شرح لإبراز عرض ترويجي أو حدث أو تحديث للجهة، إذا كان ذلك متاحًا	حقل التعبئة النصّية الحرّة حجم النص المقترَح: أقل من 45 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
Callout fine print	اختياري	نص الأحكام لوسيلة الشرح	حقل التعبئة النصّية الحرّة حجم النص المقترَح: أقل من 45 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
التقييم (اختياري) - ملاحظة: يتم عرض جميع التقييمات باستخدام نظام التقييم بالنجوم العادي.
التقييم - الحدّ الأقصى للقيمة	اختياري	الحد الأقصى لقيمة مقياس التقييم يجب تقديم هذه السمة في حال تقديم القيمة الحالية للتقييم أيضًا.	رقم >= 0.0
التقييم - القيمة الحالية	اختياري	القيمة الحالية لمقياس التقييم يجب تقديم هذه السمة في حال تقديم القيمة القصوى للتقييم أيضًا.	رقم >= 0.0
التقييم - العدد	اختياري	عدد تقييمات الكيان ملاحظة: يجب تقديم هذا الحقل إذا كان تطبيقك يتحكّم في طريقة عرض العدد للمستخدمين. استخدِم سلسلة موجزة. على سبيل المثال، إذا كان العدد 1,000,000، ننصحك باستخدام اختصار مثل مليون واحد لكي لا يتم اقتطاع العدد على أحجام الشاشات الأصغر.	سلسلة
التقييم - قيمة العدد	اختياري	عدد تقييمات الكيان ملاحظة: يجب تقديم هذا الحقل إذا لم تكن تتعامل مع منطق اختصار العرض بنفسك. في حال توفّر كل من Count وCount Value، يتم عرض Count للمستخدمين.	الصيغة الطويلة
‫DisplayTimeWindow (اختيارية): لضبط نافذة زمنية لعرض المحتوى على مساحة العرض
الطابع الزمني للبدء	اختياري	الطابع الزمني الذي يمثّل الوقت الذي يجب بعده عرض المحتوى على مساحة العرض. وفي حال عدم ضبطها، يكون المحتوى مؤهلاً للظهور على مساحة العرض.	الطابع الزمني للحقبة بالملي ثانية
الطابع الزمني للنهاية	اختياري	الطابع الزمني الذي يشير إلى الوقت الذي لن يظهر فيه المحتوى على مساحة العرض. وفي حال عدم ضبطها، يكون المحتوى مؤهلاً للظهور على مساحة العرض.	الطابع الزمني للحقبة بالملي ثانية

`ShoppingCart`

السمة	المتطلبات	الوصف	التنسيق
معرّف الموارد المنتظم (URI) للإجراء	مطلوبة	الرابط العميق لسلة التسوّق في تطبيق الشريك ملاحظة: يمكنك استخدام الروابط العميقة لتحديد المصدر. يُرجى الرجوع إلى هذه الأسئلة الشائعة	معرّف موارد منتظم (URI)
عدد العناصر	مطلوبة	عدد السلع (وليس عدد المنتجات فقط) في سلة التسوّق على سبيل المثال: إذا كان هناك 3 قمصان متطابقة وقبعة واحدة في سلة التسوّق، يجب أن يكون هذا الرقم 4.	عدد صحيح >= 1
نص الإجراء	اختياري	نص عبارة الحث على اتخاذ إجراء للزر في سلة التسوق (على سبيل المثال، حقيبة التسوق). *إذا لم يوفّر المطوّر نصًا للإجراء، سيتم استخدام عرض سلة التسوّق* كخيار تلقائي.** تتوفّر هذه السمة في الإصدار 1.1.0 والإصدارات الأحدث.	سلسلة
العنوان	اختياري	عنوان سلة التسوّق (على سبيل المثال، حقيبة التسوّق) *إذا لم يقدّم المطوّر عنوانًا، سيتم استخدام سلّة التسوّق* كعنوان تلقائي. إذا كان الشريك المطوّر ينشر سلة تسوّق منفصلة لكل تاجر، يُرجى تضمين اسم التاجر في العنوان.**	حقل التعبئة النصّية الحرّة حجم النص المقترَح: أقل من 25 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
صور سلة التسوّق	اختياري	صور لكل منتج في سلة التسوّق يمكن تقديم ما يصل إلى 10 صور حسب الأولوية، ويعتمد عدد الصور الفعلي المعروض على شكل الجهاز.	يُرجى الاطّلاع على مواصفات الصور للحصول على إرشادات.
تصنيفات العناصر	اختياري	قائمة التصنيفات للسلع في قائمة التسوّق يعتمد العدد الفعلي للتصنيفات المعروضة على شكل الجهاز.	قائمة التصنيفات النصية المجانية حجم النص المقترَح: أقل من 20 حرفًا (قد يظهر النص الطويل جدًا على شكل علامات حذف)
الطابع الزمني لآخر تفاعل للمستخدم	اختياري	عدد الملّي ثانية المنقضية من الفترة الزمنية، والتي تحدّد آخر مرة تفاعل فيها المستخدم مع سلة التسوّق. سيتم تمرير هذه السمة كإدخال من قِبل الشركاء المطوّرين الذين ينشرون سلة تسوّق منفصلة لكل تاجر، وقد يتم استخدامها للترتيب.	الطابع الزمني للحقبة بالملي ثانية
‫DisplayTimeWindow (اختياري): لضبط فترة زمنية لعرض المحتوى على مساحة العرض
الطابع الزمني للبدء	اختياري	الطابع الزمني الذي يمثّل الوقت الذي يجب بعده عرض المحتوى على مساحة العرض. وفي حال عدم ضبطها، يكون المحتوى مؤهلاً للظهور على مساحة العرض.	الطابع الزمني للحقبة بالملي ثانية
الطابع الزمني للنهاية	اختياري	الطابع الزمني الذي يشير إلى الوقت الذي لن يظهر فيه المحتوى على مساحة العرض. وفي حال عدم ضبطها، يكون المحتوى مؤهلاً للظهور على مساحة العرض.	الطابع الزمني للحقبة بالملي ثانية

`ShoppingList`

السمة	المتطلبات	الوصف	التنسيق
معرّف الموارد المنتظم (URI) للإجراء	مطلوبة	الرابط العميق لقائمة التسوّق في تطبيق الشريك. ملاحظة: يمكنك استخدام الروابط العميقة لتحديد المصدر. يُرجى الرجوع إلى هذه الأسئلة الشائعة	معرّف موارد منتظم (URI)
عدد العناصر	مطلوبة	عدد السلع في قائمة التسوّق	عدد صحيح >= 1
العنوان	اختياري	عنوان القائمة (على سبيل المثال، قائمة البقالة) *إذا لم يقدّم المطوّر عنوانًا، سيتم استخدام قائمة التسوّق* كعنوان تلقائي.**	حقل التعبئة النصّية الحرّة حجم النص المقترَح: أقل من 25 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
تصنيفات العناصر	مطلوبة	قائمة التصنيفات للسلع في قائمة التسوّق يجب تقديم تصنيف واحد على الأقل ويمكن تقديم ما يصل إلى 10 تصنيفات حسب الأولوية، ويعتمد العدد الفعلي للتصنيفات المعروضة على شكل الجهاز.	قائمة التصنيفات النصية المجانية حجم النص المقترَح: أقل من 20 حرفًا (قد يظهر النص الطويل جدًا على شكل علامات حذف)
الطابع الزمني لآخر تفاعل للمستخدم	مطلوبة	عدد الملّي ثانية المنقضية من العصر، لتحديد آخر مرة تفاعل فيها المستخدم مع قائمة التسوّق.	الطابع الزمني للحقبة بالملي ثانية

`ShoppingReorderCluster`

السمة	المتطلبات	الوصف	التنسيق
معرّف الموارد المنتظم (URI) للإجراء	مطلوبة	الرابط العميق لإعادة الطلب في تطبيق الشريك ملاحظة: يمكنك استخدام الروابط العميقة لتحديد المصدر. يُرجى الرجوع إلى هذه الأسئلة الشائعة	معرّف موارد منتظم (URI)
نص الإجراء	اختياري	نص عبارة الحث على اتخاذ إجراء للزر في صفحة "إعادة الطلب" (على سبيل المثال، الطلب مرة أخرى). *إذا لم يوفّر المطوّر نصًا للإجراء، سيتم استخدام إعادة الطلب* كخيار تلقائي.** تتوفّر هذه السمة في الإصدار 1.1.0 والإصدارات الأحدث.	سلسلة
عدد العناصر	مطلوبة	عدد السلع (وليس عدد المنتجات فقط) في الطلب السابق على سبيل المثال: إذا كان الطلب السابق يتضمّن 3 أكواب قهوة صغيرة وكرواسون واحد، يجب أن يكون هذا الرقم 4.	عدد صحيح >= 1
العنوان	مطلوبة	عنوان السلعة التي تتم إعادة طلبها	حقل التعبئة النصّية الحرّة حجم النص المقترَح: أقل من 40 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
تصنيفات العناصر	اختياري (في حال عدم توفيرها، يجب توفير صور الملصقات)	قائمة تصنيفات العناصر للطلب السابق يمكن تقديم ما يصل إلى 10 تصنيفات حسب الأولوية، ويعتمد العدد الفعلي للتصنيفات المعروضة على شكل الجهاز.	قائمة النصوص الحرة حجم النص المقترَح لكل تصنيف: أقل من 20 حرفًا (قد يظهر النص الطويل جدًا بعلامات حذف)
صور الملصقات	اختياري (في حال عدم تقديمها، يجب تقديم تصنيفات السلع)	صور للسلع في الطلب السابق يمكن تقديم ما يصل إلى 10 صور حسب الأولوية، ويعتمد عدد الصور الفعلي المعروض على شكل الجهاز.	يُرجى الاطّلاع على مواصفات الصور للحصول على إرشادات.

`ShoppingOrderTrackingCluster`

السمة	المتطلبات	الوصف	التنسيق
العنوان	مطلوبة	عنوان قصير للطرد أو السلع التي يتم تتبّعها أو رقم التتبّع	حقل التعبئة النصّية الحرّة حجم النص المقترَح: 50 حرفًا (سيتم عرض علامات الحذف في حال كان النص طويلاً جدًا)
نوع الطلب	مطلوبة	عنوان قصير للطرد أو السلع التي يتم تتبّعها أو رقم التتبّع	قيم التعداد: IN_STORE_PICKUP وSAME_DAY_DELIVERY وMULTI_DAY_DELIVERY
الحالة	مطلوبة	الحالة الحالية للطلب على سبيل المثال: "متأخر" أو "قيد النقل" أو "متأخر" أو "تم الشحن" أو "تم التسليم" أو "غير متوفّر" أو "الطلب جاهز"	حقل التعبئة النصّية الحرّة حجم النص المقترَح: 25 حرفًا (سيظهر النص الطويل جدًا بعلامات حذف)
وقت الطلب	مطلوبة	الطابع الزمني للحقبة بالملي ثانية الذي تم فيه تقديم الطلب سيتم عرض وقت الطلب إذا لم تكن الفترة الزمنية المتوقّعة للتسليم متاحة	الطابع الزمني للحقبة بالملي ثانية
معرّف الموارد المنتظم (URI) للإجراء	مطلوبة	رابط عميق لتتبُّع الطلب في تطبيق الشريك	معرّف موارد منتظم (URI)
‫OrderDeliveryTimeWindow (اختيارية): يمكنك ضبط فترة زمنية للطلب الذي يتم تتبُّعه من وقت تقديم الطلب إلى وقت التسليم المتوقّع أو الفعلي.
OrderDeliveryTimeWindow - وقت البدء	اختياري	الطابع الزمني للحقبة بالملي ثانية الذي سيتم فيه/بعده تسليم الطلب أو تجهيزه للاستلام.	الطابع الزمني للحقبة بالملي ثانية
OrderDeliveryTimeWindow - وقت الانتهاء	اختياري	الطابع الزمني للحقبة بالملي ثانية الذي سيتم فيه/قبله تسليم الطلب أو تجهيزه للاستلام	الطابع الزمني للحقبة بالملي ثانية
صور الملصقات	اختياري	صورة لسلعة أو منتج واحد ضمن الطلب نسبة العرض إلى الارتفاع المقترَحة هي 1:1	يُرجى الاطّلاع على مواصفات الصور للحصول على إرشادات.
عدد العناصر	اختياري	عدد السلع في الطلب	عدد صحيح >= 1
الوصف	اختياري	فقرة نصية واحدة لوصف السلع في الطلب ملاحظة: سيتم عرض الوصف أو قائمة العناوين الفرعية للمستخدم، وليس كليهما.	حقل التعبئة النصّية الحرّة حجم النص المقترَح: 180 حرفًا
قائمة الترجمات	اختياري	ما يصل إلى 3 عناوين فرعية، يتألف كل منها من سطر واحد من النص ملاحظة: سيتم عرض الوصف أو قائمة العناوين الفرعية للمستخدم، وليس كليهما.	حقل التعبئة النصّية الحرّة حجم النص المقترَح لكل ترجمة: 50 حرفًا كحدّ أقصى
قيمة طلب الشراء - السعر الحالي	اختياري	تمثّل هذه السمة القيمة الحالية للطلب.	حقل التعبئة النصّية الحرّة
رقم الطلب	اختياري	رقم الطلب أو معرّفه الذي يمكن استخدامه لتحديد الطلب بشكل فريد	حقل التعبئة النصّية الحرّة حجم النص المقترَح: 25 حرفًا كحدّ أقصى
رقم التتبع	اختياري	رقم تتبُّع تسليم الطلب/الطرد في حال كان الطلب يتطلّب التسليم	حقل التعبئة النصّية الحرّة حجم النص المقترَح: 25 حرفًا كحدّ أقصى

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

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

نسبة العرض إلى الارتفاع	الحدّ الأدنى لعدد وحدات البكسل	وحدات البكسل المقترَحة
مربّعة (1 × 1) مفضَّل للمجموعات غير المميّزة	‫300 × 300	‫1200 × 1200
أفقية (1.91x1) الخيار المفضّل للمجموعات المميّزة	600 × 314	‫1200 × 628
عمودية (4x5)	‫480×600	‫960 × 1200

نسبة العرض إلى الارتفاع

الحدّ الأدنى لعدد وحدات البكسل

وحدات البكسل المقترَحة

مربّعة (1 × 1)

مفضَّل للمجموعات غير المميّزة

‫300 × 300

‫1200 × 1200

أفقية (1.91x1)

الخيار المفضّل للمجموعات المميّزة

600 × 314

‫1200 × 628

عمودية (4x5)

‫480×600

‫960 × 1200

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

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

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

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

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

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

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

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

‫"AppEngageShoppingClient" هي المسؤولة عن نشر مجموعات التسوّق.

يتم عرض واجهات برمجة التطبيقات التالية لنشر المجموعات في العميل:

isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishShoppingCarts
publishShoppingLists
publishShoppingReorderCluster
publishShoppingOrderTrackingCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteShoppingCartCluster
deleteShoppingListCluster
deleteReorderCluster
deleteShoppingOrderTrackingCluster
deleteUserManagementCluster
deleteClusters

`isServiceAvailable`

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

بالنسبة إلى الإصدار 1.6.0 من Engage SDK والإصدارات الأحدث (يُنصح به)

مهارات Android

العرض على GitHub

دمج حزمة Engage SDK

لتثبيت المهارة من Android CLI، شغِّل:

android skills add engage-sdk-integration

إذا كان فريقك يستخدم أدوات الترميز المستندة إلى الذكاء الاصطناعي (مثل Gemini في "استوديو Android")، يمكنك برمجة عملية نقل البيانات هذه من خلال توجيه طلب إلى مساعدك المستنِد إلى الذكاء الاصطناعي:

Use the engage-sdk-integration skill to use Engage SDK 1.6.0 and refactor isServiceAvailable to pass ServiceAvailabilityRequest for publishing all cluster types.

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

نوع المجموعة	ثابت نوع المجموعة	قيمة العدد الصحيح
غير معروف	`TYPE_UNKNOWN`	0
مجموعة الاقتراحات	`TYPE_RECOMMENDATION`	1
مجموعة "المحتوى المميّز"	`TYPE_FEATURED`	2
مجموعة المتابعة	`TYPE_CONTINUATION`	3
مجموعة سلة التسوّق	`TYPE_SHOPPING_CART`	4
مجموعة إدارة المستخدمين	`TYPE_ENGAGEMENT`	8
مجموعة قائمة التسوّق	`TYPE_SHOPPING_LIST`	9
مجموعة إعادة الطلب في Shopping	`TYPE_SHOPPING_REORDER`	10
مجموعة تتبُّع طلبات التسوّق	`TYPE_SHOPPING_ORDER_TRACKING`	11
مجموعة الاشتراكات	`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 وإيقافها بشكل متقطّع لتقليل تكاليف عرض الإعلانات. ومع ذلك، فإنّ استراتيجية تحليل المحتوى المتقطّعة هذه تؤثر سلبًا في تجربة المستخدم، إذ لن يتم عرض المحتوى القديم، ولن يتم عرض بعض مساحات العرض.

اعتبارًا من الإصدار 1.6.0، تتيح حزمة Engage SDK التحقّق من مدى توفّر أنواع معيّنة من المجموعات. إذا كان تطبيقك يستخدم ميزة "الاستيعاب المتقطّع":

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

إذا لم تكن هذه الإعدادات التلقائية مناسبة لاحتياجاتك، يُرجى التواصل مع 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.

يمكن أن يتضمّن عنصر RecommendationCluster السمات التالية:

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

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build());

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

تتم إزالة جميع بيانات "مجموعات الاقتراحات" الحالية.
يتم تحليل البيانات من الطلب وتخزينها في مجموعات اقتراحات جديدة.

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

`publishFeaturedCluster`

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

Kotlin

client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

Java

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

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

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

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

`publishShoppingCarts`

تُستخدَم واجهة برمجة التطبيقات هذه لنشر قائمة بعناصر ShoppingCart. ينطبق ذلك على المطوّرين الشركاء الذين ينشرون سلال تسوّق منفصلة لكل تاجر. يجب تضمين اسم التاجر في العنوان عند استخدام واجهة برمجة التطبيقات هذه.

Kotlin

client.publishShoppingCarts(
            PublishShoppingCartClustersRequest.Builder()
                .addShoppingCart(
                    ShoppingCart.Builder()
                        ...
                        .build())
                .build())

Java

client.publishShoppingCarts(
            new PublishShoppingCartClustersRequest.Builder()
                .addShoppingCart(
                    new ShoppingCart.Builder()
                        ...
                        .build())
                .build())

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

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

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

`publishShoppingLists`

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

Kotlin

client.publishShoppingLists(
            PublishShoppingListsRequest.Builder()
                .addShoppingList(
                    ShoppingList.Builder()
                        ...
                        .build())
                .build())

Java

client.publishShoppingLists(
            new PublishShoppingListsRequest.Builder()
                .addShoppingList(
                    new ShoppingList.Builder()
                        ...
                        .build())
                .build());

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

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

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

`publishShoppingReorderCluster`

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

Kotlin

client.publishShoppingReorderCluster(
            PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishShoppingReorderCluster(
            new PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    new ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build());

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

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

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

`publishShoppingOrderTrackingCluster`

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

Kotlin

client.publishShoppingOrderTrackingCluster(
            PublishShoppingOrderTrackingClusterRequest.Builder()
                .setShoppingOrderTrackingCluster(
                    ShoppingOrderTrackingCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishShoppingOrderTrackingCluster(
            new PublishShoppingOrderTrackingClusterRequest.Builder()
                .setShoppingOrderTrackingCluster(
                    new ShoppingOrderTrackingCluster.Builder()
                        ...
                        .build())
                .build());

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

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

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

`publishUserAccountManagementRequest`

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

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

السمة	المتطلبات	الوصف
معرّف الموارد المنتظم (URI) للإجراء	مطلوب	رابط لصفحة معيّنة يؤدي إلى إجراء (أي ينقل المستخدم إلى صفحة تسجيل الدخول إلى التطبيق)
صورة	اختيارية: إذا لم يتم تقديمها، يجب تقديم سمة "العنوان" (Title)	الصورة المعروضة على البطاقة صور بنسبة عرض إلى ارتفاع 16:9 وبدرجة دقة 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();

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

`deleteShoppingCartCluster`

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

Kotlin

client.deleteShoppingCartCluster()

Java

client.deleteShoppingCartCluster();

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

`deleteShoppingListCluster`

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

Kotlin

client.deleteShoppingListCluster()

Java

client.deleteShoppingListCluster();

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

`deleteReorderCluster`

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

Kotlin

client.deleteReorderCluster()

Java

client.deleteReorderCluster();

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

`deleteShoppingOrderTrackingCluster`

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

Kotlin

client.deleteShoppingOrderTrackingCluster()

Java

client.deleteShoppingOrderTrackingCluster();

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

`deleteUserManagementCluster`

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

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

`deleteClusters`

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

Kotlin

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

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast
  // is received
  // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast
  // is received
  // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
  // received
  // Trigger shopping order tracking cluster publish when
  // PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER 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 Shopping Cart Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

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

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

// Register Shopping Order Tracking Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER),
                           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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast is
// received

// Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast is
// received

// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
// received

// Trigger reorder cluster publish when PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER
// 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 Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_CART),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

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

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

// Register Shopping Order Tracking Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER),
                         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.shopping.PUBLISH_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER" />
      </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.shopping.PUBLISH_SHOPPING_CART ننصحك ببدء مكالمة publishShoppingCarts عند تلقّي هذا الطلب.
com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST ننصحك ببدء مكالمة publishShoppingLists عند تلقّي هذا الطلب.
com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER ننصحك ببدء مكالمة publishReorderCluster عند تلقّي هذا الطلب.
com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER ننصحك ببدء مكالمة publishShoppingOrderTrackingCluster عند تلقّي هذا الطلب.

سير عمل الدمج

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

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

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

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

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

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

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

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