حزمة تطوير البرامج (SDK) لتفاعلات المستخدمين على الشبكات الاجتماعية: تعليمات الدمج الفني التابع لطرف ثالث

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

يحتوي هذا المستند على تعليمات للشركاء المطوّرين لدمج المحتوى الاجتماعي باستخدام حزمة SDK Engage لتعبئة هذه المساحة الجديدة.

تفاصيل الدمج

يعرض القسم التالي تفاصيل الدمج.

المصطلحات

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

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

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

تتألف كل مجموعة اقتراحات من أحد النوعَين التاليَين من الكيانات :

  • PortraitMediaEntity
  • SocialPostEntity

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

  • مشاركة

    • صورة في الوضع العمودي والطابع الزمني
    • الصورة في الوضع العمودي + محتوى النص والطابع الزمني

  • الملف الشخصي

    • الصورة الرمزية أو الاسم أو الاسم المعرِّف أو صورة إضافية

  • التفاعلات

    • احتساب الأصوات وتصنيفها فقط
    • العدد والمرئيات (الرمز)

يحتوي SocialPostEntity على بيانات وصفية ذات صلة بالملف الشخصي والمشاركة والتفاعل.

  • الملف الشخصي

    • صورة رمزية أو اسم أو اسم معرِّف، نص إضافي، صورة إضافية

  • مشاركة

    • النص والطابع الزمني
    • الوسائط الغنية (صورة أو عنوان URL غني) والطابع الزمني
    • نص ووسائط غنية (صورة أو عنوان URL غني) والطابع الزمني
    • معاينة الفيديو (الصورة المصغّرة والمدّة) والطابع الزمني

  • التفاعلات

    • احتساب عدد العناصر وتصنيفها فقط
    • العدد والعناصر المرئية (رمز)

العمل التمهيدي

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

ملخّص

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

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

نوع المجموعة حدود المجموعات الحد الأدنى لعدد العناصر في مجموعة الحد الأقصى لعدد العناصر في مجموعة
مجموعات الاقتراحات 5 بحد أقصى 5 على الأقل (PortraitMediaEntity أو SocialPostEntity) 25 كحدّ أقصى (PortraitMediaEntity أو SocialPostEntity)

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

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

  1. PortraitMediaEntity
  2. SocialPostEntity

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

PortraitMediaEntity

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

رابط لصفحة في التطبيق ينقل إلى الكيان

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

URI
البيانات الوصفية ذات الصلة بالمشاركة (مطلوبة)
صورة (صور) مطلوب

يجب أن تكون الصور بنسبة العرض إلى الارتفاع العمودية.

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

إذا كانت المشاركة عبارة عن فيديو، على مقدّم المحتوى تقديم صورة مصغّرة للفيديو ليتم عرضها كصورة.

اطّلِع على مواصفات الصور للحصول على إرشادات.
محتوى النص اختياري تمثّل هذه السمة النص الأساسي للمنشور أو آخر المعلومات أو غير ذلك. سلسلة (140 حرفًا بحد أقصى)
الطابع الزمني اختياري يشير إلى الوقت الذي تم فيه نشر المشاركة. الطابع الزمني لحقبة Unix بالملي ثانية
أن يكون محتوى فيديو اختياري هل المحتوى المعروض في المشاركة هو فيديو؟ قيمة منطقية
مدة الفيديو اختياري مدة الفيديو بالمللي ثانية الصيغة الطويلة
البيانات الوصفية ذات الصلة بالملف الشخصي (اختيارية)
الاسم مطلوب اسم الملف الشخصي أو رقم التعريف أو الاسم المعرِّف، مثل "خالد كمال" أو "‎@TeamPixel" سلسلة (25 حرفًا بحد أقصى)
الأفاتار مطلوب

صورة الملف الشخصي أو الصورة الرمزية للمستخدم

صورة مربّعة بنسبة عرض إلى ارتفاع 1:1

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

شارة الملف الشخصي، على سبيل المثال، شارة إثبات القناة

صورة مربّعة بنسبة عرض إلى ارتفاع 1:1

اطّلِع على مواصفات الصور للحصول على إرشادات.
البيانات الوصفية ذات الصلة بالتفاعلات (اختيارية)
العدد اختياري

تشير إلى عدد التفاعلات، على سبيل المثال - "3.7 مليون".

ملاحظة: في حال توفّر كلّ من "العدد" و"قيمة العدد"، سيتم استخدام "العدد".

سلسلة

حجم النص المقترَح: 20 حرفًا كحد أقصى للعدد + التصنيف مجمّع
قيمة العدد اختياري

عدد التفاعلات كقيمة.

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

الصيغة الطويلة
التصنيف اختياري حدِّد الغرض من تصنيف التفاعل. على سبيل المثال، "الإعجابات".

سلسلة

حجم النص المُقترَح: 20 حرفًا كحد أقصى للعدد + التصنيف معًا
الصور اختياري

حدِّد الغرض من التفاعل. على سبيل المثال، صورة تعرض رمز الإعجابات والرموز التعبيرية.

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

ملاحظة: يجب أن تكون الصورة مربّعة بنسبة عرض إلى ارتفاع 1:1.

 اطّلِع على مواصفات الصور للحصول على إرشادات.
‫DisplayTimeWindow (اختياري) - لضبط نافذة زمنية لعرض المحتوى على المساحة
الطابع الزمني للبدء اختياري

الطابع الزمني لبدء حساب الفترة الذي من المفترض أن يظهر المحتوى بعده على سطح الشاشة

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

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

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

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

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

SocialPostEntity

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

رابط لصفحة في التطبيق ينقل إلى الكيان

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

URI

البيانات الوصفية ذات الصلة بالمشاركة (مطلوبة)

