إرشادات نشر مجموعة حِزم تطوير البرامج (SDK) للتفاعل

يتضمّن هذا الدليل مجموعة من الإرشادات لنشر المجموعات العنقودية التي يمكن للمطوّرين استخدامها عند الدمج مع حزمة Engage SDK.

مجموعات "الاقتراحات"

عنوان المجموعة

ننصح بتقديم عنوان فريد وملائم للمجموعة يمنح المستخدمين مزيدًا من المعلومات حول محتوى المجموعة.

في ما يلي بعض الأمثلة على عناوين المجموعات الجيدة استنادًا إلى المحتوى:

  • المجموعات المرتبطة بالتسوّق
    • عروض Lightning
    • منتجات أسبوعية لا غنى عنها
    • رسالة متعلقة بعملية شراء سمّاعات Pixel Buds
    • أحذية مطر نسائية
  • مجموعات من الكتب حول الصحة
    • الصحة والعقل والجسد
    • محتوى مقترَح لك في Health
    • المنتجات الأكثر مبيعًا في مجال اللياقة البدنية

محتوى المجموعة

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

عندما يكون المستخدم مسجّلاً الدخول

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

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

متساهل

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

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

صارم

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

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

عندما لا يكون المستخدم مسجّلاً الدخول

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

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

متساهل

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

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

صارم

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

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

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

مجموعات المتابعة

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

عندما يكون المستخدم مسجّلاً الدخول

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

صارم

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

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

عندما لا يكون المستخدم مسجّلاً الدخول

Continuation journeys are primarily intended for signed-in users; however, you can also publish continuation clusters for signed-out users if your app supports guest sessions.

مجموعة إدارة المستخدمين

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

بطاقة تسجيل الدخول

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

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

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

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

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

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

تعديل حالة النشر

إذا لم يتم نشر أي من المجموعات لأي سبب داخلي يتعلّق بالنشاط التجاري، ننصح بشدة بتعديل حالة النشر باستخدام واجهة برمجة التطبيقات 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

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

‫WorkManager لنشر المجموعات

ننصح باستخدام WorkManager لنشر المجموعات العنقودية، لأنّه الحلّ المقترَح للعمل في الخلفية حيث يجب أن يكون التنفيذ انتهازيًا وموثوقًا.

  • ينفّذ WorkManager عملك في الخلفية في أقرب وقت ممكن.
  • يتولّى WorkManager معالجة المنطق لبدء عملك في ظل مجموعة متنوعة من الظروف، حتى إذا انتقل المستخدم بعيدًا عن تطبيقك.

عندما ينتقل المستخدم بعيدًا عن التطبيق، ننصحك ببدء مهمة في الخلفية تنشر مجموعات المتابعة مع مجموعات الاقتراحات. من الأماكن المناسبة للتعامل مع هذا المنطق هو Activity.onStop()، والذي يتم استدعاؤه عندما ينتقل المستخدم بعيدًا عن التطبيق.

ننصحك باستخدام PeriodicWorkRequest لجدولة مهمة متكررة تنشر المجموعات كل 24 ساعة. باستخدام سياسة CANCEL_AND_REENQUEUE لتشغيل العمل، يمكن للمطوّرين التأكّد من أنّ WorkManager يرسل البيانات المعدَّلة في كل مرة ينتقل فيها المستخدم بعيدًا عن التطبيق. يساعد ذلك في منع المستخدمين من رؤية البيانات القديمة.

يوضّح المثال التالي ذلك:

// Define the PublishClusters Worker requiring input
public class PublishClusters extends Worker {

   public PublishClusters(Context appContext, WorkerParameters workerParams) {
       super(appContext, workerParams);
   }

   @NonNull
   @Override
   public Result doWork() {
       // publish clusters
   }
   ...
}

public static void schedulePublishClusters(Context appContext) {
// Create a PeriodicWorkRequest to schedule a recurring job to update
// clusters at a regular interval
PeriodicWorkRequest publishClustersEntertainmentSpace =
// Define the time for the periodic job
       new PeriodicWorkRequest.Builder(PublishClusters.class, 24, TimeUnit.HOURS)
// Set up a tag for the worker.
// Tags are Unique identifier, which can be used to identify that work
// later in order to cancel the work or observe its progress.
          .addTag("Publish Clusters to Entertainment Space")
          .build();

// Trigger Periodic Job, this will ensure that the periodic job is triggered
// only once since we have defined a uniqueWorkName
WorkManager.getInstance(appContext).enqueueUniquePeriodicWork(
// uniqueWorkName
     "publishClustersEntertainmentSpace",
// If a work with the uniqueWorkName is already running, it will cancel the
// existing running jobs and replace it with the new instance.
// ExistingPeriodicWorkPolicy#CANCEL_AND_REENQUEUE
     ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
// Recurring Work Request
publishClustersEntertainmentSpace);

}

التعامل مع أهداف البث

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

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

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

  • سجِّل ديناميكيًا مثيلاً من فئة BroadcastReceiver باستخدام Context.registerReceiver(). يتيح ذلك الاتصال من التطبيقات التي لا تزال نشطة في الذاكرة.
  • يجب الإعلان بشكل ثابت عن عملية التنفيذ باستخدام علامة <receiver> في ملف AndroidManifest.xml. يسمح هذا للتطبيق بتلقي أهداف البث عندما لا يكون قيد التشغيل، ويسمح أيضًا للتطبيق بنشر المحتوى.