Grow SDK Food: تعليمات الدمج الفني التابعة لجهات خارجية

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

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

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

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

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

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

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

المصطلحات

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

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

    • يمكن أن تتكوّن مجموعة الاقتراحات من بيانات ProductEntity أو StoreEntity أو RecipeEntity، ولكن لا يمكن أن تتضمّن مزيجًا من أنواع العناصر المختلفة.
    الشكل :`ProductEntity` و`StoreEntity` و `RecipeEntity`. (*واجهة المستخدم لأغراض توضيحية فقط)

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

    الشكل : مجموعة مميّزة تتضمّن `RecipeEntity`. (*واجهة المستخدم لأغراض التوضيح فقط)

  • تعرض مجموعة سلّة تسوّق الطعام نظرة سريعة على سلال تسوّق البقالة من عدة شركاء مطوّرين في مجموعة واحدة ضمن واجهة المستخدم، ما يشجّع المستخدمين على إكمال سلالهم غير المكتملة. هناك مجموعة واحدة من "عربات تسوّق الطعام".

    • يجب أن تعرض مجموعة "سلة تسوّق الطعام" إجمالي عدد السلع في السلة، وقد تتضمّن أيضًا صورًا لعدد X من السلع في سلة المستخدم.

      الشكل: مجموعة "عربة تسوّق الطعام" من شريك واحد (*واجهة المستخدم لأغراض التوضيح فقط)

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

    الشكل: مجموعة "قائمة تسوّق الطعام" من شريك واحد (*واجهة المستخدم لأغراض التوضيح فقط)

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

    • يجب أن تعرض مجموعة إعادة الطلب إجمالي عدد السلع في طلب المستخدم السابق، ويجب أن تتضمّن أيضًا أحد العناصر التالية:

      • صور لسلع عددها X في طلب المستخدم السابق
      • تصنيفات لعدد X من السلع في طلب المستخدم السابق
    الشكل: مجموعة "إعادة طلب الطعام" من شريك واحد (*واجهة المستخدم لأغراض التوضيح فقط)

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

الحدّ الأدنى لمستوى واجهة برمجة التطبيقات: 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'
}

ملخّص

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

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

نوع المجموعة حدود المجموعة العنقودية الحدود القصوى للكيانات في مجموعة عنقودية
مجموعات الاقتراحات 7 على الأكثر ‫50 على الأكثر (ProductEntity أو RecipeEntity أو StoreEntity)
مجموعة "المحتوى المميّز" ‫1 كحدّ أقصى ‫20 على الأكثر (ProductEntity أو RecipeEntity أو StoreEntity)
مجموعة سلة تسوّق الطعام ‫1 كحدّ أقصى ‫3 FoodShoppingCart كحدّ أقصى
مجموعة قوائم تسوّق الطعام ‫1 كحدّ أقصى ‫3 FoodShoppingList كحدّ أقصى
مجموعة إعادة طلب الطعام ‫1 كحدّ أقصى ‫ReorderEntity واحد كحدّ أقصى

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

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

  1. ProductEntity
  2. StoreEntity
  3. RecipeEntity
  4. FoodShoppingCart
  5. FoodShoppingList
  6. FoodReorderCluster

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

ProductEntity

يمثّل عنصر ProductEntity سلعة فردية (مثل سلعة بقالة أو طبق من مطعم أو عرض ترويجي) يريد الشركاء المطوّرون نشرها.

الشكل : سمات ProductEntity

السمة المتطلبات الوصف التنسيق
صور الملصقات مطلوبة يجب تقديم صورة واحدة على الأقل. يُرجى الاطّلاع على مواصفات الصور للحصول على إرشادات.
معرّف الموارد المنتظم (URI) للإجراء مطلوبة

الرابط العميق للصفحة في التطبيق الذي يعرض تفاصيل عن المنتج.

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

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

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

حجم النص المقترَح: أقل من 90 حرفًا (قد يظهر النص الطويل جدًا بعلامات حذف)
السعر - الحالي مطلوب بشروط

تمثّل هذه السمة السعر الحالي للمنتج.

يجب تقديمها في حال تقديم السعر الأصلي المشطوب.

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

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

حجم النص المقترَح: أقل من 45 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
Callout fine print اختياري نص الأحكام لوسيلة الشرح

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