يجب توفير نوع واحد على الأقل من TextContent أو Image أو WebContent

صورة (صور) اختياري

يجب أن تكون الصور بنسبة العرض إلى الارتفاع العمودية.

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

إذا كانت المشاركة عبارة عن فيديو، على مقدّم الخدمة توفير صورة مصغّرة للفيديو لعرضها كصورة.

اطّلِع على مواصفات الصور للحصول على إرشادات.
محتوى النص اختياري تمثّل هذه السمة النص الأساسي للمنشور أو آخر المعلومات أو غير ذلك. سلسلة (140 حرفًا بحد أقصى)
محتوى الفيديو (اختياري)
المدة مطلوب مدة الفيديو بالمللي ثانية الصيغة الطويلة
صورة مطلوب صورة معاينة لمحتوى الفيديو اطّلِع على مواصفات الصور للحصول على إرشادات.
معاينة الرابط (اختياري)
معاينة الرابط - العنوان مطلوب نص يشير إلى عنوان محتوى صفحة الويب سلسلة
معاينة الرابط - اسم المضيف مطلوب نص للإشارة إلى مالك الصفحة الإلكترونية، مثل "INSIDER" سلسلة
معاينة الرابط - صورة اختياري الصورة الرئيسية لمحتوى الويب اطّلِع على مواصفات الصور للحصول على إرشادات.
الطابع الزمني اختياري يشير إلى الوقت الذي تم فيه نشر المشاركة. الطابع الزمني للحقبة بالمللي ثانية
البيانات الوصفية ذات الصلة بالملف الشخصي (اختيارية)
الاسم مطلوب اسم الملف الشخصي أو رقم تعريفه أو اسم معرِّفه، مثل "سامح رضا" أو " @TeamPixel". سلسلة (25 حرفًا بحد أقصى)
نص إضافي اختياري

يمكن استخدامه كمعرّف الملف الشخصي أو الاسم المعرِّف أو بيانات وصفية إضافية

على سبيل المثال " @John-Doe" و"5 مليون متابع" و"قد يعجبك" و"رائج" و"5 مشاركات جديدة"

سلسلة (40 حرفًا بحد أقصى)
الأفاتار مطلوب

صورة الملف الشخصي أو الصورة الرمزية للمستخدم

صورة مربّعة 1:1

اطّلِع على مواصفات الصور للحصول على إرشادات.
صورة إضافية اختياري

شارة الملف التجاري، على سبيل المثال، شارة إثبات الملكية

صورة مربّعة بنسبة عرض إلى ارتفاع 1:1

راجِع مواصفات الصور للحصول على إرشادات.
البيانات الوصفية ذات الصلة بالتفاعلات (اختيارية)
العدد مطلوب حدِّد عدد التفاعلات، على سبيل المثال - "3.7 مليون". سلسلة (يُنصح باستخدام 20 حرفًا بحد أقصى للعدد والعلامة معًا)
التصنيف

اختياري

يجب تقديم Visual في حال عدم توفّره.

حدِّد الغرض من التفاعل. على سبيل المثال، "المعجبون". سلسلة (يُنصح باستخدام 20 حرفًا بحد أقصى للعدد والعلامة معًا)
الصور

اختياري

يجب تقديم التصنيف في حال عدم تقديمه.

حدِّد الغرض من التفاعل. على سبيل المثال، صورة تعرض رمز "أعجبني" أو رموز تعبيرية

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

صورة مربّعة بنسبة عرض إلى ارتفاع 1:1

اطّلِع على مواصفات الصور للحصول على إرشادات.
‫DisplayTimeWindow (اختياري) - لضبط نافذة زمنية لعرض المحتوى على المساحة
الطابع الزمني للبدء اختياري

الطابع الزمني لبدء حساب الفترة الذي من المفترض أن يظهر المحتوى بعده على سطح الشاشة

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

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

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

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

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

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

يجب أن تكون الصور مستضافة على شبكات توصيل المحتوى (CDN) العامة حتى تتمكّن Google من الوصول إليها.

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

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

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

5,120 كيلوبايت

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

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

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

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

AppEngageSocialClient مسؤول عن نشر المجموعات الاجتماعية.

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

  • isServiceAvailable
  • publishRecommendationClusters
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • 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 السمات التالية:

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

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

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

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

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

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build());

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

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

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

publishUserAccountManagementRequest

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

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

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

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

صور بنسبة عرض إلى ارتفاع 16×9 بدرجة دقة 1264×712
العنوان اختياري - يجب تقديم الصورة إذا لم يتم توفيرها العنوان على البطاقة
نص الإجراء اختياري النص المعروض على عبارة الحث على اتّخاذ إجراء (مثل "تسجيل الدخول")
العنوان الفرعي اختياري ترجمة اختيارية على البطاقة

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 الحالية من المطوِّر الشريك .
  • يتم تحليل البيانات الواردة من الطلب وتخزينها في ملف تعريف clustered 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_MANAGEED_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();

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

deleteUserManagementCluster

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

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

deleteClusters

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

Kotlin

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

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .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 لتلقّي طلب نشر المحتوى.

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

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

  • تسجيل مثيل من الفئة BroadcastReceiver ديناميكيًا باستخدام Context.registerReceiver() يتيح ذلك الاتصال من التطبيقات التي لا تزال مباشرة في الذاكرة.
class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION 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));

}
  • حدِّد التنفيذ بشكلٍ ثابت باستخدام علامة <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>
   </receiver>
</application>

سترسل ال خدمة الأهداف التالية:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION ننصح ببدء مكالمة publishRecommendationClusters عندتلقّي نية الشراء هذه.

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

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

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

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

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

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

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

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

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