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

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

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

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

المصطلحات

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

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

    تتّخذ اقتراحاتك البنية التالية:

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

    • ShoppingEntity: عنصر يمثّل سلعة واحدة في مجموعة.

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

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

    تتضمّن سلة التسوّق البنية التالية:

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

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

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

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

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

      • صور لـ X منتجات في طلب المستخدم السابق
      • تصنيفات لـ X منتجات في طلب المستخدم السابق

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

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

    • تتّخذ السمة ShoppingOrderTrackingCluster البنية التالية:

      • مجموعة تتبُّع طلبات التسوّق: هي طريقة عرض في واجهة المستخدم تتضمّن مجموعة من معاينات تتبُّع الطلبات من العديد من شركاء المطوّرين
      • 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.5.2'
}

لمزيد من المعلومات، يمكنك الاطّلاع على مقالة مستوى ظهور الحِزم في الإصدار 11 من نظام التشغيل Android.

ملخّص

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

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

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

لا يُتوقّع توفّر سلال تسوّق متعددة إلا للتطبيقات التي تتضمّن سلال تسوّق منفصلة لكل تاجر.

مجموعة قوائم التسوّق عملية واحدة بحد أقصى ShoppingListEntity واحد كحدّ أقصى
مجموعة إعادة ترتيب التسوّق عملية واحدة بحد أقصى ReorderEntity واحد كحدّ أقصى
مجموعة تتبُّع طلبات التسوّق 3 على الأكثر ‫3 ShoppingOrderTrackingEntity على الأكثر

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

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

  1. ShoppingEntity
  2. ShoppingCart
  3. ShoppingList
  4. Reorder
  5. ShoppingOrderTracking

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

ShoppingEntity

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

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

تمثّل هذه السمة الرابط لصفحة في التطبيق تعرض تفاصيل حول الكيان.

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

معرّف موارد منتظم (URI)
العنوان اختياري تمثّل هذه السمة اسم الكيان.

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

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

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

يجب توفيرها إذا تم توفير السعر المشطوب.

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

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

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

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

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

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

يجب توفيرها إذا تم توفير القيمة الحالية للتقييم أيضًا.

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

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

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

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

تمثّل هذه السمة عدد التقييمات الخاصة بالكيان.

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

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

تمثّل هذه السمة عدد التقييمات الخاصة بالكيان.

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

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

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

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

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

الطابع الزمني لوقت بدء العصر الذي يتوقف بعده عرض المحتوى على مساحة العرض.

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

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

ShoppingCart

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

الرابط لصفحة سلة التسوق في تطبيق الشريك

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

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

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

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

عدد صحيح >= 1
نص الإجراء اختياري

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

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

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

سلسلة
العنوان اختياري

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

في حال عدم توفير المطوّر للعنوان، يكون العنوان التلقائي هو سلّة التسوّق.

إذا كان الشريك المطوّر ينشر سلّة تسوّق منفصلة لكل تاجر، يُرجى تضمين اسم التاجر في العنوان.

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

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

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

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

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

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

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

قائمة التصنيفات النصية الحرة

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

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

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

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

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

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

الطابع الزمني لوقت بدء العصر الذي يتوقف بعده عرض المحتوى على مساحة العرض.

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

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

ShoppingList

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

الرابط لصفحة معيّنة في تطبيق الشريك تؤدي إلى قائمة التسوّق

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

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

عنوان القائمة (مثلاً، قائمة مشترياتك)

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

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

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

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

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

قائمة التصنيفات النصية الحرة

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

ShoppingReorderCluster

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

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

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

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

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

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

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

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

تمثّل هذه السمة عدد السلع (وليس عدد المنتجات فقط) في الطلب السابق.

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

عدد صحيح >= 1
العنوان مطلوبة تمثّل هذه السمة عنوان المنتج الذي يمكن إعادة طلبه.

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

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

اختياري

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

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

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

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

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

صور الملصقات

