Udostępnianie uprawnień do aplikacji w Google TV za pomocą pakietu Engage SDK

book_path: /distribute/other-docs/_book.yaml project_path: /distribute/other-docs/_project.yaml

Ten przewodnik zawiera instrukcje dla deweloperów dotyczące udostępniania danych o subskrypcjach i uprawnieniach w aplikacji w Google TV za pomocą pakietu Engage SDK. Użytkownicy mogą znaleźć treści, do których mają dostęp, i włączyć Google TV, aby otrzymywać bardzo trafne rekomendacje treści bezpośrednio w Google TV na telewizorze, telefonie komórkowym i tablecie.

Wymagania wstępne

Zanim zaczniesz korzystać z interfejsu Device Entitlement API, musisz przejść proces wprowadzania do kanału działań związanych z multimediami. Jeśli jeszcze tego nie zrobiono, przeprowadź proces wprowadzania pliku danych z działaniami dotyczącymi multimediów.

Przygotowanie

Wykonaj instrukcje z sekcji Przygotowania w przewodniku dla początkujących.

1. Publikuj informacje o subskrypcji w przypadku tych zdarzeń:
   1. Użytkownik loguje się w Twojej aplikacji.
   2. Użytkownik przełącza się między profilami (jeśli są one obsługiwane).
   3. Użytkownik kupuje nową subskrypcję.
   4. Użytkownik przenosi obecną subskrypcję na wyższą wersję.
   5. Subskrypcja użytkownika wygasa.

Integracja

W tej sekcji znajdziesz przykłady kodu i instrukcje wdrażania SubscriptionEntity do zarządzania różnymi typami subskrypcji.

Subskrypcja na poziomie wspólnym

W przypadku użytkowników z podstawową subskrypcją usług dostawców treści, np. usługi z jednym poziomem subskrypcji, który zapewnia dostęp do wszystkich płatnych treści, podaj te podstawowe informacje:

1. SubscriptionType: wyraźnie wskazywać konkretny abonament, z którego korzysta użytkownik;

   • SUBSCRIPTION_TYPE_ACTIVE: użytkownik ma aktywną płatną subskrypcję.
   • SUBSCRIPTION_TYPE_ACTIVE_TRIAL: użytkownik ma subskrypcję próbną.
   • SUBSCRIPTION_TYPE_INACTIVE: użytkownik ma konto, ale nie ma aktywnej subskrypcji ani okresu próbnego.

2. ExpirationTimeMillis: opcjonalny czas w milisekundach. Określ, kiedy subskrypcja ma wygasnąć.

3. ProviderPackageName: Określ nazwę pakietu aplikacji, która obsługuje subskrypcję.

Przykład przykładowego pliku danych dostawcy mediów

"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
  }

W tym przykładzie tworzymy SubscriptionEntity dla użytkownika:

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

Subskrypcja Premium

Jeśli aplikacja oferuje wielopoziomowe pakiety subskrypcji premium, które obejmują rozszerzone treści lub funkcje wykraczające poza zwykły poziom, dodaj do subskrypcji co najmniej 1 uprawnienie.

To uprawnienie ma te pola:

1. Identifier: Wymagany ciąg identyfikatora tego uprawnienia. Musi on być zgodny z jednym z identyfikatorów uprawnień (uwaga: nie jest to pole identyfikatora) podanych w pliku danych dostawcy treści opublikowanym w Google TV.
2. Name: są to informacje dodatkowe, które służą do dopasowywania uprawnień. Podanie nazwy uprawnienia w formie czytelnej dla człowieka jest opcjonalne, ale zwiększa zrozumienie uprawnień użytkowników zarówno przez programistów, jak i zespoły pomocy. Na przykład Sling Orange.
3. ExpirationTimeMillis: Opcjonalnie podaj czas wygaśnięcia tego uprawnienia w milisekundach, jeśli różni się on od czasu wygaśnięcia subskrypcji. Domyślnie uprawnienie wygaśnie wraz z wygaśnięciem subskrypcji.

Dla tego przykładowego fragmentu pliku danych dostawcy mediów:

"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"
  }

Poniższy przykład tworzy SubscriptionEntity dla subskrybującego użytkownika:

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

Subskrypcja pakietu połączonych usług

Subskrypcje należą zwykle do dostawcy treści aplikacji, z której pochodzą, ale można je przypisać do połączonego pakietu usług, podając nazwę tego pakietu w subskrypcji.

Poniższy przykładowy kod pokazuje, jak utworzyć subskrypcję użytkownika.

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

Jeśli użytkownik ma inną subskrypcję usługi dodatkowej, dodaj kolejną subskrypcję i odpowiednio ustaw nazwę pakietu połączonej usługi.

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

Opcjonalnie możesz też dodać uprawnienia do połączonej subskrypcji usługi.

Podaj zestaw subskrypcji

Uruchom zadanie publikowania treści, gdy aplikacja działa na pierwszym planie.