حجم النص المقترَح: أقل من 45 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
التقييم (اختياري) - ملاحظة: يتم عرض جميع التقييمات باستخدام نظام التقييم بالنجوم العادي.
التقييم - الحدّ الأقصى للقيمة اختياري

الحد الأقصى لقيمة مقياس التقييم

يجب تقديم هذه السمة في حال تقديم القيمة الحالية للتقييم أيضًا.

 رقم >= 0.0
التقييم - القيمة الحالية اختياري

القيمة الحالية لمقياس التقييم

يجب تقديم هذه السمة في حال تقديم القيمة القصوى للتقييم أيضًا.

 رقم >= 0.0
التقييم - العدد اختياري

عدد تقييمات المنتج

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

 سلسلة
التقييم - قيمة العدد اختياري

عدد تقييمات المنتج

ملاحظة: يجب تقديم هذا الحقل إذا لم تكن تتعامل مع منطق اختصار العرض بنفسك. في حال توفّر كل من Count وCount Value، يتم عرض Count للمستخدمين.

 الصيغة الطويلة
‫DisplayTimeWindow (اختياري): لضبط فترة زمنية لعرض المحتوى على مساحة العرض
الطابع الزمني للبدء اختياري

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

وفي حال عدم ضبطها، يكون المحتوى مؤهلاً للظهور على مساحة العرض.

 الطابع الزمني للحقبة بالملي ثانية
الطابع الزمني للنهاية اختياري

الطابع الزمني الذي يشير إلى الوقت الذي لن يظهر فيه المحتوى على مساحة العرض.

وفي حال عدم ضبطها، يكون المحتوى مؤهلاً للظهور على مساحة العرض.

 الطابع الزمني للحقبة بالملي ثانية

StoreEntity

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

الشكل : سمات StoreEntity

السمة المتطلبات الوصف التنسيق
صور الملصقات مطلوبة يجب تقديم صورة واحدة على الأقل. يُرجى الاطّلاع على مواصفات الصور للحصول على إرشادات.
معرّف الموارد المنتظم (URI) للإجراء مطلوبة

الرابط العميق لصفحة في التطبيق تعرض تفاصيل عن المتجر.

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

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

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

حجم النص المقترَح: أقل من 45 حرفًا (قد يظهر النص الطويل جدًا على شكل علامات حذف)
الموقع الجغرافي اختياري الموقع الجغرافي للمتجر

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

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

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

حجم النص المقترَح: أقل من 45 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
Callout fine print اختياري نص الأحكام لوسيلة الشرح

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

حجم النص المقترَح: أقل من 45 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
الوصف اختياري وصف للمتجر

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

حجم النص المقترَح: أقل من 90 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
الفئة اختياري

فئة المتجر، وفي سياق أماكن تناول الطعام، يمكن أن تكون مأكولات مثل "فرنسية" أو "أمريكية جديدة" أو "رامن" أو "طعام فاخر".

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

حجم النص المقترَح: أقل من 45 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
ملاحظة: يتم عرض جميع التقييمات باستخدام نظام التقييم بالنجوم العادي.
التقييم - الحدّ الأقصى للقيمة اختياري

الحد الأقصى لقيمة مقياس التقييم

يجب تقديم هذه السمة في حال تقديم القيمة الحالية للتقييم أيضًا.

 رقم >= 0.0
التقييم - القيمة الحالية اختياري

القيمة الحالية لمقياس التقييم

يجب تقديم هذه السمة في حال تقديم القيمة القصوى للتقييم أيضًا.

 رقم >= 0.0
التقييم - العدد اختياري

عدد تقييمات المتجر

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

 سلسلة
التقييم - قيمة العدد اختياري

عدد تقييمات المتجر

ملاحظة: يجب تقديم هذا الحقل إذا كنت لا تريد معالجة منطق اختصار العرض بنفسك. في حال توفّر كل من Count وCount Value، سنستخدم Count لعرضها للمستخدمين.

 الصيغة الطويلة

RecipeEntity

يمثّل العنصر RecipeEntity وصفة طعام يريد الشركاء المطوّرون نشرها.

الشكل : سمات RecipeEntity

السمة المتطلبات الوصف التنسيق
صور الملصقات مطلوبة يجب تقديم صورة واحدة على الأقل. يُرجى الاطّلاع على مواصفات الصور للحصول على إرشادات.
معرّف الموارد المنتظم (URI) للإجراء مطلوبة