اختياري

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

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

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

 راجِع مواصفات الصور للحصول على إرشادات.

ShoppingOrderTrackingCluster

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

تمثّل هذه السمة عنوانًا قصيرًا للحزمة أو السلع التي يتم تتبُّعها أو رقم التتبُّع.

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

حجم النص المقترَح: 50 حرفًا (سيتم عرض علامات حذف إذا كان النص طويلاً جدًا)

نوع الطلب مطلوبة

تمثّل هذه السمة عنوانًا قصيرًا للحزمة أو السلع التي يتم تتبُّعها أو رقم التتبُّع.

قيم التعداد: IN_STORE_PICKUP وSAME_DAY_DELIVERY وMULTI_DAY_DELIVERY
الحالة مطلوبة

تمثّل هذه السمة حالة الطلب الحالية.

على سبيل المثال: "سأصل متأخرًا" أو "أثناء النقل" أو "متأخر" أو "تم الشحن" أو "تم التسليم" أو "غير متوفّر في المخزون" أو "الطلب جاهز"

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

حجم النص المقترَح: 25 حرفًا (سيتم عرض علامات حذف إذا كان النص طويلاً جدًا)

وقت الطلب مطلوبة

الطابع الزمني للحقبة بالملي ثانية الذي تم فيه تقديم الطلب.

سيتم عرض وقت الطلب إذا لم تتوفر فترة التسليم المتوقّعة

 الطابع الزمني لحقبة Unix بالملي ثانية
معرّف الموارد المنتظم للإجراء مطلوبة

رابط لصفحة معيّنة في تطبيق الشريك لتتبُّع الطلب

 معرّف موارد منتظم (URI)
OrderDeliveryTimeWindow (اختيارية): لضبط مهلة زمنية للطلب الذي يتم تتبّعه منذ وقت تقديمه وحتى وقت التسليم المتوقّع أو الفعلي
OrderDeliveryTimeWindow - Start Time اختياري

الطابع الزمني لحقبة Unix بالملي ثانية الذي سيتم بعده أو عنده تسليم الطلب أو تجهيزه للاستلام

 الطابع الزمني لحقبة Unix بالملي ثانية
OrderDeliveryTimeWindow - End Time اختياري

الطابع الزمني لحقبة Unix بالملي ثانية الذي سيتم فيه تسليم الطلب أو سيكون جاهزًا للاستلام، أو قبله.

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

تمثّل هذه السمة صورة لسلعة أو منتج واحد يشكّل جزءًا من الطلب.

نسبة العرض إلى الارتفاع المقترَحة هي 1:1

 راجِع مواصفات الصور للحصول على إرشادات.
عدد العناصر اختياري عدد السلع في الطلب عدد صحيح >= 1
الوصف اختياري

فقرة نصية واحدة لوصف السلع في الطلب

ملاحظة: سيظهر للمستخدم إما الوصف أو قائمة العناوين الفرعية، وليس كلاهما.

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

حجم النص المقترَح: 180 حرفًا
قائمة العناوين الفرعية اختياري

ما يصل إلى 3 عناوين فرعية، كل عنوان فرعي عبارة عن سطر واحد من النص

ملاحظة: سيظهر للمستخدم إما الوصف أو قائمة العناوين الفرعية، وليس كلاهما.

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

حجم النص المقترَح لكل عنوان فرعي: 50 حرفًا كحد أقصى
Order Value - CurrentPrice اختياري تمثّل هذه السمة القيمة الحالية للطلب. حقل التعبئة النصّية الحرّة
رقم الطلب اختياري رقم الطلب أو معرّفه الذي يمكن استخدامه لتحديد الطلب بشكلٍ فريد.

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

حجم النص المقترَح: 25 حرفًا كحدّ أقصى
رقم التتبع اختياري رقم تتبُّع تسليم الطلب/الحزمة في حال كان الطلب يتطلّب تسليمًا

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

