แชร์การให้สิทธิ์ของแอปกับ Google TV โดยใช้ Engage SDK

คู่มือนี้มีวิธีการสำหรับนักพัฒนาแอปในการแชร์ข้อมูลการสมัครใช้บริการแอปและสิทธิ์กับ Google TV โดยใช้ Engage SDK ผู้ใช้จะค้นหาเนื้อหา ที่ตนมีสิทธิ์รับชมได้ และเปิดใช้ Google TV เพื่อให้แสดงคำแนะนำเนื้อหาที่เกี่ยวข้องสูง แก่ผู้ใช้ได้โดยตรงภายในประสบการณ์การใช้งาน Google TV บนทีวี อุปกรณ์เคลื่อนที่ และแท็บเล็ต

สิ่งที่ต้องมีก่อน

คุณต้องเริ่มต้นใช้งานฟีดการดำเนินการกับสื่อก่อนจึงจะใช้ Device Entitlement API ได้ หากยังไม่ได้ดำเนินการ ให้ทําตามกระบวนการเริ่มต้นใช้งานฟีดการกระทําเกี่ยวกับสื่อให้เสร็จสมบูรณ์

งานก่อนเริ่มเวิร์กช็อป

ก่อนที่จะเริ่ม ให้ทำตามขั้นตอนต่อไปนี้ ยืนยันว่าแอปกำหนดเป้าหมายเป็น API ระดับ 19 ขึ้นไปสำหรับการผสานรวมนี้

1. เพิ่มไลบรารี com.google.android.engage ลงในแอป

   มี SDK แยกต่างหากให้ใช้ในการผสานรวม โดย SDK หนึ่งสำหรับแอปบนอุปกรณ์เคลื่อนที่ และอีก 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

   สำหรับ 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 ให้ตั้งค่าสภาพแวดล้อมของบริการ Engage เป็น การใช้งานจริงในไฟล์ 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();

การสมัครใช้บริการ Premium

หากแอปเสนอแพ็กเกจการสมัครใช้บริการแบบพรีเมียมหลายระดับ ซึ่งรวมถึงเนื้อหาหรือฟีเจอร์เพิ่มเติมที่นอกเหนือจากระดับทั่วไป ให้แสดงสิ่งนี้โดยการเพิ่มสิทธิ์อย่างน้อย 1 รายการในการสมัครใช้บริการ

การให้สิทธิ์นี้มีช่องต่อไปนี้

1. ตัวระบุ: สตริงตัวระบุที่ต้องระบุสำหรับการให้สิทธิ์นี้ โดยต้องตรงกับตัวระบุสิทธิ์อย่างใดอย่างหนึ่ง (โปรดทราบว่านี่ไม่ใช่ ฟิลด์รหัส) ที่ระบุไว้ในฟีดของผู้ให้บริการสื่อที่เผยแพร่ไปยัง Google TV
2. ชื่อ: ข้อมูลนี้เป็นข้อมูลเสริมและใช้สำหรับการจับคู่การให้สิทธิ์ แม้จะไม่บังคับ แต่การระบุชื่อการให้สิทธิ์ที่มนุษย์อ่านได้จะช่วยเพิ่มความเข้าใจ เกี่ยวกับการให้สิทธิ์ผู้ใช้สำหรับทั้งนักพัฒนาแอปและทีมสนับสนุน เช่น Sling Orange
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() ซึ่งยอมรับรายการ ของการสมัครใช้บริการที่ลิงก์ไว้ เพื่อให้ผู้ใช้มีการสมัครใช้บริการที่ลิงก์ไว้ ตั้งแต่ 0 รายการขึ้นไป

เมื่อบริการได้รับคำขอ ระบบจะสร้างรายการใหม่และลบรายการเก่าโดยอัตโนมัติหลังจากผ่านไป 60 วัน ระบบจะใช้รายการล่าสุดเสมอ ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธคำขอทั้งหมดและคงสถานะเดิมไว้

อัปเดตการสมัครใช้บริการให้เป็นปัจจุบันอยู่เสมอ