الرابط لصفحة التطبيق التي تعرض تفاصيل عن الوصفة

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

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

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

حجم النص المقترَح: أقل من 45 حرفًا (قد يظهر النص الطويل جدًا على شكل علامات حذف)
المؤلِّف اختياري تمثّل هذه السمة مؤلف الوصفة.

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

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

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

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

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

حجم النص المقترَح: أقل من 45 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
الفئة اختياري تمثّل هذه السمة فئة الوصفة.

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

حجم النص المقترَح: أقل من 45 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
الوصف اختياري تمثّل هذه السمة وصفًا للوصفة.

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

حجم النص المقترَح: أقل من 90 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
ملاحظة: يتم عرض جميع التقييمات باستخدام نظام التقييم بالنجوم العادي.
التقييم - الحدّ الأقصى للقيمة اختياري

الحد الأقصى لقيمة مقياس التقييم

يجب تقديم هذه السمة في حال تقديم القيمة الحالية للتقييم أيضًا.

 رقم >= 0.0
التقييم - القيمة الحالية اختياري

القيمة الحالية لمقياس التقييم

يجب تقديم هذه السمة في حال تقديم القيمة القصوى للتقييم أيضًا.

 رقم >= 0.0
التقييم - العدد اختياري

عدد تقييمات الوصفة

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

 سلسلة
التقييم - قيمة العدد اختياري

عدد تقييمات الوصفة

ملاحظة: يجب تقديم هذا الحقل إذا كنت لا تريد معالجة منطق اختصار العرض بنفسك. في حال توفّر كل من Count وCount Value، سنستخدم Count لعرضها للمستخدمين.

 الصيغة الطويلة

FoodShoppingCart

الشكل: سمات مجموعة Food Shopping Cart.

السمة المتطلبات الوصف التنسيق
معرّف الموارد المنتظم (URI) للإجراء مطلوبة

الرابط العميق لسلة التسوّق في تطبيق الشريك

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

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

عدد السلع (وليس عدد المنتجات فقط) في سلة التسوّق

على سبيل المثال: إذا كان هناك 3 برتقالات وتفاحة واحدة في سلة التسوق، يجب أن يكون هذا الرقم 4.

 عدد صحيح >= 1
الطابع الزمني لآخر تفاعل للمستخدم مطلوبة عدد الملّي ثانية المنقضية من العصر، لتحديد آخر مرة تفاعل فيها المستخدم مع سلة التسوق. الطابع الزمني للحقبة بالملي ثانية
العنوان اختياري

عنوان سلة التسوّق (مثلاً، سلة التسوّق).

إذا لم يقدّم المطوّر عنوانًا، سيتم استخدام سلّة التسوّق كعنوان تلقائي.

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

حجم النص المقترَح: أقل من 25 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
نص الإجراء اختياري

نص عبارة الحث على اتخاذ إجراء للزر في سلة التسوق (على سبيل المثال، حقيبة التسوق).

إذا لم يوفّر المطوّر نصًا للإجراء، سيتم استخدام عرض سلة التسوّق كخيار تلقائي.

تتوفّر هذه السمة في الإصدار 1.1.0 والإصدارات الأحدث.

سلسلة
صور سلة التسوّق اختياري

صور لكل منتج في سلة التسوّق

يمكن تقديم ما يصل إلى 10 صور حسب الأولوية، ويعتمد عدد الصور الفعلي المعروض على شكل الجهاز.

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

قائمة التصنيفات للسلع في قائمة التسوّق

يعتمد العدد الفعلي للتصنيفات المعروضة على شكل الجهاز.

قائمة التصنيفات النصية المجانية

حجم النص المقترَح: أقل من 20 حرفًا (قد يظهر النص الطويل جدًا على شكل علامات حذف)
‫DisplayTimeWindow (اختياري): لضبط فترة زمنية لعرض المحتوى على مساحة العرض
الطابع الزمني للبدء اختياري

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

وفي حال عدم ضبطها، يكون المحتوى مؤهلاً للظهور على مساحة العرض.

 الطابع الزمني للحقبة بالملي ثانية
الطابع الزمني للنهاية اختياري

