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

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

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

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

يُرجى الاطّلاع على تفاصيل الدمج أدناه:

المصطلحات

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

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

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

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

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

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

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

    تتخذ سلة التسوق البنية التالية:

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

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

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

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

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

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

ما قبل العمل

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

إضافة مكتبة com.google.android.play:engage إلى تطبيقك:

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

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

ملخّص

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

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

نوع المجموعة حدود المجموعة الحدود القصوى لعدد العناصر في المجموعة الواحدة
مجموعة أو مجموعات الاقتراحات 5 على الأكثر ShoppingEntity 25 كحد أقصى
مجموعة مميّزة 1 كحد أقصى ShoppingEntity واحد كحدّ أقصى
مجموعة سلات التسوّق 1 كحد أقصى ShoppingCart واحد كحدّ أقصى
مجموعة قوائم التسوّق 1 كحد أقصى ShoppingListEntity واحد كحدّ أقصى
مجموعة إعادة ترتيب التسوّق 1 كحد أقصى ReorderEntity واحد كحدّ أقصى

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

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

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

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

ShoppingEntity

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

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

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

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

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

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

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

السعر الحالي للكيان.

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

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

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

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

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

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

تمثّل هذه السمة القيمة القصوى لمقياس التقييم.

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

 الرقم >= 0.0
التقييم - القيمة الحالية عنصر مطلوب

القيمة الحالية لتقييم الكيان.

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

 الرقم >= 0.0
التقييم - العدد اختياري تمثّل هذه السمة عدد التقييمات للكيان. سلسلة
DisplayTimeWindow (اختيارية): ضبط فترة زمنية لعرض المحتوى على مساحة العرض
الطابع الزمني للبدء اختياري

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

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

 الطابع الزمني للفترة بالمللي ثانية
الطابع الزمني للانتهاء اختياري

الطابع الزمني للفترة التي لن يظهر بعدها المحتوى على السطح.

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

 الطابع الزمني للفترة بالمللي ثانية

ShoppingCart

السمة المتطلب الوصف التنسيق
يوري أدنيش مطلوبة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 الطابع الزمني للفترة بالمللي ثانية
الطابع الزمني للانتهاء اختياري

الطابع الزمني للفترة التي لن يظهر بعدها المحتوى على السطح.

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

 الطابع الزمني للفترة بالمللي ثانية

ShoppingList

السمة المتطلب الوصف التنسيق
يوري أدنيش مطلوبة

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

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

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

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

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

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

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

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

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

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

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

ShoppingReorderCluster

السمة المتطلب الوصف التنسيق
يوري أدنيش مطلوبة

رابط الصفحة في التطبيق المطلوب إعادة ترتيبه في تطبيق الشريك.

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

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

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

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

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

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

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

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

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

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

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

اختياري

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

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

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

قائمة النصوص المجانية

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

اختياري

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

صور السلع بالترتيب السابق

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

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

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

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

نسبة العرض إلى الارتفاع الحدّ الأدنى لوحدات البكسل وحدات البكسل التي ننصح بها

مربّع (1x1)

الخيار المفضّل بالنسبة إلى المجموعات غير المميّزة

 300×300 1200 × 1200

أفقي (1.91x1)

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

 600×314 1200 × 628
العمودية (4×5) 480×600 960×1200

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

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

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

5120 كيلوبايت

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

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

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

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

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

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

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishShoppingCart
  • publishShoppingList
  • publishShoppingReorderCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteShoppingCartCluster
  • deleteShoppingListCluster
  • deleteShoppingReorderCluster
  • 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 حرفًا (قد يعرض النص الطويل جدًا علامات حذف)
يوري أدنيش اختياري

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

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

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

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

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

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

publishUserAccountManagementRequest

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

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

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

الصورة التي تظهر على البطاقة

صور بنسبة عرض إلى ارتفاع تبلغ 16x9 بدقة 1264x712
العنوان اختياري - إذا لم يتم توفير الصورة، يجب تقديم الصورة العنوان على البطاقة
نص الإجراء اختياري النص الذي يظهر في عبارة الحث على اتخاذ إجراء (أي تسجيل الدخول)
العنوان الفرعي اختياري عنوان فرعي اختياري على البطاقة

Kotlin


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

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

Java


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

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

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

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

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

updatePublishStatus

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

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

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

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

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

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

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

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

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

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

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

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

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

Kotlin


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

Java


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

deleteRecommendationClusters

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

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

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

Kotlin


client.deleteShoppingReorderCluster()

Java


client.deleteShoppingReorderCluster();

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

deleteUserManagementCluster

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

Kotlin


client.deleteUserManagementCluster()

Java


client.deleteUserManagementCluster();

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

deleteClusters

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

Kotlin


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

Java


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

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

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

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

Kotlin


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

Java


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

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

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

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

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

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

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

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

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION
  // broadcast is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is
  // received
  // Trigger 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
}

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

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION))

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

// Register Shopping Cart Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART))

// Register Shopping List Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_LIST))

// Register Reorder Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_REORDER_CLUSTER))
}

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
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

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

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

// Register Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_CART));

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

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

}
  • أعلِن بشكل ثابت عن عملية تنفيذ باستخدام علامة <receiver> في ملف AndroidManifest.xml الخاص بك. يتيح ذلك للتطبيق تلقّي أغراض البث عندما لا يكون قيد التشغيل، كما يسمح للتطبيق بنشر المحتوى.
<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.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>
   </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 عند تلقّي هذا الغرض.

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

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

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

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

Contact

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

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

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

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