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

Google در حال ساخت یک سطح روی دستگاه است که برنامه های کاربران را بر اساس عمودی سازماندهی می کند و یک تجربه همهجانبه جدید را برای مصرف شخصی و کشف محتوای برنامه امکان پذیر می کند. این تجربه تمام صفحه به شرکای توسعه‌دهنده فرصتی می‌دهد تا بهترین محتوای غنی خود را در یک کانال اختصاصی خارج از برنامه خود به نمایش بگذارند.

این سند حاوی دستورالعمل‌هایی برای شرکای توسعه‌دهنده است تا محتوای اجتماعی خود را با استفاده از Engage SDK برای پر کردن این سطح جدید یکپارچه کنند.

جزئیات یکپارچه سازی

بخش زیر جزئیات یکپارچه سازی را نشان می دهد.

اصطلاحات

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

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

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

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

• PortraitMediaEntity
• SocialPostEntity

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

• ارسال کنید

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

• نمایه

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

• تعاملات

  • فقط شمارش و برچسب بزنید یا
  • شمارش و بصری (نماد)

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

• نمایه

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

• ارسال کنید

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

• تعاملات

  • فقط شمارش و برچسب، یا
  • شمارش و بصری (نماد)

قبل از کار

حداقل سطح API: 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'
}

خلاصه

طراحی بر اساس اجرای یک سرویس محدود است.

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

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

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

1. PortraitMediaEntity
2. SocialPostEntity

نمودارهای زیر ویژگی ها و الزامات موجود برای هر نوع را مشخص می کند.

PortraitMediaEntity

SocialPostEntity

مشخصات تصویر

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

فرمت های فایل

PNG، JPG، GIF استاتیک، WebP

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

5120 کیلوبایت

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

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

مرحله 2: داده های Cluster را ارائه دهید

توصیه می‌شود کار انتشار محتوا در پس‌زمینه اجرا شود (مثلاً با استفاده از 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

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

• ارائه وضعیت در همه سناریوها، حتی زمانی که محتوا منتشر می شود (وضعیت == منتشر شده)، برای پر کردن داشبوردهایی که از این وضعیت صریح برای انتقال سلامت و سایر معیارهای ادغام شما استفاده می کنند، بسیار مهم است.
• اگر محتوایی منتشر نشود اما وضعیت ادغام خراب نباشد (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 انتشار کارت ورود به سیستم را توصیه می کند. اگر به هر دلیلی ارائه دهندگان قادر به انتشار کارت ورود به سیستم نیستند، توصیه می کنیم با کد وضعیت NOT_PUBLISHED_REQUIRES_SIGN_IN با updatePublishStatus API تماس بگیرید.

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 Cluster استفاده می شود.

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

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

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

مرحله 3: اهداف پخش را مدیریت کنید

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

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

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 مراجعه کنید.

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

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

تماس بگیرید

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

مراحل بعدی

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

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