الطابع الزمني الذي يشير إلى الوقت الذي لن يظهر فيه المحتوى على مساحة العرض.

وفي حال عدم ضبطها، يكون المحتوى مؤهلاً للظهور على مساحة العرض.

 الطابع الزمني للحقبة بالملي ثانية

FoodShoppingList

الشكل: مجموعة "قائمة تسوّق الطعام".

السمة المتطلبات الوصف التنسيق
معرّف الموارد المنتظم (URI) للإجراء مطلوبة

الرابط العميق لقائمة التسوّق في تطبيق الشريك.

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

معرّف موارد منتظم (URI)
عدد العناصر مطلوبة عدد السلع في قائمة التسوّق عدد صحيح >= 1
الطابع الزمني لآخر تفاعل للمستخدم مطلوبة عدد الملّي ثانية المنقضية من العصر، لتحديد آخر مرة تفاعل فيها المستخدم مع قائمة التسوّق. الطابع الزمني للحقبة بالملي ثانية
العنوان اختياري

عنوان القائمة (على سبيل المثال، قائمة البقالة)

إذا لم يقدّم المطوّر عنوانًا، سيتم استخدام قائمة التسوّق كعنوان تلقائي.

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

حجم النص المقترَح: أقل من 25 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
تصنيفات العناصر مطلوبة

قائمة التصنيفات للسلع في قائمة التسوّق

يجب تقديم تصنيف واحد على الأقل ويمكن تقديم ما يصل إلى 10 تصنيفات حسب الأولوية، ويعتمد العدد الفعلي للتصنيفات المعروضة على شكل الجهاز.

قائمة التصنيفات النصية المجانية

حجم النص المقترَح: أقل من 20 حرفًا (قد يظهر النص الطويل جدًا على شكل علامات حذف)

FoodReorderCluster

الشكل: مجموعة "إعادة طلب الطعام".

السمة المتطلبات الوصف التنسيق
معرّف الموارد المنتظم (URI) للإجراء مطلوبة

الرابط العميق لإعادة الطلب في تطبيق الشريك

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

معرّف موارد منتظم (URI)
نص الإجراء اختياري

نص عبارة الحث على اتخاذ إجراء للزر في صفحة "إعادة الطلب" (على سبيل المثال، الطلب مرة أخرى).

إذا لم يوفّر المطوّر نصًا للإجراء، سيتم استخدام إعادة الطلب كخيار تلقائي.

تتوفّر هذه السمة في الإصدار 1.1.0 والإصدارات الأحدث.

سلسلة
عدد العناصر مطلوبة

عدد السلع (وليس عدد المنتجات فقط) في الطلب السابق

على سبيل المثال: إذا كان هناك 3 أكواب قهوة صغيرة وكرواسون واحد في الطلب السابق، يجب أن يكون هذا الرقم 4.

عدد صحيح >= 1
العنوان مطلوبة عنوان السلعة التي تتم إعادة طلبها

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

حجم النص المقترَح: أقل من 40 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
تصنيفات العناصر

اختياري

(في حال عدم توفيرها، يجب توفير صور الملصقات)

قائمة تصنيفات العناصر للطلب السابق

يمكن تقديم ما يصل إلى 10 تصنيفات حسب الأولوية، ويعتمد العدد الفعلي للتصنيفات المعروضة على شكل الجهاز.

قائمة النصوص الحرة

حجم النص المقترَح لكل تصنيف: أقل من 20 حرفًا (قد يظهر النص الطويل جدًا بعلامات حذف)
صور الملصقات

اختياري

(في حال عدم تقديمها، يجب تقديم تصنيفات السلع)

صور للسلع في الطلب السابق

يمكن تقديم ما يصل إلى 10 صور حسب الأولوية، ويعتمد عدد الصور الفعلي المعروض على شكل الجهاز.

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

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

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

نسبة العرض إلى الارتفاع الحدّ الأدنى لعدد وحدات البكسل وحدات البكسل المقترَحة

مربّعة (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) وجدولتها بشكل منتظم أو حسب الحدث (على سبيل المثال، في كل مرة يفتح فيها المستخدم التطبيق أو عندما يضيف المستخدم عنصرًا إلى سلة التسوق).

