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

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

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

تفاصيل الدمج

المصطلحات

يتضمّن هذا الدمج أنواع المجموعات الثلاثة التالية: الاقتراح، المتابعة، والعرض.

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

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

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

      الشكل 1. واجهة مستخدم "مساحة الترفيه" تعرض مجموعة اقتراحات من شريك واحد

    • الكيان: هو كائن يمثّل عنصرًا واحدًا في مجموعة. يمكن أن يكون العنصر كتابًا إلكترونيًا أو كتابًا مسموعًا أو سلسلة كتب وغير ذلك. اطّلِع على قسم تقديم data للعناصر للحصول على قائمة بأنواع العناصر المتوافقة.

      الشكل 2. واجهة مستخدم "مساحة الترفيه" تعرض كيانًا واحدًا ضمن مجموعة اقتراحات خاصة بشريك واحد.

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

    الشكل 3. واجهة مستخدم "مساحة الترفيه" تعرض مجموعة محتوى متسلسلاً مع اقتراحات غير مكتملة من شركاء عدّة (يظهر اقتراح واحد فقط حاليًا).

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

    الشكل 4. واجهة مستخدم "مساحة الترفيه" تعرض مجموعة "محتوى مميّز" مع اقتراحات من شركاء متعددين (يظهر اقتراح واحد فقط في الوقت الحالي)

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

الحد الأدنى لمستوى واجهة برمجة التطبيقات: 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 بحد أقصى 50 بحد أقصى
مجموعة المتابعة 1 بحد أقصى 10 بحد أقصى
المجموعة المميزة 1 بحد أقصى 10 على الأكثر

الخطوة 1: تقديم بيانات العنصر

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

  1. EbookEntity
  2. AudiobookEntity
  3. BookSeriesEntity

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

EbookEntity

يمثّل عنصر EbookEntity كتابًا إلكترونيًا (على سبيل المثال، الكتاب الإلكتروني لكتاب Becoming من تأليف ميشيل أوباما).

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

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

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

تاريخ النشر اختياري بالملي ثانية إذا تم تقديمها
الوصف اختياري يجب أن يتألّف من 200 حرف كحدّ أقصى في حال توفّره.
السعر اختياري حقل التعبئة النصّية الحرّة
عدد الصفحات اختياري يجب أن يكون عددًا صحيحًا موجبًا في حال توفّره.
النوع اختياري تمثّل هذه السمة قائمة الأنواع المرتبطة بالكتاب.
اسم السلسلة اختياري اسم السلسلة التي ينتمي إليها الكتاب الإلكتروني (مثل Harry Potter).
فهرس وحدات السلسلة اختياري تمثّل هذه السمة فهرس الكتاب الإلكتروني في السلسلة، حيث يمثّل الرقم 1 أول كتاب إلكتروني في السلسلة. على سبيل المثال، إذا كان Harry Potter and the Prisoner of Azkaban هو الكتاب الثالث في السلسلة، يجب ضبط القيمة على 3.
مواصلة نوع الدفتر اختياري

‫TYPE_CONTINUE: استئناف قراءة كتاب غير مكتمل

‫TYPE_NEXT: للمتابعة في حلقة جديدة من سلسلة.

TYPE_NEW - تم إصداره مؤخرًا.
آخر مدة تفاعل مطلوبة بشروط

يجب تقديمها عندما يكون العنصر في مجموعة "المتابعة".

يمكن أن تكون الكتب الإلكترونية *حديثة* جزءًا من مجموعة مواصلة القراءة.

بالملي ثانية منذ بداية الفترة
النسبة المئوية للتقدّم مطلوب بشكل مشروط

يجب تقديمها عندما يكون العنصر في مجموعة "المتابعة".

يجب أن تكون القيمة أكبر من 0 وأقل من 100.
‫DisplayTimeWindow: ضبط فترة زمنية لمحتوى ليتم عرضه على المساحة
الطابع الزمني للبدء اختياري

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

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

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

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

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

بالملي ثانية منذ بداية الفترة

AudiobookEntity

يمثّل عنصر AudiobookEntity كتابًا مسموعًا (على سبيل المثال، الكتاب المسموع Becoming من تأليف ميشيل أوباما).

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

الرابط لصفحة في تطبيق الموفِّر الخاص بالكتاب المسموع

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