Aby opublikować obiekt SubscriptionCluster, użyj metody publishSubscriptionCluster() z klasy AppEngagePublishClient.

Zainicjuj klienta i sprawdź dostępność usługi zgodnie z opisem w Przewodniku dla początkujących.

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

Użyj setSubscription(), aby sprawdzić, czy użytkownik powinien mieć tylko jedną subskrypcję usługi.

Użyj addLinkedSubscription() lub addLinkedSubscriptions(), które akceptują listę połączonych subskrypcji, aby umożliwić użytkownikowi posiadanie zera lub większej liczby połączonych subskrypcji.

Gdy usługa otrzyma prośbę, utworzy nowy wpis, a stary wpis zostanie automatycznie usunięty po 60 dniach. System zawsze używa najnowszego wpisu. W przypadku błędu całe żądanie jest odrzucane, a dotychczasowy stan jest zachowywany.

Dbaj o aktualność subskrypcji

1. Aby natychmiast informować o zmianach, wywołuj funkcję publishSubscriptionCluster za każdym razem, gdy zmieni się stan subskrypcji użytkownika, np. w przypadku aktywacji, dezaktywacji, uaktualnienia lub obniżenia wersji.

2. Aby regularnie weryfikować bieżącą dokładność, wywołuj funkcję publishSubscriptionCluster co najmniej raz w miesiącu.

3. Aby usunąć dane dotyczące odkrywania filmów, przed upływem standardowego 60-dniowego okresu przechowywania ręcznie usuń dane użytkownika z serwera Google TV, korzystając z client.deleteClusterstej metody. Spowoduje to usunięcie wszystkich dotychczasowych danych dotyczących odkrywania filmów z profilu konta lub z całego konta w zależności od podanego parametru DeleteReason.

   Ten fragment kodu pokazuje, jak usunąć subskrypcję użytkownika:

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

   Poniższy fragment kodu pokazuje usuwanie subskrypcji użytkownika, gdy wycofa on zgodę:

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

   Poniższy kod pokazuje, jak usunąć dane subskrypcji po usunięciu profilu użytkownika.

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

Testowanie

W tej sekcji znajdziesz szczegółowe instrukcje testowania wdrożenia subskrypcji. Przed uruchomieniem sprawdź dokładność danych i prawidłowe działanie.

Lista kontrolna publikowania integracji

1. Publikowanie powinno następować, gdy aplikacja jest na pierwszym planie, a użytkownik aktywnie z niej korzysta.

2. Opublikuj, gdy:

   • Użytkownik loguje się po raz pierwszy.
   • Użytkownik zmienia profil (jeśli profile są obsługiwane).
   • Użytkownik kupuje nową subskrypcję.
   • Użytkownik przechodzi na wyższą subskrypcję.
   • Subskrypcja użytkownika wygasa.

3. Sprawdź, czy aplikacja prawidłowo wywołuje interfejsy API isServiceAvailable() i publishClusters() w logcat podczas publikowania zdarzeń.

4. Sprawdź, czy dane są widoczne w aplikacji weryfikacyjnej. Subskrypcja powinna być wyświetlana w aplikacji weryfikacyjnej w osobnym wierszu. Gdy wywołasz interfejs API publikowania, dane powinny pojawić się w aplikacji weryfikacyjnej.

5. Otwórz aplikację i wykonaj te czynności:

   • Zaloguj się.
   • przełączanie się między profilami (jeśli jest to obsługiwane);
   • kupić nowy abonament,
   • przejść na wyższą wersję subskrypcji,
   • Wygaśnięcie subskrypcji.

Weryfikowanie integracji

Aby przetestować integrację, użyj aplikacji weryfikacyjnej.

1. W przypadku każdego zdarzenia sprawdź, czy aplikacja wywołała interfejs API publishSubscription. Sprawdź opublikowane dane w aplikacji weryfikacyjnej. Sprawdź, czy w aplikacji weryfikacyjnej wszystko jest oznaczone na zielono

2. Jeśli wszystkie informacje o firmie są prawidłowe, przy wszystkich firmach pojawi się zielony znacznik wyboru „Wszystko w porządku”.

   

3. Problemy są też wyróżnione w aplikacji weryfikacyjnej

   

4. Aby zobaczyć problemy w pakiecie subskrypcji, użyj pilota do telewizora, aby skupić się na konkretnym pakiecie subskrypcji, a następnie kliknij, aby wyświetlić problemy. Najpierw możesz musieć skupić się na wierszu i przesunąć w prawo, aby znaleźć kartę Subskrypcja w pakiecie. Problemy są wyróżnione na czerwono, jak pokazano na rysunku 3. Użyj pilota, aby przewinąć w dół i zobaczyć problemy z uprawnieniami w ramach subskrypcji pakietowej.

   

5. Aby zobaczyć problemy z uprawnieniem, użyj pilota do telewizora, aby skupić się na tym konkretnym uprawnieniu, a następnie kliknij, aby wyświetlić problemy. Problemy są wyróżnione na czerwono.