هم‌رسانی کردن حقوق برنامه با Google TV بااستفاده از Engage SDK

این راهنما حاوی دستورالعمل‌هایی برای توسعه‌دهندگان است تا داده‌های اشتراک و حق استفاده برنامه را بااستفاده از Engage SDK با Google TV هم‌رسانی کنند. کاربران می‌توانند محتوایی را که حق استفاده از آن را دارند پیدا کنند و به Google TV اجازه دهند توصیه‌های محتوای بسیار مرتبط را مستقیماً در تجربه‌های Google TV در تلویزیون، تلفن همراه، و رایانه لوحی به کاربران ارائه دهد.

پیش‌نیازها

مهم: ابراز علاقه به توسعه با Engage.

قبل‌از اینکه بتوانید از میانای برنامه‌سازی کاربردی حق استفاده دستگاه استفاده کنید، باید فید کنش‌های رسانه را آماده‌سازی کنید. اگر قبلاً این کار را نکرده‌اید، فرایند آماده‌سازی فید کنش‌های رسانه‌ای را تکمیل کنید.

پیش‌کار

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

1. اطلاعات اشتراک را در رویدادهای زیر منتشر کنید:
   1. کاربر به سیستم برنامه شما وارد می‌شود.
   2. کاربر بین نمایه‌ها جابه‌جا می‌شود (اگر نمایه‌ها پشتیبانی شوند).
   3. کاربر اشتراک جدیدی می‌خرد.
   4. کاربر اشتراک موجود را ارتقا می‌دهد.
   5. اشتراک کاربر منقضی می‌شود.

یکپارچه‌سازی

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

اشتراک سطح معمولی

برای کاربرانی که اشتراک‌های پایه در سرویس‌های ارائه‌دهنده رسانه دارند، برای مثال، سرویسی که یک سطح اشتراک دارد که دسترسی به همه محتوای پولی را اعطا می‌کند، این جزئیات ضروری را ارائه دهید:

1. SubscriptionType: طرح اشتراک خاصی را که کاربر دارد به‌وضوح نشان دهید.

   • SUBSCRIPTION_TYPE_ACTIVE: کاربر اشتراک پولی فعال دارد.
   • SUBSCRIPTION_TYPE_ACTIVE_TRIAL: کاربر اشتراک آزمایشی دارد.
   • SUBSCRIPTION_TYPE_INACTIVE: کاربر حساب دارد اما اشتراک یا دوره آزمایشی فعال ندارد.
   مهم: فقط کاربران دارای SUBSCRIPTION_TYPE_ACTIVE یا SUBSCRIPTION_TYPE_ACTIVE_TRIAL واجدشرایط دریافت توصیه‌های محتوای شخصی‌سازی‌شده براساس اشتراکشان هستند.

2. ExpirationTimeMillis: زمان اختیاری برحسب میلی‌ثانیه. مشخص کنید اشتراک چه زمانی منقضی می‌شود.

3. ProviderPackageName: نام بسته برنامه‌ای را که اشتراک را مدیریت می‌کند مشخص کنید.

نمونه‌ای برای فید ارائه‌دهنده رسانه نمونه.

