Engage SDK Social: دستورالعمل‌های ادغام فنی طرف سوم

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

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

پشتیبانی دسته‌بندی و سطوح

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

وضعیت دسته‌بندی محتوا یا مورد استفاده سطوح پشتیبانی‌شده
پشتیبانی‌شده
(واجدشرایط در همه سطوح)
  • شبکه‌های اجتماعی
  • تصویر / میم
  • کلیپ‌های ویدیویی / ویدیو کوتاه مدت
  • دیدارهای IRL
  • فضای ذخیره‌سازی ابری عکس
  • مجموعه‌ها
  • برگه برنامه‌های «فروشگاه Play»
  • زبانه «شما» در «فروشگاه Play»
  • صفحه فهرستگان فروشگاه «فروشگاه Play»
پشتیبانی نمی‌شود
  • گپ تصویری زنده
  • پیام‌رسانی فوری، هم‌رسانی حضور آنلاین، یا داده‌های زنده
  • هم‌رسانی فایل و بارگیرنده‌ها
  • دوست‌یابی
  • تولیدکننده‌های چهرک

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

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

اصطلاحات

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

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

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

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

  • PortraitMediaEntity
  • SocialPostEntity

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

  • پست

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

  • نمایه

    • چهرک، نام یا نام کاربری، تصویر اضافی

  • تعاملات

    • فقط شمارش و برچسب‌گذاری، یا
    • تعداد و عنصر دیداری (نماد)

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

  • نمایه

    • چهره‌نما، نام یا نام کاربری، نوشتار اضافی، تصویر اضافی

  • پست

    • نوشتار و مُهر زمان، یا
    • رسانه غنی (تصویر یا نشانی وب غنی) و مُهر زمان، یا
    • نوشتار و رسانه غنی (تصویر یا نشانی وب غنی) و مُهر زمان، یا
    • پیش‌نمایش ویدیو (ریزعکس و مدت‌زمان) و مُهر زمان

  • تعاملات

    • فقط شمارش و برچسب‌گذاری، یا
    • تعداد و تصویر (نماد)

پیش‌کار

حداقل سطح میانای برنامه‌سازی کاربردی: ۱۹

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

خلاصه

این طراحی براساس پیاده‌سازی خدمات محدودکننده است.

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

نوع خوشه محدودیت‌های خوشه حداقل محدودیت‌های نهاد در خوشه حداکثر حد مجاز نهاد در خوشه
خوشه(های) توصیه حداکثر ۷ حداقل ۱ (PortraitMediaEntity، یا SocialPostEntity) حداکثر ۵۰ (PortraitMediaEntity، یا SocialPostEntity)

مرحله ۱: ارائه داده‌های نهاد

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

  1. PortraitMediaEntity
  2. SocialPostEntity

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

PortraitMediaEntity

مشخصه الزام شرح قالب
URI کنش برای همه سطوح به‌جز Google TV الزامی است

پیوند عمیق به نهاد در برنامه ارائه‌دهنده.

توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید

URI
PlatformSpecificPlayback برای سطح Google TV الزامی است

پیوند عمیق به نهاد در برنامه ارائه‌دهنده برای پلاتفرم‌هایی مثل Google TV و تلفن همراه.

فهرست اشیاء PlatformSpecificPlayback
دلیل توصیه اختیاری توجیه توصیه محتوا به کاربر. شیء RecommendationReason
خلاصه نظرات اختیاری خلاصه نظرات برای پست. رشته
فراداده‌های مربوط به پست (الزامی)
تصویر(ها) الزامی

تصویر(ها) باید نسبت ابعادی عمودی داشته باشد.

وقتی چند تصویر ارائه می‌شود، ممکن است واسط کاربر فقط ۱ تصویر را نشان دهد. بااین‌حال، رابط کاربری ممکن است نشانگر بصری ارائه دهد که تصاویر بیشتری در برنامه وجود دارد.

اگر پست ویدیو باشد، ارائه‌دهنده باید ریزعکسی از ویدیو ارائه دهد تا به‌عنوان تصویر نشان داده شود.

برای راهنمایی، مشخصات تصویر را ببینید.
محتوای نوشتار اختیاری نوشتار اصلی پست، به‌روزرسانی، و غیره. رشته (حداکثر ۱۴۰ نویسه توصیه می‌شود)
مُهر زمان اختیاری زمانی که پست منتشر شده است. مُهر زمان تاریخ برحسب میلی‌ثانیه
محتوای ویدیویی است اختیاری آیا پست ویدیو است؟ بولی
مدت ویدیو اختیاری مدت ویدیو برحسب میلی‌ثانیه. بلند
فراداده مربوط به نمایه (اختیاری)
نام الزامی نام یا شناسه یا نام کاربری نمایه، مثلاً «John Doe»،‏ «‎@TeamPixel» رشته(حداکثر ۲۵ نویسه توصیه می‌شود)
چهرک الزامی