‫AppEngageFoodClient مسؤول عن نشر مجموعات الطعام.

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

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishFoodShoppingCarts
  • publishFoodShoppingLists
  • publishReorderCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteFoodShoppingCartCluster
  • deleteFoodShoppingListCluster
  • deleteReorderCluster
  • deleteUserManagementCluster
  • deleteClusters

isServiceAvailable

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

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

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

Kotlin

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

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

Java

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

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

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

اعتبارًا من الإصدار 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 السمات التالية:

السمة المتطلبات الوصف
قائمة بـ ProductEntity أو StoreEntity أو RecipeEntity مطلوبة قائمة بالكيانات التي تشكّل الاقتراحات لهذه المجموعة من الاقتراحات يجب أن تكون الكيانات في مجموعة واحدة من النوع نفسه.
العنوان مطلوبة

عنوان مجموعة الاقتراحات (على سبيل المثال، خصومات كبيرة على قائمة عيد الشكر)

حجم النص المقترَح: أقل من 25 حرفًا (قد تظهر علامات حذف في النص الطويل جدًا)
العنوان الفرعي اختياري العنوان الفرعي لمجموعة الاقتراحات
معرّف الموارد المنتظم (URI) للإجراء اختياري

الرابط لصفحة معيّنة في تطبيق الشريك حيث يمكن للمستخدمين الاطّلاع على القائمة الكاملة للاقتراحات.

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

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .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 الحالية من الشريك المطوّر.
  • يتم تحليل البيانات من الطلب وتخزينها في "المجموعة المميّزة" المعدَّلة.

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

publishFoodShoppingCarts

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

Kotlin

client.publishFoodShoppingCarts(
            PublishFoodShoppingCartsRequest.Builder()
                .addFoodShoppingCart(
                    FoodShoppingCart.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFoodShoppingCarts(
            new PublishFoodShoppingCartsRequest.Builder()
                .addFoodShoppingCart(
                    new FoodShoppingCart.Builder()
                        ...
                        .build())
                .build());

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

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

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

publishFoodShoppingLists

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

Kotlin

client.publishFoodShoppingLists(
            PublishFoodShoppingListsRequest.Builder()
                .addFoodShoppingList(
                    FoodShoppingList.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFoodShoppingLists(
            new PublishFoodShoppingListsRequest.Builder()
                .addFoodShoppingList(
                    new FoodShoppingList.Builder()
                        ...
                        .build())
                .build());

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

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

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

publishReorderCluster

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

Kotlin

client.publishReorderCluster(
            PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    FoodReorderCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishReorderCluster(
            new PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    new FoodReorderCluster.Builder()
                        ...
                        .build())
                .build());

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

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

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

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

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

deleteFoodShoppingCartCluster

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

Kotlin

client.deleteFoodShoppingCartCluster()

Java

client.deleteFoodShoppingCartCluster();

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

deleteFoodShoppingListCluster

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

Kotlin

client.deleteFoodShoppingListCluster()

Java

client.deleteFoodShoppingListCluster();

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

deleteReorderCluster

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

Kotlin

client.deleteReorderCluster()

Java

client.deleteReorderCluster();

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

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

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

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

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

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 food shopping cart cluster publish when PUBLISH_FOOD_SHOPPING_CART broadcast
  // is received
  // Trigger food shopping list cluster publish when PUBLISH_FOOD_SHOPPING_LIST broadcast
  // is received
  // Trigger reorder cluster publish when PUBLISH_REORDER_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 food Shopping Cart Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register food Shopping List Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FOOD_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)
}

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 food shopping cart cluster publish when PUBLISH_FOOD_SHOPPING_CART broadcast is
// received

// Trigger food shopping list cluster publish when PUBLISH_FOOD_SHOPPING_LIST broadcast is
// received

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

// Register food Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_FOOD_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);

}

  • يجب الإعلان بشكل ثابت عن عملية التنفيذ باستخدام علامة <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.food.PUBLISH_FOOD_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_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.food.PUBLISH_FOOD_SHOPPING_CART ننصح ببدء مكالمة publishFoodShoppingCarts عند تلقّي هذا الطلب.
  • com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST ننصح ببدء مكالمة publishFoodShoppingLists عند تلقّي هذا الطلب.
  • com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER ننصحك ببدء مكالمة publishReorderCluster عند تلقّي هذا الطلب.

سير عمل الدمج

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

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

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

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

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

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

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

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