"actionAccessibilityRequirement": [
  {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2022-06-01T07:00:00Z",
    "availabilityEnds": "2026-05-31T07:00:00Z",
    "requiresSubscription": {
    "@type": "MediaSubscription",
    // Don't match this string,
    // ID is only used to for reconciliation purpose
    "@id": "https://www.example.com/971bfc78-d13a-4419",
    // Don't match this, as name is only used for displaying purpose
    "name": "Basic common name",
    "commonTier": true
  }

مثال زیر SubscriptionEntity را برای کاربر ایجاد می‌کند:

val subscription = SubscriptionEntity.Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds since epoch
  .setExpirationTimeMillis(1767052800000)
  .build()

اشتراک ممتاز

اگر برنامه بسته‌های اشتراک Premium چندسطحی ارائه می‌دهد که شامل محتوا یا ویژگی‌های گسترش‌یافته فراتر از سطح معمول است، این موضوع را با افزودن یک یا چند حق استفاده به «اشتراک» نشان دهید.

این حق فیلدهای زیر را دارد:

1. Identifier: رشته شناسه الزامی برای این حق استفاده. این مقدار باید با یکی از شناسه‌های حق استفاده (توجه داشته باشید که این فیلد شناسه نیست) که در فید ارائه‌دهنده رسانه منتشرشده در Google TV ارائه شده است مطابقت داشته باشد.
2. ‫Name: این اطلاعات کمکی است و برای مطابقت دادن حق استفاده به‌کار می‌رود. هرچند اختیاری است، ارائه نام حق استفاده قابل‌خواندن برای انسان، درک حق استفاده کاربر را هم برای توسعه‌دهندگان و هم برای تیم‌های پشتیبانی بهبود می‌بخشد. برای مثال: Sling Orange.
3. ExpirationTimeMillis: درصورت تمایل، زمان انقضا را برحسب میلی‌ثانیه برای این حق استفاده مشخص کنید، اگر با زمان انقضای اشتراک متفاوت است. به‌طور پیش‌فرض، حق استفاده با انقضای اشتراک منقضی می‌شود.

برای قطعه فید ارائه‌دهنده رسانه نمونه زیر:

"actionAccessibilityRequirement": [
  {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2022-06-01T07:00:00Z",
    "availabilityEnds": "2026-05-31T07:00:00Z",
    "requiresSubscription": {
    "@type": "MediaSubscription",
    // Don't match this string,
    // ID is only used to for reconciliation purpose
    "@id": "https://www.example.com/971bfc78-d13a-4419",

    // Don't match this, as name is only used for displaying purpose
    "name": "Example entitlement name",
    "commonTier": false,
    // match this identifier in your API. This is the crucial
    // entitlement identifier used for recommendation purpose.
    "identifier": "example.com:entitlementString1"
  }

مثال زیر یک SubscriptionEntity برای کاربر مشترک‌شده ایجاد می‌کند:

// Subscription with entitlements.
// The entitlement expires at the same time as its subscription.
val subscription = SubscriptionEntity.Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds
  .setExpirationTimeMillis(1767052800000)
  .addEntitlement(
    SubscriptionEntitlement.Builder()
    // matches with the identifier in media provider feed
    .setEntitlementId("example.com:entitlementString1")
    .setDisplayName("entitlement name1")
    .build()
  )
  .build()

// Subscription with entitlements
// The entitement has different expiration time from its subscription
val subscription = SubscriptionEntity.Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds
  .setExpirationTimeMillis(1767052800000)
  .addEntitlement(
    SubscriptionEntitlement.Builder()
    .setEntitlementId("example.com:entitlementString1")
    .setDisplayName("entitlement name1")
    // You may set the expiration time for entitlement
    // December 15, 2025 10:00:00 AM in milliseconds
    .setExpirationTimeMillis(1765792800000)
    .build())
  .build()

اشتراک برای بسته سرویس پیوندشده

درحالی‌که اشتراک‌ها معمولاً به ارائه‌دهنده رسانه برنامه مبدأ تعلق دارند، می‌توان اشتراک را با مشخص کردن نام بسته سرویس پیوندشده در اشتراک، به بسته سرویس پیوندشده نسبت داد.

نمونه کد زیر نحوه ایجاد اشتراک کاربر را نشان می‌دهد.

// Subscription for linked service package
val subscription = SubscriptionEntity.Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds since epoch
  .setExpirationTimeMillis(1767052800000)
  .build()

علاوه‌براین، اگر کاربر اشتراک دیگری در سرویس فرعی دارد، اشتراک دیگری اضافه کنید و نام بسته سرویس پیوندشده را مطابق با آن تنظیم کنید.

// Subscription for linked service package
val linkedSubscription = SubscriptionEntity.Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("linked service package name")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds since epoch
  .setExpirationTimeMillis(1767052800000)
  .addBundledSubscription(
    BundledSubscription.Builder()
      .setBundledSubscriptionProviderPackageName(
        "bundled-subscription-package-name"
      )
      .setSubscriptionType(SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE)
      .setExpirationTimeMillis(111)
      .addEntitlement(
        SubscriptionEntitlement.Builder()
        .setExpirationTimeMillis(111)
        .setDisplayName("Silver subscription")
        .setEntitlementId("subscription.tier.platinum")
        .build()
      )
      .build()
  )
  .build()

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

ارائه مجموعه اشتراک

وقتی برنامه در پیش‌زمینه است، کار انتشار محتوا را اجرا کنید.

از روش publishSubscriptionCluster()، از کلاس AppEngagePublishClient، برای انتشار شیء SubscriptionCluster استفاده کنید.

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

client.publishSubscription(
  PublishSubscriptionRequest.Builder()
    .setAccountProfile(accountProfile)
    .setSubscription(subscription)
    .build()
)

از setSubscription() استفاده کنید تا تأیید کنید که کاربر باید فقط یک اشتراک برای سرویس داشته باشد.

از addLinkedSubscription() یا addLinkedSubscriptions() که فهرستی از اشتراک‌های پیوندشده را می‌پذیرند استفاده کنید تا کاربر بتواند صفر یا چند اشتراک پیوندشده داشته باشد.

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

به‌روز نگه داشتن اشتراک

1. برای ارائه به‌روزرسانی‌های فوری پس‌از تغییرات، هرگاه وضعیت اشتراک کاربر تغییر کرد (مثلاً فعال‌سازی، غیرفعال‌سازی، ارتقا، تنزل)، publishSubscriptionCluster را فراخوانی کنید.

2. برای ارائه اعتبارسنجی منظم برای دقت مداوم، حداقل یک بار در ماه با publishSubscriptionCluster تماس بگیرید.

   توجه: ازآنجایی‌که Google TV برای محافظت از حریم خصوصی کاربر، داده‌های قدیمی‌تر از ۶۰ روز را به‌طور خودکار حذف می‌کند، انتشار داده‌های اشتراک کاربر حداقل یک‌بار در ماه اعتبار داده‌ها را تأیید می‌کند. برخلاف publishContinuationCluster برای داده‌های ادامه تماشا، پرچم syncAcrossDevices را تنظیم نکنید، زیرا اطلاعات اشتراک به‌طور پیش‌فرض برای ارائه محتوا در همه دستگاه‌ها استفاده می‌شود.

3. برای حذف داده‌های Engage، داده‌های کاربر را به‌صورت دستی از سرور Google TV قبل‌از دوره نگهداری استاندارد ۶۰ روزه حذف کنید، از روش client.deleteClusters استفاده کنید. با این کار، همه داده‌های Engage موجود برای نمایه حساب یا برای کل حساب بسته به DeleteReason داده‌شده حذف می‌شود.

   تکه‌کد زیر نحوه برداشتن اشتراک کاربر را نشان می‌دهد:

   // If the user logs out from your media app, you must make the following call
   // to remove subscription and other Engage data from the current
   // google TV device.
   client.deleteClusters(
     DeleteClustersRequest.Builder()
       .setAccountProfile(accountProfile)
       .setDeleteReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
       .build()
   )
   

   تکه‌کد زیر نحوه حذف اشتراک کاربر را هنگامی که کاربر رضایت خود را لغو می‌کند نشان می‌دهد:

   // If the user revokes the consent to share across device, make the call
   // to remove subscription and other Engage data from all google
   // TV devices.
   client.deleteClusters(
     DeleteClustersRequest.Builder()
       .setAccountProfile(accountProfile)
       .setDeleteReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
       .build()
   )
   

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

   // If the user delete a specific profile, you must make the following call
   // to remove subscription data and other Engage data.
   client.deleteClusters(
     DeleteClustersRequest.Builder()
       .setAccountProfile(accountProfile)
       .setDeleteReason(DeleteReason.DELETE_REASON_ACCOUNT_PROFILE_DELETION)
       .build()
   )
   

آزمایش

این بخش راهنمای گام‌به‌گام برای آزمایش پیاده‌سازی اشتراک ارائه می‌دهد. پیش‌از راه‌اندازی، دقت داده‌ها و عملکرد صحیح را درستی‌سنجی کنید.

بازبینه یکپارچه‌سازی انتشار

1. انتشار باید زمانی اتفاق بیفتد که برنامه در پیش‌زمینه باشد و کاربر به‌طور فعال با آن تعامل داشته باشد.

2. زمان انتشار:

   • کاربر برای اولین‌بار به سیستم وارد می‌شود.
   • کاربر نمایه را تغییر می‌دهد (اگر نمایه‌ها پشتیبانی شوند).
   • کاربر اشتراک جدیدی می‌خرد.
   • کاربر اشتراک را ارتقا می‌دهد.
   • اشتراک کاربر منقضی می‌شود.

3. بررسی کنید که آیا برنامه به‌درستی میاناهای برنامه‌سازی کاربردی isServiceAvailable و publishClusters را در logcat، در رویدادهای انتشار، فراخوانی می‌کند.

4. بررسی کنید که داده‌ها در برنامه درستی‌سنجی قابل‌مشاهده باشند. برنامه درستی‌سنجی باید اشتراک را به‌عنوان ردیفی جداگانه نمایش دهد. وقتی API انتشار فراخوانده می‌شود، داده‌ها باید در برنامه درستی‌سنجی نشان داده شود.

   مهم: مطمئن شوید که پرچم سرویس Engage روی تولید تنظیم نشده باشد.

5. به برنامه بروید و هریک از کنش‌های زیر را انجام دهید:

   • به سیستم وارد شوید.
   • جابه‌جایی بین نمایه‌ها (درصورت پشتیبانی).
   • اشتراک جدیدی خریداری کنید.
   • اشتراک موجود را ارتقا دهید.
   • اشتراک را منقضی کنید.

درستی‌سنجی کردن ادغام

برای آزمایش کردن ادغام، از برنامه درستی‌سنجی استفاده کنید.

1. برای هریک از رویدادها، بررسی کنید که آیا برنامه publishSubscription API را فراخوانی کرده است یا نه. داده‌های منتشرشده را در برنامه درستی‌سنجی درستی‌سنجی کنید. درستی‌سنجی کنید که همه موارد در برنامه درستی‌سنجی سبز باشد

2. اگر همه اطلاعات نهاد درست باشد، علامت سبز «همه چیز خوب است» در همه نهادها نشان داده می‌شود.

   

   شکل ۱. اشتراک موفق

3. مشکلات در برنامه درستی‌سنجی نیز برجسته می‌شود

   

   شکل ۲.اشتراک ناموفق

4. برای دیدن مشکلات اشتراک بسته‌ای، بااستفاده از کنترل ازراه‌دور تلویزیون روی آن اشتراک بسته‌ای خاص تمرکز کنید و برای دیدن مشکلات کلیک کنید. ممکن است لازم باشد ابتدا روی ردیف تمرکز کنید و به راست بروید تا کارت «اشتراک بسته‌ای» را پیدا کنید. مشکلات با رنگ قرمز برجسته شده‌اند، همان‌طور که در شکل ۳ نشان داده شده است. همچنین، از کنترل ازراه‌دور برای رفتن به پایین و دیدن مشکلات مربوط به حقوق در اشتراک بسته‌ای استفاده کنید

   

   شکل ۳.خطاهای اشتراک

5. برای دیدن مشکلات موجود در حق استفاده، بااستفاده از کنترل از راه دور تلویزیون روی آن حق استفاده خاص تمرکز کنید و برای دیدن مشکلات کلیک کنید. مشکلات با رنگ قرمز برجسته شده‌اند.

   

   شکل ۴.جزئیات خطای اشتراک