1. หากต้องการให้ข้อมูลอัปเดตทันทีเมื่อมีการเปลี่ยนแปลง ให้เรียกใช้ publishSubscriptionCluster() ทุกครั้งที่สถานะการสมัครใช้บริการของผู้ใช้เปลี่ยนแปลง เช่น การเปิดใช้งาน การปิดใช้งาน การอัปเกรด การดาวน์เกรด

2. เรียกใช้ publishSubscriptionCluster() อย่างน้อยเดือนละครั้งเพื่อให้การตรวจสอบเป็นประจำเพื่อความแม่นยำอย่างต่อเนื่อง

3. หากต้องการลบข้อมูลการค้นพบวิดีโอ ให้ลบข้อมูลของผู้ใช้จากเซิร์ฟเวอร์ Google TV ด้วยตนเองก่อนระยะเวลาเก็บรักษามาตรฐาน 60 วันโดยใช้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 เป็นการใช้งานจริงในไฟล์ Android Manifest ของแอป
   • ติดตั้งและเปิดแอปการยืนยัน Engage
   • หากค่าของ isServiceAvailable เป็น false ในแอปยืนยัน ให้คลิกปุ่ม Toggle ภายในแอปยืนยันเพื่อตั้งค่าเป็น true
   • ป้อนชื่อแพ็กเกจของแอป ระบบจะแสดงข้อมูลที่เผยแพร่โดยอัตโนมัติ

5. ไปที่แอปและดำเนินการต่อไปนี้

   • ลงชื่อเข้าใช้
   • สลับไปมาระหว่างโปรไฟล์ (หากรองรับ)
   • ซื้อการสมัครใช้บริการใหม่
   • อัปเกรดการสมัครใช้บริการที่มีอยู่
   • การสมัครใช้บริการหมดอายุ

ยืนยันการผสานรวม

หากต้องการทดสอบการผสานรวม ให้ใช้แอปยืนยัน

แอปยืนยันเป็นแอปพลิเคชัน Android ที่นักพัฒนาแอปใช้เพื่อยืนยันว่าการผสานรวมทำงานได้ แอปมีความสามารถที่จะช่วย นักพัฒนาแอปยืนยันข้อมูลและออกอากาศ Intent ซึ่งจะช่วยยืนยันความถูกต้องของข้อมูล และการทํางานที่เหมาะสมก่อนเปิดตัว

1. สําหรับเหตุการณ์แต่ละรายการ ให้ตรวจสอบว่าแอปเรียกใช้ publishSubscription API หรือไม่ ยืนยันข้อมูลที่เผยแพร่ในแอปยืนยัน ตรวจสอบว่าทุกอย่างเป็นสีเขียวในแอปยืนยัน

2. หากข้อมูลของเอนทิตีทั้งหมดถูกต้อง ระบบจะแสดงเครื่องหมายถูกสีเขียว "เรียบร้อย" ในเอนทิตีทั้งหมด

   

3. นอกจากนี้ ปัญหาจะไฮไลต์ในแอปยืนยันด้วย

   

4. หากต้องการดูปัญหาในการสมัครใช้บริการแบบแพ็กเกจ ให้ใช้รีโมตทีวีเพื่อโฟกัส ที่การสมัครใช้บริการแบบแพ็กเกจนั้นๆ แล้วคลิกเพื่อดูปัญหา คุณอาจต้องโฟกัสที่แถวก่อน แล้วเลื่อนไปทางขวาเพื่อค้นหา การ์ดการสมัครใช้บริการแบบแพ็กเกจ โดยปัญหาจะไฮไลต์เป็นสีแดงดังที่แสดงใน รูปที่ 3 นอกจากนี้ ให้ใช้รีโมตเลื่อนลงเพื่อดูปัญหาในสิทธิ์ ในการสมัครใช้บริการแบบแพ็กเกจ

   

5. หากต้องการดูปัญหาในสิทธิ์ ให้ใช้รีโมตทีวีเพื่อโฟกัสที่สิทธิ์นั้นๆ แล้วคลิกเพื่อดูปัญหา ปัญหาจะ ไฮไลต์เป็นสีแดง