تاريخ النشر اختياري بالملي ثانية إذا تم تقديمها
الوصف اختياري يجب أن يتألّف من 200 حرف كحدّ أقصى في حال توفّره.
السعر اختياري حقل التعبئة النصّية الحرّة
المدة اختياري يجب أن تكون القيمة موجبة إذا تم توفيرها.
النوع اختياري تمثّل هذه السمة قائمة الأنواع المرتبطة بالكتاب.
اسم السلسلة اختياري اسم السلسلة التي ينتمي إليها الكتاب المسموع (مثل هاري بوتر.
فهرس وحدة السلسلة اختياري فهرس الكتاب المسموع في السلسلة، حيث يكون الرقم 1 هو أول كتاب مسموع في السلسلة. على سبيل المثال، إذا كان Harry Potter and the Prisoner of Azkaban هو الكتاب الثالث في السلسلة، يجب ضبط القيمة على 3.
مواصلة نوع الدفتر اختياري

‫TYPE_CONTINUE: استئناف قراءة كتاب غير مكتمل

‫TYPE_NEXT: للمتابعة في حلقة جديدة من سلسلة.

TYPE_NEW - تم إصداره مؤخرًا.
آخر مدة تفاعل مطلوبة بشروط

يجب تقديمها عندما يكون العنصر في مجموعة "المتابعة".

بالملي ثانية منذ بداية الفترة
النسبة المئوية للتقدّم مطلوب بشكل مشروط

يجب توفيره عندما يكون العنصر في مجموعة المتابعة.

يمكن أن تكون الكتب المسموعة *المكتسَبة حديثًا* جزءًا من مجموعة "مواصلة القراءة".

يجب أن تكون القيمة أكبر من 0 وأقل من 100.
‫DisplayTimeWindow: ضبط فترة زمنية لمحتوى ليتم عرضه على المساحة
الطابع الزمني للبدء اختياري

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

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

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

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

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

بالمللي ثانية من الحقبة

BookSeriesEntity

يمثّل العنصر BookSeriesEntity سلسلة كتب (مثل سلسلة كتب Harry Potter التي تتضمّن 7 كتب).

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

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

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

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

‫TYPE_CONTINUE: استئناف قراءة كتاب غير مكتمل

‫TYPE_NEXT: للمتابعة في حلقة جديدة من سلسلة.

TYPE_NEW - تم إصداره مؤخرًا.
آخر مدة تفاعل مطلوبة بشروط

يجب تقديمها عندما يكون العنصر في مجموعة "المتابعة".

بالملي ثانية منذ بداية الفترة
النسبة المئوية للتقدّم مطلوب بشكل مشروط

يجب تقديمها عندما يكون العنصر في مجموعة "المتابعة".

يمكن أن تكون سلسلة الكتب *المُكتسَبة حديثًا* جزءًا من مجموعة مواصلة القراءة.

يجب أن تكون القيمة أكبر من 0 وأقل من 100.
‫DisplayTimeWindow: ضبط فترة زمنية لمحتوى ليتم عرضه على المساحة
الطابع الزمني للبدء اختياري

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

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

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

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

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

بالمللي ثانية من الحقبة

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

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

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

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

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

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

5,120 كيلوبايت

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

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

مثال

AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(
                      new Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .build();

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

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

تتحمّل "AppEngagePublishClient" مسؤولية نشر المجموعات. تتوفّر منصّة برمجة التطبيقات التالية في العميل:

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishContinuationCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteContinuationCluster
  • 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.

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .build())
                .build());

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

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

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

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

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

publishContinuationCluster

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

Kotlin

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

Java

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

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

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

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

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

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

deleteContinuationCluster

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

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

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

deleteUserManagementCluster

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

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

deleteClusters

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

Kotlin

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

Java

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

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

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

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

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

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

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

الخطوة 3: معالجة نوايا البث

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

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

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

  • سجِّل مثيلًا من فئة BroadcastReceiver ديناميكيًا باستخدام Context.registerReceiver(). يتيح ذلك التواصل من التطبيقات التي لا تزال نشطة في الذاكرة.
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 continuation cluster publish when PUBLISH_CONTINUATION 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 Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}
  • أعلن بشكل ثابت عن عملية تنفيذ باستخدام العلامة <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.PUBLISH_CONTINUATION" />
      </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.Publish_CONTINUATIONIt is recommended to start apublishContinuationCluster` عند تلقّي هذا الغرض.

سير عمل الدمج

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

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

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

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

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

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

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

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