عکس نمایه یا تصویر چهرک کاربر.

تصویر مربعی ۱:۱

برای راهنمایی، مشخصات تصویر را ببینید.
تصویر اضافی اختیاری

نشان نمایه. برای مثال - نشان درستی‌سنجی‌شده

تصویر مربعی ۱:۱

برای راهنمایی، مشخصات تصویر را ببینید.
فراداده مربوط به تعامل‌ها (اختیاری)
شمارش اختیاری

تعداد تعامل‌ها را نشان می‌دهد، برای مثال - «۳٫۷ میلیون».

توجه: اگر هم «تعداد» و هم «مقدار تعداد» ارائه شده باشد، از «تعداد» استفاده خواهد شد.

توجه: شرکا باید از Count یا CountWithOptionalLabel استفاده کنند.

رشته
CountWithOptionalLabel اختیاری

تعداد تعامل‌ها را با برچسب اختیاری نشان دهید، برای مثال - «۳٫۷ میلیون پسندیدن».

توجه: اگر هم CountWithOptionalLabel و هم Count Value ارائه شده باشد، یکی از آن‌ها استفاده خواهد شد.

توجه: شرکا باید از Count یا CountWithOptionalLabel استفاده کنند.

رشته
مقدار شمارش اختیاری

تعداد تعامل‌ها به‌عنوان مقدار.

توجه: اگر برنامه‌تان منطق مربوط به نحوه بهینه‌سازی اعداد بزرگ برای اندازه‌های مختلف نمایش را مدیریت نمی‌کند، به‌جای Count،‏ Count Value را ارائه دهید. اگر هم «تعداد» و هم «مقدار تعداد» ارائه شده باشد، از «تعداد» استفاده می‌شود.

بلند
برچسب اختیاری مشخص کنید برچسب تعامل برای چیست. برای مثال - «پسندیدن‌ها».

رشته
تصویری اختیاری

مشخص کنید تعامل برای چیست. برای مثال - تصویری که نماد «پسندیدن»، اموجی را نشان می‌دهد.

می‌توانید بیش‌از ۱ تصویر ارائه دهید، هرچند ممکن است همه آن‌ها در همه ضرایب شکل نشان داده نشوند.

توجه: باید تصویر مربعی ۱:۱ باشد

 برای راهنمایی، مشخصات تصویر را ببینید.
DisplayTimeWindow (اختیاری) - پنجره زمانی را برای نمایش محتوا در سطح تنظیم کنید
مُهر زمان شروع اختیاری

مُهر زمان مبدأ که پس‌از آن محتوا باید در سطح نشان داده شود.

اگر تنظیم نشده باشد، محتوا واجدشرایط نمایش در سطح است.

 مُهر زمان تاریخ برحسب میلی‌ثانیه
مُهر زمان پایان اختیاری

مُهر زمان مبدأ که پس‌از آن محتوا دیگر در سطح نشان داده نمی‌شود.

اگر تنظیم نشده باشد، محتوا واجدشرایط نمایش در سطح است.

 مُهر زمان تاریخ برحسب میلی‌ثانیه

SocialPostEntity

مشخصه الزام شرح قالب
URI کنش الزامی

پیوند عمیق به نهاد در برنامه ارائه‌دهنده.

توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید

URI
URIهای PlatformSpecificPlayback برای سطح Google TV الزامی است

پیوند عمیق به نهاد در برنامه ارائه‌دهنده برای پلاتفرم‌هایی مثل Google TV و تلفن همراه.

فهرست اشیاء PlatformSpecificPlayback
دلیل توصیه اختیاری توجیه توصیه محتوا به کاربر. شیء RecommendationReason
خلاصه نظرات اختیاری خلاصه نظرات برای پست. رشته

فراداده‌های مربوط به پست (الزامی)

حداقل یکی از TextContent،‏ Image، یا WebContent لازم است

تصویر(ها) اختیاری

تصویر(ها) باید نسبت ابعادی عمودی داشته باشد.

وقتی چند تصویر ارائه می‌شود، ممکن است واسط کاربر فقط ۱ تصویر را نشان دهد. بااین‌حال، رابط کاربری ممکن است نشانگر بصری ارائه دهد که تصاویر بیشتری در برنامه وجود دارد.

اگر پست ویدیو باشد، ارائه‌دهنده باید ریزعکسی از ویدیو ارائه دهد تا به‌عنوان تصویر نشان داده شود.

