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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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() API.

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

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

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

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

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

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

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

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