Engage SDK Social: دستورالعمل های یکپارچه سازی فنی شخص ثالث

با دسترسی به کاربران خود در هر کجا که هستند، تعامل با برنامه را افزایش دهید. Engage SDK را ادغام کنید تا توصیه‌های شخصی‌سازی‌شده و محتوای مداوم را مستقیماً به کاربران در سطوح مختلف روی دستگاه، مانند Collections ، Entertainment Space و Play Store ارائه دهید. این ادغام کمتر از ۵۰ کیلوبایت (فشرده‌شده) به میانگین APK اضافه می‌کند و برای اکثر برنامه‌ها حدود یک هفته از زمان توسعه‌دهنده را می‌گیرد. برای اطلاعات بیشتر به سایت تجاری ما مراجعه کنید.

این راهنما شامل دستورالعمل‌هایی برای شرکای توسعه‌دهنده است تا محتوای رسانه‌های اجتماعی را به سطوح محتوای Engage ارائه دهند.

جزئیات ادغام

بخش زیر جزئیات ادغام را شرح می‌دهد.

اصطلاحات

خوشه‌های توصیه ، پیشنهادهای شخصی‌سازی‌شده از یک شریک توسعه‌دهنده‌ی منفرد را نشان می‌دهند.

توصیه‌های شما ساختار زیر را دارند:

خوشه توصیه : نمای رابط کاربری که شامل گروهی از توصیه‌ها از یک شریک توسعه‌دهنده است.

هر خوشه توصیه شامل یکی از دو نوع موجودیت زیر است:

• نهاد رسانه‌ای پرتره
• نهاد اجتماعی

PortraitMediaEntity باید شامل یک تصویر عمودی برای پست باشد. متادیتای مربوط به پروفایل و تعامل اختیاری است.

• پست

  • تصویر در حالت عمودی و برچسب زمان، یا
  • تصویر در حالت عمودی + محتوای متن و برچسب زمان

• پروفایل

  • آواتار، نام یا شناسه، تصویر اضافی

• تعاملات

  • فقط بشمارید و برچسب بزنید، یا
  • تعداد و تصویر (آیکون)

SocialPostEntity شامل فراداده‌های مربوط به پروفایل، پست و تعامل است.

• پروفایل

  • آواتار، نام یا شناسه، متن اضافی، تصویر اضافی

• پست

  • متن و مهر زمان، یا
  • رسانه‌های غنی (تصویر یا URL غنی) و مهر زمان، یا
  • متن و رسانه‌های غنی (تصویر یا URL غنی) و مهر زمان، یا
  • پیش‌نمایش ویدیو (تصویر بندانگشتی و مدت زمان) و برچسب زمانی

• تعاملات

  • فقط بشمارید و برچسب بزنید، یا
  • تعداد و تصویر (آیکون)

پیش کار

حداقل سطح API: ۱۹

کتابخانه 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.12'
}

خلاصه

طراحی بر اساس پیاده‌سازی یک سرویس محدود (bound service) است.

داده‌هایی که یک کلاینت می‌تواند منتشر کند، برای انواع مختلف خوشه‌ها مشمول محدودیت‌های زیر است:

مرحله ۱: ارائه داده‌های موجودیت

SDK موجودیت‌های مختلفی را برای نمایش هر نوع آیتم تعریف کرده است. SDK از موجودیت‌های زیر برای دسته‌ی Social پشتیبانی می‌کند:

1. PortraitMediaEntity
2. SocialPostEntity

نمودارهای زیر ویژگی‌ها و الزامات موجود برای هر نوع را شرح می‌دهند.

PortraitMediaEntity

SocialPostEntity

مشخصات تصویر

تصاویر باید روی CDN های عمومی میزبانی شوند تا گوگل بتواند به آنها دسترسی داشته باشد.

فرمت‌های فایل

PNG، JPG، GIF ثابت، WebP

حداکثر اندازه فایل

۵۱۲۰ کیلوبایت

توصیه‌های اضافی

• ناحیه امن تصویر: محتوای مهم خود را در مرکز ۸۰٪ تصویر قرار دهید.
• از یک پس‌زمینه شفاف استفاده کنید تا تصویر در تنظیمات تم تیره و روشن به درستی نمایش داده شود.

مرحله ۲: ارائه داده‌های خوشه‌ای