برای راهنمایی، مشخصات تصویر را ببینید.
محتوای نوشتار اختیاری نوشتار اصلی پست، به‌روزرسانی، و غیره. رشته (حداکثر ۱۴۰ نویسه توصیه می‌شود)
محتوای ویدیویی (اختیاری)
مدت الزامی مدت ویدیو برحسب میلی‌ثانیه. بلند
تصویر الزامی پیش‌نمایش تصویر محتوای ویدیو. برای راهنمایی، مشخصات تصویر را ببینید.
پیش‌نمایش پیوند (اختیاری)
پیش‌نمایش پیوند - عنوان الزامی نوشتاری که عنوان محتوای صفحه وب را نشان می‌دهد رشته
پیش‌نمایش پیوند - نام میزبان الزامی نوشتاری که مالک صفحه وب را نشان می‌دهد، مثلاً «INSIDER» رشته
پیش‌نمایش پیوند - تصویر اختیاری نگاره اصلی برای محتوای وب برای راهنمایی، مشخصات تصویر را ببینید.
مُهر زمان اختیاری زمانی که پست منتشر شده است. مُهر زمان تاریخ برحسب میلی‌ثانیه
فراداده مربوط به نمایه (اختیاری)
نام الزامی نام نمایه یا شناسه یا نام کاربری، مثلاً «John Doe»،‏ «‎@TeamPixel». رشته(حداکثر ۲۵ نویسه توصیه می‌شود)
نوشتار اضافی اختیاری

می‌تواند به‌عنوان شناسه نمایه یا نام کاربری یا فراداده اضافی استفاده شود

برای مثال «@John-Doe»،‏ «۵ میلیون دنبال‌کننده»، «ممکن است بپسندید»، «پرطرفدار»، «۵ پست جدید»

رشته(حداکثر ۴۰ نویسه توصیه می‌شود)
چهرک الزامی

عکس نمایه یا تصویر چهرک کاربر.

تصویر مربعی ۱:۱

برای راهنمایی، مشخصات تصویر را ببینید.
تصویر اضافی اختیاری

نشان نمایه، برای مثال - نشان درستی‌سنجی‌شده

تصویر مربعی ۱:۱

برای راهنمایی، مشخصات تصویر را ببینید.
فراداده مربوط به تعامل‌ها (اختیاری)
شمارش الزامی

تعداد تعامل‌ها را نشان می‌دهد، برای مثال - «۳٫۷ میلیون».

توجه: شرکا باید از Count یا CountWithOptionalLabel استفاده کنند.

رشته
CountWithOptionalLabel الزامی

تعداد تعامل‌ها را با برچسب اختیاری نشان دهید، برای مثال - «۳٫۷ میلیون پسندیدن».

توجه: شرکا باید از Count یا CountWithOptionalLabel استفاده کنند.

رشته
برچسب

اختیاری

اگر ارائه نشده باشد، Visual باید ارائه شود.

مشخص کنید تعامل برای چیست. برای مثال - «پسندیدن‌ها». رشته (حداکثر ۲۰ نویسه برای ترکیب تعداد + برچسب توصیه می‌شود)
تصویری

اختیاری

اگر ارائه نشده باشد، برچسب باید ارائه شود.

مشخص کنید تعامل برای چیست. برای مثال - تصویری که نماد «پسندیدن»، اموجی را نشان می‌دهد.

می‌تواند بیش‌از ۱ تصویر ارائه دهد، هرچند ممکن است همه آن‌ها در همه ضرایب شکل نشان داده نشود.

تصویر مربعی ۱:۱

برای راهنمایی، مشخصات تصویر را ببینید.
DisplayTimeWindow (اختیاری) - پنجره زمانی را برای نمایش محتوا در سطح تنظیم کنید
مُهر زمان شروع اختیاری

مُهر زمان مبدأ که پس‌از آن محتوا باید در سطح نشان داده شود.

اگر تنظیم نشده باشد، محتوا واجدشرایط نمایش در سطح است.

 مُهر زمان تاریخ برحسب میلی‌ثانیه
مُهر زمان پایان اختیاری

مُهر زمان مبدأ که پس‌از آن محتوا دیگر در سطح نشان داده نمی‌شود.

اگر تنظیم نشده باشد، محتوا واجدشرایط نمایش در سطح است.

 مُهر زمان تاریخ برحسب میلی‌ثانیه

مشخصات تصویر

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

قالب‌های فایل

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

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

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

توصیه‌های بیشتر

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

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

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

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

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

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

isServiceAvailable

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

می‌توانید دردسترس بودن سرویس را برای هر نوع خوشه‌ای که قصد انتشار آن را دارید بررسی کنید. ‫isServiceAvailable API یک شیء درخواست را می‌پذیرد، ServiceAvailabilityRequest، که حاوی انواع خوشه‌ای است که باید دردسترس بودن سرویس برای آن‌ها بررسی شود. می‌توانید مقادیر شمارشی ClusterType موردنیاز برای ServiceAvailabilityRequest را در جدول زیر پیدا کنید.

