مسیر_کتاب: /distribute/other-docs/_book.yaml مسیر_پروژه: /distribute/other-docs/_project.yaml
این راهنما شامل دستورالعملهایی برای توسعهدهندگان است تا دادههای اشتراک و حق اشتراک برنامه را با استفاده از Engage SDK با Google TV به اشتراک بگذارند. کاربران میتوانند محتوای مورد نظر خود را پیدا کنند و Google TV را قادر سازند تا توصیههای محتوای بسیار مرتبط را مستقیماً از طریق تجربیات Google TV در تلویزیون، موبایل و تبلت به کاربران ارائه دهد.
پیشنیازها
قبل از اینکه بتوانید از API مربوط به تعیین حق دسترسی دستگاه استفاده کنید، لازم است که فید اقدامات رسانهای را فعال کنید. اگر هنوز این کار را انجام ندادهاید، فرآیند فعالسازی فید اقدامات رسانهای را تکمیل کنید.
پیش کار
دستورالعملهای پیش از کار را در راهنمای شروع به کار تکمیل کنید.
- اطلاعات اشتراک مربوط به رویدادهای زیر را منتشر کنید:
- کاربر وارد برنامه شما میشود.
- کاربر بین پروفایلها جابجا میشود (در صورت پشتیبانی از پروفایلها).
- کاربر یک اشتراک جدید خریداری میکند.
- کاربر اشتراک موجود خود را ارتقا میدهد.
- اشتراک کاربر منقضی میشود.
ادغام
این بخش، مثالهای کد و دستورالعملهای لازم برای پیادهسازی SubscriptionEntity جهت مدیریت انواع مختلف اشتراک را ارائه میدهد.
اشتراک سطح مشترک
برای کاربرانی که اشتراک پایه در سرویسهای ارائهدهنده رسانه دارند، مثلاً سرویسی که یک سطح اشتراک دارد و به تمام محتوای پولی دسترسی میدهد، این جزئیات ضروری را ارائه دهید:
SubscriptionType: به طور واضح طرح اشتراک خاصی که کاربر دارد را مشخص کنید.-
SUBSCRIPTION_TYPE_ACTIVE: کاربر یک اشتراک پولی فعال دارد. -
SUBSCRIPTION_TYPE_ACTIVE_TRIAL: کاربر اشتراک آزمایشی دارد. -
SUBSCRIPTION_TYPE_INACTIVE: کاربر حساب کاربری دارد اما اشتراک فعال یا نسخه آزمایشی ندارد.
-
ExpirationTimeMillis: زمان اختیاری بر حسب میلیثانیه. مشخص کنید که اشتراک چه زمانی منقضی شود.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()
اشتراک ویژه
اگر برنامه بستههای اشتراک ویژه چند سطحی ارائه میدهد که شامل محتوا یا ویژگیهای گستردهتر فراتر از سطح مشترک است، این را با اضافه کردن یک یا چند حق اشتراک به اشتراک نشان دهید.
این مجوز دارای فیلدهای زیر است:
-
Identifier: رشته شناسه مورد نیاز برای این حق پخش. این باید با یکی از شناسههای حق پخش (توجه داشته باشید که این فیلد شناسه نیست) ارائه شده در فید ارائه دهنده رسانه منتشر شده در Google TV مطابقت داشته باشد. -
Name: این یک اطلاعات کمکی است و برای تطبیق حق دسترسی استفاده میشود. اگرچه اختیاری است، اما ارائه یک نام حق دسترسی خوانا برای انسان، درک حق دسترسیهای کاربر را هم برای توسعهدهندگان و هم برای تیمهای پشتیبانی افزایش میدهد. به عنوان مثال: Sling Orange. -
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 = 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 استفاده کنید.
حتماً کلاینت را راهاندازی اولیه کنید و همانطور که در راهنمای شروع به کار توضیح داده شده است، در دسترس بودن سرویس را بررسی کنید.
client.publishSubscription(
PublishSubscriptionRequest.Builder()
.setAccountProfile(accountProfile)
.setSubscription(subscription)
.build()
)
از setSubscription() برای تأیید اینکه کاربر فقط باید یک اشتراک در سرویس داشته باشد، استفاده کنید.
برای اینکه کاربر بتواند هیچ یا چند اشتراک لینکشده داشته باشد، addLinkedSubscription() یا addLinkedSubscriptions() که فهرستی از اشتراکهای لینکشده را میپذیرند، استفاده کنید.
وقتی سرویس درخواست را دریافت میکند، یک ورودی جدید ایجاد میشود و ورودی قدیمی پس از ۶۰ روز به طور خودکار حذف میشود. سیستم همیشه از آخرین ورودی استفاده میکند. در صورت بروز خطا، کل درخواست رد میشود و وضعیت موجود حفظ میشود.
اشتراک را بهروز نگه دارید
برای ارائه بهروزرسانیهای فوری پس از تغییرات، هر زمان که وضعیت اشتراک کاربر مانند فعالسازی، غیرفعالسازی، ارتقاء یا تنزل رتبه تغییر کند، تابع
publishSubscriptionClusterرا فراخوانی کنید.برای اعتبارسنجی منظم و دقیق، حداقل ماهی یک بار
publishSubscriptionClusterتماس بگیرید.برای حذف دادههای کشف ویدیو، دادههای کاربر را قبل از دوره نگهداری استاندارد ۶۰ روزه، به صورت دستی از سرور 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) .setReason(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 video discovery data from all google // TV devices. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile(accountProfile) .setReason(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 video discovery data. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile(accountProfile) .setReason(DeleteReason.DELETE_REASON_ACCOUNT_PROFILE_DELETION) .build() )
آزمایش
این بخش یک راهنمای گام به گام برای آزمایش پیادهسازی اشتراک ارائه میدهد. قبل از راهاندازی، صحت دادهها و عملکرد مناسب را تأیید کنید.
چک لیست ادغام را منتشر کنید
انتشار باید زمانی اتفاق بیفتد که برنامه در پیشزمینه قرار دارد و کاربر به طور فعال با آن تعامل دارد.
منتشر شدن در چه زمانی:
- کاربر برای اولین بار وارد سیستم میشود.
- کاربر نمایه را تغییر میدهد (در صورت پشتیبانی از نمایهها).
- کاربر اشتراک جدید خریداری میکند.
- کاربر اشتراک را ارتقا میدهد.
- اشتراک کاربر منقضی میشود.
بررسی کنید که آیا برنامه به درستی APIهای
isServiceAvailable()وpublishClusters()را در logcat، در رویدادهای انتشار، فراخوانی میکند یا خیر.تأیید کنید که دادهها در برنامه تأیید قابل مشاهده هستند. برنامه تأیید باید اشتراک را به عنوان یک ردیف جداگانه نمایش دهد. وقتی API انتشار فراخوانی میشود، دادهها باید در برنامه تأیید نمایش داده شوند.
به برنامه بروید و هر یک از اقدامات زیر را انجام دهید:
- وارد سیستم شوید.
- جابجایی بین پروفایلها (در صورت پشتیبانی).
- اشتراک جدید خریداری کنید.
- اشتراک موجود را ارتقا دهید.
- اشتراک را منقضی کنید.
تأیید ادغام
برای آزمایش ادغام خود، از برنامه تأیید استفاده کنید.
- برای هر یک از رویدادها، بررسی کنید که آیا برنامه، API
publishSubscriptionرا فراخوانی کرده است یا خیر. دادههای منتشر شده را در برنامه تأیید صحت، تأیید کنید. در برنامه تأیید صحت، مطمئن شوید که همه چیز سبز است. اگر تمام اطلاعات موجودیت صحیح باشد، در تمام موجودیتها تیک سبز «کاملاً خوب» را نشان میدهد.
شکل ۱. اشتراک موفق مشکلات در برنامه تأیید نیز برجسته شدهاند
شکل ۲. اشتراک ناموفق بود برای مشاهده مشکلات اشتراک همراه، از کنترل تلویزیون برای تمرکز روی آن اشتراک همراه خاص استفاده کنید و برای مشاهده مشکلات کلیک کنید. ممکن است ابتدا لازم باشد روی ردیف تمرکز کنید و به سمت راست بروید تا کارت اشتراک همراه را پیدا کنید. مشکلات همانطور که در شکل 3 نشان داده شده است، با رنگ قرمز برجسته شدهاند. همچنین، از کنترل برای حرکت به پایین استفاده کنید تا مشکلات مربوط به حقوق در اشتراک همراه را مشاهده کنید.
شکل ۳. خطاهای اشتراک برای مشاهده مشکلات مربوط به هر بخش، از کنترل تلویزیون برای تمرکز روی آن بخش خاص استفاده کنید و برای مشاهده مشکلات کلیک کنید. مشکلات با رنگ قرمز مشخص شدهاند.
شکل ۴. جزئیات خطای اشتراک