توصیه می‌شود که کار انتشار محتوا در پس‌زمینه اجرا شود (برای مثال، با استفاده از WorkManager ) و به صورت منظم یا بر اساس رویداد (مثلاً هر بار که کاربر برنامه را باز می‌کند یا وقتی کاربر به تازگی یک حساب کاربری جدید را دنبال می‌کند) زمان‌بندی شود.

AppEngageSocialClient مسئول انتشار خوشه‌های اجتماعی است.

API های زیر برای انتشار خوشه ها در کلاینت وجود دارد:

• isServiceAvailable
• publishRecommendationClusters
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

این API برای بررسی اینکه آیا سرویس برای ادغام در دسترس است و آیا محتوا می‌تواند روی دستگاه ارائه شود، استفاده می‌شود.

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.
    }
}

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

این API برای انتشار لیستی از اشیاء RecommendationCluster استفاده می‌شود.

یک شیء RecommendationCluster می‌تواند ویژگی‌های زیر را داشته باشد:

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

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

وقتی سرویس درخواست را دریافت می‌کند، اقدامات زیر در یک تراکنش انجام می‌شود:

• تمام داده‌های موجود در خوشه توصیه حذف می‌شوند.
• داده‌های درخواست تجزیه و تحلیل شده و در خوشه‌های توصیه جدید ذخیره می‌شوند.

در صورت بروز خطا، کل درخواست رد می‌شود و وضعیت موجود حفظ می‌شود.

publishUserAccountManagementRequest

این API برای انتشار یک کارت ورود به سیستم استفاده می‌شود. عمل ورود به سیستم، کاربران را به صفحه ورود به سیستم برنامه هدایت می‌کند تا برنامه بتواند محتوا را منتشر کند (یا محتوای شخصی‌سازی‌شده‌تری ارائه دهد).

فراداده‌های زیر بخشی از کارت ورود به سیستم هستند -

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

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

اگر به هر دلیل داخلی تجاری، هیچ یک از کلاسترها منتشر نشده‌اند، اکیداً توصیه می‌کنیم وضعیت انتشار را با استفاده از API مربوط به updatePublishStatus به‌روزرسانی کنید. این مهم است زیرا:

• ارائه وضعیت در همه سناریوها، حتی زمانی که محتوا منتشر شده است (وضعیت == منتشر شده)، برای پر کردن داشبوردهایی که از این وضعیت صریح برای انتقال سلامت و سایر معیارهای ادغام شما استفاده می‌کنند، بسیار مهم است.
• اگر هیچ محتوایی منتشر نشده باشد اما وضعیت ادغام خراب نباشد (STATUS == NOT_PUBLISHED)، گوگل می‌تواند از نمایش هشدارها در داشبوردهای سلامت برنامه جلوگیری کند. این تأیید می‌کند که محتوا به دلیل وضعیت مورد انتظار از دیدگاه ارائه‌دهنده منتشر نشده است.
• این به توسعه‌دهندگان کمک می‌کند تا بینشی در مورد زمان انتشار داده‌ها در مقابل عدم انتشار آنها ارائه دهند.
• گوگل ممکن است از کدهای وضعیت برای ترغیب کاربر به انجام اقدامات خاصی در برنامه استفاده کند تا بتواند محتوای برنامه را ببیند یا از آن عبور کند.

لیست کدهای وضعیت انتشار واجد شرایط عبارتند از:

// 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

اگر محتوا به دلیل عدم ورود کاربر منتشر نشود، گوگل انتشار کارت ورود به سیستم را توصیه می‌کند. اگر به هر دلیلی ارائه دهندگان خدمات قادر به انتشار کارت ورود به سیستم نیستند، توصیه می‌کنیم API مربوط به 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());

deleteRecommendationClusters

این API برای حذف محتوای خوشه‌های توصیه استفاده می‌شود.

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

وقتی سرویس درخواست را دریافت می‌کند، داده‌های موجود را از خوشه‌های توصیه حذف می‌کند. در صورت بروز خطا، کل درخواست رد می‌شود و وضعیت موجود حفظ می‌شود.

deleteUserManagementCluster

این API برای حذف محتوای کلاستر UserAccountManagement استفاده می‌شود.

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

وقتی سرویس درخواست را دریافت می‌کند، داده‌های موجود را از کلاستر UserAccountManagement حذف می‌کند. در صورت بروز خطا، کل درخواست رد شده و وضعیت موجود حفظ می‌شود.

