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

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

پیش نیازها

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

قبل از کار

قبل از شروع، مراحل زیر را تکمیل کنید. تأیید کنید که برنامه شما API سطح 19 یا بالاتر را برای این ادغام هدف قرار می دهد

  1. کتابخانه com.google.android.engage را به برنامه خود اضافه کنید:

    SDK های جداگانه ای برای استفاده در ادغام وجود دارد: یکی برای برنامه های تلفن همراه و دیگری برای برنامه های تلویزیون.

    برای موبایل 

    
  dependencies {
    implementation 'com.google.android.engage:engage-core:1.5.5
  }

    برای تلویزیون 

    
  dependencies {
    implementation 'com.google.android.engage:engage-tv:1.0.2
  }

  2. محیط سرویس Engage را در فایل AndroidManifest.xml روی production قرار دهید.

    برای apk موبایل 

    
<meta-data
      android:name="com.google.android.engage.service.ENV"
      android:value="PRODUCTION">
</meta-data>

    برای apk تلویزیون 

    
<meta-data
    android:name="com.google.android.engage.service.ENV"
    android:value="PRODUCTION">
</meta-data>

  3. قبل از ارسال APK به Google، محیط سرویس تعامل را در فایل AndroidManifest.xml روی تولید تنظیم کنید. برای عملکرد بهینه و سازگاری در آینده، داده‌ها را فقط زمانی منتشر کنید که برنامه در پیش‌زمینه باشد و کاربر فعالانه با آن تعامل داشته باشد، مانند راه‌اندازی برنامه، پس از ورود به سیستم یا در حین استفاده فعال. انتشار از فرآیندهای پس زمینه ممنوع است.

  4. انتشار اطلاعات اشتراک در رویدادهای زیر:

    1. کاربر به برنامه شما وارد می شود.
    2. کاربر بین پروفایل ها جابجا می شود (اگر پروفایل ها پشتیبانی شوند).
    3. کاربر یک اشتراک جدید خریداری می کند.
    4. کاربر اشتراک موجود را ارتقا می دهد.
    5. اشتراک کاربر منقضی می شود.

یکپارچه سازی

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

حساب کاربری و نمایه

برای مجاز کردن ویژگی‌های شخصی‌شده در Google TV، اطلاعات حساب را ارائه کنید. از AccountProfile برای ارائه موارد زیر استفاده کنید:

  1. شناسه حساب: یک شناسه منحصر به فرد که نمایانگر حساب کاربر است. این می تواند شناسه واقعی حساب یا یک نسخه مبهم مناسب باشد. 
// Set the account ID to which the subscription applies.
// Don't set the profile ID because subscription applies to account level.
val accountProfile = AccountProfile.Builder()
  .setAccountId("user_account_id")
  .setProfileId("user_profile id")
  .build();

اشتراک ردیف مشترک

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

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

    1. SUBSCRIPTION_TYPE_ACTIVE : کاربر اشتراک پولی فعال دارد.
    2. SUBSCRIPTION_TYPE_ACTIVE_TRIAL : کاربر اشتراک آزمایشی دارد.
    3. SUBSCRIPTION_TYPE_INACTIVE : کاربر یک حساب دارد اما اشتراک یا آزمایشی فعال ندارد.

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

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

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

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

اشتراک حق بیمه

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

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

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

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

"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 = Subscription
  .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 استفاده کنید.

از isServiceAvailable برای بررسی اینکه آیا سرویس برای یکپارچه سازی در دسترس است یا خیر استفاده کنید. 

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

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

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

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

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

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

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

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

    قطعه کد برای حذف اشتراک کاربر 

      // If the user logs out from your media app, you must make the following call
  // to remove subscription and other video discovery data from the current
  // google TV device.
  client.deleteClusters(
    new DeleteClustersRequest.Builder()
      .setAccountProfile(
        AccountProfile
          .Builder()
          .setAccountId()
          .setProfileId()
          .build()
      )
    .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
    .build()
    )
  ```
Following code snippet demonstrates removal of user subscription
when user revokes the consent.

```Kotlin
  // If the user revokes the consent to share across device, make the call
  // to remove subscription and other video discovery data from all google
  // TV devices.
  client.deleteClusters(
    new DeleteClustersRequest.Builder()
      .setAccountProfile(
        AccountProfile
        .Builder()
        .setAccountId()
        .setProfileId()
        .build()
      )
      .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
      .build()
  )
  ```

Following code demonstrates how to remove subscription data on user profile
deletion.

```Kotlin
// If the user delete a specific profile, you must make the following call
// to remove subscription data and other video discovery data.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
  .setAccountProfile(
    AccountProfile
    .Builder()
    .setAccountId()
    .setProfileId()
    .build()
  )
  .setReason(DeleteReason.DELETE_REASON_ACCOUNT_PROFILE_DELETION)
  .build()
)

تست کردن

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

چک لیست ادغام را منتشر کنید

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

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

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

  3. بررسی کنید که آیا برنامه به درستی APIهای isServiceAvailable() و publishClusters() در logcat را در رویدادهای انتشار صدا می کند یا خیر.

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

    • بررسی کنید که Engage Service Flag روی تولید در فایل Manifest Android برنامه تنظیم نشده باشد.
    • برنامه Engage Verification را نصب و باز کنید.
    • اگر مقدار isServiceAvailable در برنامه تأیید false است، روی دکمه Toggle در برنامه تأیید کلیک کنید تا آن را روی true تنظیم کنید.
    • نام بسته برنامه را وارد کنید. به طور خودکار داده های منتشر شده را نشان می دهد.

  5. به برنامه بروید و هر یک از اقدامات زیر را انجام دهید:

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

ادغام را تأیید کنید

برای آزمایش ادغام خود، از برنامه تأیید استفاده کنید.

برنامه تأیید یک برنامه اندروید است که توسعه دهندگان می توانند از آن برای تأیید اینکه یکپارچه سازی کار می کند استفاده کنند. این برنامه دارای قابلیت هایی برای کمک به توسعه دهندگان برای تأیید داده ها و اهداف پخش است. این کمک می کند تا صحت داده ها و عملکرد مناسب را قبل از راه اندازی تأیید کنید.

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

  2. اگر تمام اطلاعات موجودیت صحیح باشد، علامت سبز رنگ "All Good" را در همه موجودیت ها نشان می دهد.

    نماگرفت موفقیت برنامه تأیید
    شکل 1. اشتراک موفق

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

    تصویر صفحه خطای تأیید برنامه
    شکل 2. اشتراک ناموفق

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

    نماگرفت جزئیات خطای برنامه تأیید صحت
    شکل 3. خطاهای اشتراک

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

    تصویر صفحه خطای تأیید برنامه
    شکل 4. جزئیات خطای اشتراک