نوع خوشه ثابت نوع خوشه مقدار عدد صحیح
نامعلوم TYPE_UNKNOWN 0
خوشه توصیه TYPE_RECOMMENDATION 1
خوشه ویژه TYPE_FEATURED 2
خوشه ادامه TYPE_CONTINUATION 3
خوشه مدیریت کاربر TYPE_ENGAGEMENT 8
خوشه اشتراک TYPE_SUBSCRIPTION 12

کاتلین

val request = ServiceAvailabilityRequest.Builder()
    .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
    .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
    .build()

client.isServiceAvailable(request).addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val availabilityMap = task.result
        if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
            // Proceed with publishing continuation content
        }
        if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
}

جاوا

ServiceAvailabilityRequest request =
    new ServiceAvailabilityRequest.Builder()
        .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
        .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
        .build();

client.isServiceAvailable(request).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        Map<Integer, Boolean> availabilityMap = task.getResult();
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
            // Proceed with publishing continuation content
        }
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
});
ویژگی دردسترس بودن مشروط سرویس

برخی‌از برنامه‌های ادغام‌شده پیکربندی ویژه‌ای را درخواست می‌کنند که سرویس Engage را به‌طور متناوب فعال و غیرفعال می‌کند تا هزینه‌های ارائه کاهش یابد. بااین‌حال، این استراتژی دریافت محتوای متناوب بر تجربه کاربر تأثیر منفی می‌گذارد: محتوای قدیمی ارائه نخواهد شد و برخی‌از سطوح ارائه نخواهند شد.

از نسخه ۱.۶.۰، کیت توسعه نرم‌افزار Engage امکان بررسی دردسترس بودن برای انواع خوشه‌های خاص را فراهم می‌کند. اگر مایلید این ویژگی را برای هر نوع خوشه‌ای فعال کنید، با engage-developers@google.com تماس بگیرید.

برای نسخه‌های کیت توسعه نرم‌افزار قبل‌از نسخه ۱.۶.۰ (منسوخ‌شده)

کاتلین

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

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

شیء RecommendationCluster می‌تواند مشخصه‌های زیر را داشته باشد:

مشخصه الزام شرح
List of SocialPostEntity, or PortraitMediaEntity الزامی فهرستی از نهادهایی که توصیه‌های این «خوشه توصیه‌ها» را تشکیل می‌دهند. نهادهای موجود در یک خوشه باید از یک نوع باشند.
عنوان الزامی

عنوان «خوشه توصیه» (برای مثال، جدیدترین‌ها از دوستانتان).

اندازه نوشتار توصیه‌شده: کمتر از ۲۵ نویسه (نوشتاری که خیلی طولانی باشد ممکن است با سه‌نقطه نشان داده شود)
زیرنویس اختیاری زیرعنوان «خوشه توصیه‌ها».
شناسه منبع یکسان کنش اختیاری

پیوند عمیق به صفحه‌ای در برنامه شریک که کاربران می‌توانند فهرست کامل توصیه‌ها را در آنجا ببینند.

توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید

کاتلین

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 به‌روز کنید. این موضوع مهم است زیرا :

  • ارائه وضعیت در همه سناریوها، حتی زمانی که محتوا منتشر شده است (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 توصیه می‌کند «کارت ورود به سیستم» منتشر شود. اگر ارائه‌دهندگان به هر دلیلی نتوانند «کارت ورود به سیستم» را منتشر کنند، توصیه می‌کنیم با کد وضعیت NOT_PUBLISHED_REQUIRES_SIGN_IN با میانای برنامه‌سازی کاربردی updatePublishStatus تماس بگیرید

کاتلین

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

deleteRecommendationsClusters

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

کاتلین

client.deleteRecommendationsClusters()

جاوا

client.deleteRecommendationsClusters();

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

deleteUserManagementCluster

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

کاتلین

client.deleteUserManagementCluster()

جاوا

client.deleteUserManagementCluster();

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

deleteClusters

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

کاتلین

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

جاوا

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .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 فراخوانی سرویس بیش‌ازحد انجام می‌شود.

مرحله ۳: مدیریت هدف‌های همه‌فرستی

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

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

BroadcastReceiver باید به دو روش زیر راه‌اندازی شود:

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

کاتلین

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 به‌صورت ایستا اعلام کنید. این به برنامه اجازه می‌دهد تا زمانی که درحال اجرا نیست، اهداف پخش را دریافت کند و همچنین به برنامه اجازه می‌دهد تا محتوا را منتشر کند.

<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 توصیه می‌شود هنگام دریافت این قصد، تماس publishRecommendationClusters شروع شود.

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

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

پرسشگان

برای پرسشگان، به پرسشگان Engage SDK مراجعه کنید.

تماس

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

مراحل بعدی

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

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