deleteClusters

این API برای حذف محتوای یک نوع خوشه مشخص استفاده می‌شود.

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

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

وقتی سرویس درخواست را دریافت می‌کند، داده‌های موجود را از تمام خوشه‌هایی که با انواع خوشه‌های مشخص‌شده مطابقت دارند، حذف می‌کند. کلاینت‌ها می‌توانند یک یا چند نوع خوشه را ارسال کنند. در صورت بروز خطا، کل درخواست رد می‌شود و وضعیت موجود حفظ می‌شود.

مدیریت خطا

اکیداً توصیه می‌شود که به نتیجه‌ی وظیفه از APIهای انتشار گوش دهید تا بتوان اقدامات بعدی را برای بازیابی و ارسال مجدد یک وظیفه‌ی موفق انجام داد.

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 برگردانده می‌شود و علت آن به صورت یک کد خطا درج می‌شود.

مرحله ۳: مدیریت اهداف پخش

علاوه بر فراخوانی‌های API مربوط به انتشار محتوا از طریق یک job، لازم است یک BroadcastReceiver نیز برای دریافت درخواست انتشار محتوا راه‌اندازی شود.

هدف از اعلان‌های هدف عمدتاً فعال‌سازی مجدد برنامه و همگام‌سازی اجباری داده‌ها است. اعلان‌های هدف برای ارسال مکرر طراحی نشده‌اند. این اعلان‌ها فقط زمانی فعال می‌شوند که سرویس Engage تشخیص دهد محتوا ممکن است قدیمی باشد (مثلاً یک هفته قدیمی). به این ترتیب، حتی اگر برنامه برای مدت طولانی اجرا نشده باشد، اطمینان بیشتری وجود دارد که کاربر می‌تواند تجربه محتوای جدیدی داشته باشد.

BroadcastReceiver باید به دو روش زیر تنظیم شود:

• با استفاده از Context.registerReceiver() یک نمونه از کلاس BroadcastReceiver را به صورت پویا ثبت کنید. این کار امکان ارتباط از برنامه‌هایی را که هنوز در حافظه فعال هستند، فراهم می‌کند.

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION
  // 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),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

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),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);
}

• یک پیاده‌سازی را به صورت ایستا با تگ <receiver> در فایل AndroidManifest.xml خود تعریف کنید. این به برنامه اجازه می‌دهد تا در زمانی که در حال اجرا نیست، اهداف پخش (broadcast intents) را دریافت کند و همچنین به برنامه اجازه می‌دهد تا محتوا را منتشر کند.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      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 توصیه می‌شود هنگام دریافت این intent، یک فراخوانی publishRecommendationClusters آغاز شود.

گردش کار یکپارچه‌سازی

برای راهنمای گام به گام تأیید ادغام پس از تکمیل، به گردش کار ادغام توسعه‌دهنده مراجعه کنید.

سوالات متداول

برای سوالات متداول به بخش سوالات متداول Engage SDK مراجعه کنید.

تماس

در صورت وجود هرگونه سوال در طول فرآیند ادغام، engage-developers@google.com تماس بگیرید. تیم ما در اسرع وقت پاسخ خواهد داد.

مراحل بعدی

پس از تکمیل این ادغام، مراحل بعدی به شرح زیر است:

• یک ایمیل به engage-developers@google.com ارسال کنید و APK یکپارچه خود را که آماده آزمایش توسط گوگل است، پیوست کنید.
• گوگل یک بررسی داخلی انجام می‌دهد تا مطمئن شود که ادغام طبق انتظار کار می‌کند. در صورت نیاز به تغییرات، گوگل با شما تماس می‌گیرد و جزئیات لازم را ارائه می‌دهد.
• وقتی آزمایش کامل شد و نیازی به تغییر نبود، گوگل با شما تماس می‌گیرد تا به شما اطلاع دهد که می‌توانید APK به‌روزرسانی‌شده و یکپارچه‌شده را در فروشگاه Play منتشر کنید.
• پس از اینکه گوگل تأیید کرد که APK به‌روزرسانی‌شده شما در فروشگاه Play منتشر شده است، خوشه‌های توصیه شما منتشر شده و برای کاربران قابل مشاهده خواهند بود.