حجم النص المقترَح: 25 حرفًا كحدّ أقصى

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

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

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

مربّعة (1x1)

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

 300x300 1200x1200

أفقية (1.91x1)

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

 600x314 1200x628
عمودية (4x5) ‫480x600 960x1200

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

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

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

5120 كيلوبايت

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

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

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

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

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

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

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishShoppingCart
  • publishShoppingCarts
  • publishShoppingList
  • publishShoppingReorderCluster
  • publishShoppingOrderTrackingCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteShoppingCartCluster
  • deleteShoppingListCluster
  • deleteShoppingReorderCluster
  • deleteShoppingOrderTrackingCluster
  • deleteUserManagementCluster
  • deleteClusters

isServiceAvailable

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

Kotlin

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

Java

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

publishRecommendationClusters

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

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

السمة المتطلب الوصف
قائمة ShoppingEntity مطلوبة قائمة بكائنات ShoppingEntity التي تشكّل الاقتراحات الخاصة بمجموعة الاقتراحات هذه.
العنوان مطلوبة

عنوان مجموعة الاقتراحات

حجم النص المقترَح: أقل من 25 حرفًا (قد تظهر علامات حذف إذا كان النص طويلاً جدًا)
العنوان الفرعي اختياري العنوان الفرعي لمجموعة الاقتراحات
Action 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 الحالية من حساب المطوّر الشريك.
  • يتم تحليل البيانات من الطلب وتخزينها في "المجموعة المميّزة" المعدَّلة.

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

publishShoppingCart

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

Kotlin

client.publishShoppingCart(
            PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    ShoppingCart.Builder()
                        ...
                        .build())
                .build())

Java

client.publishShoppingCart(
            new PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    new ShoppingCart.Builder()
                        ...
                        .build())
                .build())

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

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

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

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 الحالية من حساب المطوّر الشريك.
  • يتم تحليل البيانات الواردة من الطلب وتخزينها في مجموعة "سلة التسوّق" المعدَّلة.

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

publishShoppingList

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

Kotlin

client.publishFoodShoppingList(
            PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFoodShoppingList(
            new PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    new FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build());

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

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

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

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 الحالية من الشريك المطوِّر.
  • يتم تحليل البيانات الواردة من الطلب وتخزينها في مجموعة تتبُّع طلبات التسوّق المعدَّلة.

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

publishUserAccountManagementRequest

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

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

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

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

صور بنسبة عرض إلى ارتفاع 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());

deleteRecommendationClusters

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

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

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

deleteFeaturedCluster

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

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

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

deleteShoppingCartCluster

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

Kotlin

client.deleteShoppingCartCluster()

Java

client.deleteShoppingCartCluster();

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

deleteShoppingListCluster

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

Kotlin

client.deleteShoppingListCluster()

Java

client.deleteShoppingListCluster();

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

deleteShoppingReorderCluster

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

Kotlin

client.deleteShoppingReorderCluster()

Java

client.deleteShoppingReorderCluster();

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

deleteShoppingOrderTrackingCluster

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

Kotlin

client.deleteShoppingOrderTrackingCluster()

Java

client.deleteShoppingOrderTrackingCluster();

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

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 لتلقّي طلب نشر المحتوى.

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

يجب إعداد 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 يُنصح ببدء مكالمة publishShoppingCart عند تلقّي هذا الغرض.
  • com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST يُنصح ببدء مكالمة publishShoppingList عند تلقّي هذا الغرض.
  • 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 المعدَّلة والمدمجة على &quot;متجر Play&quot;.
  • بعد أن تؤكّد Google أنّه تم نشر حزمة APK المعدَّلة على متجر Play، قد يتم نشر المجموعات الاقتراحات والمميّزة وسلة التسوّق وقائمة التسوّق ومجموعة إعادة الترتيب ومجموعة تتبُّع طلبات التسوّق، وقد تصبح مرئية للمستخدمين.