Przewodnik po integracji pakietu Engage SDK z telewizorami

.

Kontynuuj oglądanie korzysta z grupy kontynuacji, aby wyświetlać niedokończone filmy i następne odcinki z tego samego sezonu serialu z różnych aplikacji w jednym układzie. Możesz wyróżnić ich elementy w tym klastrze kontynuacji. Z tego przewodnika dowiesz się, jak zwiększyć zaangażowanie użytkowników za pomocą funkcji Kontynuuj oglądanie za pomocą pakietu Engage SDK.

Krok 1. Przygotowanie

Zanim zaczniesz, wykonaj te czynności:

Upewnij się, że w przypadku tej integracji aplikacja jest kierowana na interfejs API na poziomie 19 lub wyższym.

  1. Dodaj bibliotekę com.google.android.engage do aplikacji:

    Do integracji służą osobne pakiety SDK: jeden do aplikacji mobilnych, a drugi do aplikacji na telewizory.

    Telefon

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

    TV

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

  2. W pliku AndroidManifest.xml ustaw środowisko usługi Engage na produkcyjne.

    Telefon

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

    TV

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

  3. Dodawanie uprawnień WRITE_EPG_DATA do pliku APK na telewizory

      <uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />

  4. Zaplanuj publikowanie treści, korzystając z usługi działającej w tle, takiej jak androidx.work.

  5. Aby zapewnić płynne oglądanie, publikuj dane dotyczące kontynuowania oglądania, gdy występują te zdarzenia:

    1. Pierwsze logowanie: gdy użytkownik loguje się po raz pierwszy, opublikowanie jego danych sprawia, że historia oglądania jest od razu dostępna.
    2. Tworzenie lub przełączanie profili (aplikacje obsługujące wiele profili): jeśli Twoja aplikacja obsługuje wiele profili, publikuj dane, gdy użytkownik tworzy lub przełącza profile. Dzięki temu każdy użytkownik może korzystać z usługi w spersonalizowany sposób.
    3. Przerwanie odtwarzania filmu: aby pomóc użytkownikom wznowić odtwarzanie od miejsca, w którym zostało przerwane, publikuj dane, gdy użytkownik wstrzyma lub zatrzyma film albo zamknie aplikację podczas odtwarzania.
    4. Aktualizacje sekcji Kontynuuj oglądanie (jeśli jest obsługiwana): gdy użytkownik usunie element z sekcji Kontynuuj oglądanie, odzwierciedl tę zmianę, publikując zaktualizowane dane. Dzięki temu ten element pozostaje trafny i spersonalizowany.
    5. Zakończenie filmu:
      1. W przypadku filmów usuń ukończony film z panelu Kontynuuj oglądanie. Jeśli film jest częścią serii, dodaj następny film, aby utrzymać zaangażowanie użytkownika.
      2. W przypadku odcinków usuń ukończony odcinek i dodaj następny odcinek z serii, jeśli jest dostępny, aby zachęcić do dalszego oglądania.

Integracja

AccountProfile

Aby umożliwić spersonalizowane korzystanie z funkcji „Kontynuuj oglądanie” w Google TV, podaj informacje o koncie i profilu. Użyj obiektu AccountProfile, aby podać:

  1. Identyfikator konta: unikalny identyfikator reprezentujący konto użytkownika w aplikacji. Może to być rzeczywisty identyfikator konta lub jego zaciemniona wersja.

  2. Identyfikator profilu (opcjonalnie): jeśli Twoja aplikacja obsługuje wiele profili na jednym koncie, podaj unikalny identyfikator konkretnego profilu użytkownika (może to być prawdziwy identyfikator lub zafałszowany).

// If your app only supports account
val accountProfile = AccountProfile.Builder()
      .setAccountId("your_users_account_id")
      .build()
// If your app supports both account and profile
val accountProfile = AccountProfile.Builder()
      .setAccountId("your_users_account_id")
      .setProfileId("your_users_profile_id")
.build()

Tworzenie encji

Pakiet SDK definiuje różne elementy, które reprezentują poszczególne typy elementów. Klaster kontynuacji obsługuje te typy jednostek:

  1. MovieEntity
  2. TvEpisodeEntity
  3. LiveStreamingVideoEntity
  4. VideoClipEntity

Podaj identyfikatory URI i obrazy plakatu tych elementów w przypadku poszczególnych platform.

Utwórz też URI odtwarzania dla każdej platformy, np. Android TV, Android lub iOS. Gdy użytkownik będzie kontynuować oglądanie na każdej platformie, aplikacja będzie używać do odtwarzania treści docelowego identyfikatora URI odtwarzania.

// Required. Set this when you want continue watching entities to show up on
// Google TV
val playbackUriTv =
          PlatformSpecificUri.Builder()
              .setPlatformType(PlatformType.TYPE_ANDROID_TV)
              .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
              .build()

// Required. Set this when you want continue watching entities to show up on
// Google TV Android app, Entertainment Space, Playstore Widget
val playbackUriAndroid =
          PlatformSpecificUri.Builder()
              .setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
              .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
              .build()
// Optional. Set this when you want continue watching entities to show up on
// Google TV iOS app
val playbackUriIos =
          PlatformSpecificUri.Builder()
              .setPlatformType(PlatformType.TYPE_IOS)
              .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
              .build()
 val platformSpecificPlaybackUris =
          Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)

Obrazy plakatu wymagają identyfikatora URI i wymiarów w pikselach (wysokość i szerokość). Ukierunkowuj reklamę na różne formaty, przesyłając wiele obrazów z plakatem, ale pamiętaj, aby wszystkie obrazy miały współczynnik proporcji 16:9 i minimalną wysokość 200 pikseli, aby można było prawidłowo wyświetlać element „Ciąg dalszego oglądania”, zwłaszcza w miejscu na treści rozrywkowe w Google. Obrazy o wysokości mniejszej niż 200 pikseli mogą nie być wyświetlane.


Image image1 = new Image.Builder()
            .setImageUri(Uri.parse("http://www.example.com/entity_image1.png");)
            .setImageHeightInPixel(300)
            .setImageWidthInPixel(169)
            .build()
Image image2 = new Image.Builder()
            .setImageUri(Uri.parse("http://www.example.com/entity_image2.png");)
            .setImageHeightInPixel(640)
            .setImageWidthInPixel(360)
            .build()
// And other images for different form factors.
val images = Arrays.asList(image1, image2)
MovieEntity

Ten przykład pokazuje, jak utworzyć MovieEntity ze wszystkimi wymaganymi polami:

val movieEntity = MovieEntity.Builder()
   .setWatchNextType(WatchNextType.TYPE_CONTINUE)
   .setName("Movie name")
   .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
   .addPosterImages(images)
   // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
   .setLastEngagementTimeMillis(1701388800000)
   // Suppose the duration is 2 hours, it is 72000000 in milliseconds
   .setDurationMills(72000000)
   // Suppose last playback offset is 1 hour, 36000000 in milliseconds
   .setLastPlayBackPositionTimeMillis(36000000)
   .build()

Podanie szczegółów takich jak gatunki i oceny treści umożliwia Google TV prezentowanie Twoich treści w bardziej dynamiczny sposób i dotarcie do odpowiednich widzów.

val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build();
val contentRatings = Arrays.asList(rating1);
val movieEntity = MovieEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .build()

Elementy są automatycznie dostępne przez 60 dni, chyba że określisz krótszy czas ważności. Ustaw datę wygaśnięcia tylko wtedy, gdy chcesz usunąć element przed tym domyślnym okresem.

// Set the expiration time to be now plus 30 days in milliseconds
val expirationTime = new DisplayTimeWindow.Builder()
             .setEndTimestampMillis(now().toMillis()+2592000000).build()
val movieEntity = MovieEntity.Builder()
    ...
    .addAvailabilityTimeWindow(expirationTime)
    .build()
TvEpisodeEntity

Ten przykład pokazuje, jak utworzyć TvEpisodeEntity ze wszystkimi wymaganymi polami:

val tvEpisodeEntity = TvEpisodeEntity.Builder()
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Episode name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) // 2 hours in milliseconds
    // 45 minutes and 15 seconds in milliseconds is 2715000
    .setLastPlayBackPositionTimeMillis(2715000)
    .setEpisodeNumber("2")
    .setSeasonNumber("1")
    .setShowTitle("Title of the show")
    .build();

Ciąg znaków z numerem odcinka (np. "2") i ciąg znaków z numerem sezonu (np. "1") zostanie rozwinięty do odpowiedniej formy przed wyświetleniem na karcie „Kontynuuj oglądanie”. Pamiętaj, że powinny to być ciągi znaków liczbowych. Nie wpisuj „e2”, „episode 2”, „s1” ani „season 1”.

Jeśli dany serial ma tylko jeden sezon, ustaw jego numer na 1.

Aby zwiększyć szanse widzów na znalezienie Twoich treści w Google TV, rozważ podanie dodatkowych danych, takich jak gatunki, oceny treści i okresy dostępności. Te informacje mogą ulepszyć wyświetlanie i opcje filtrowania.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val tvEpisodeEntity = TvEpisodeEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .setSeasonTitle("Season Title")
    .setShowTitle("Show Title)
    .build();
VideoClipEntity

Oto przykład tworzenia obiektu VideoClipEntity ze wszystkimi polami wymaganymi.

VideoClipEntity oznacza klip utworzony przez użytkownika, np. film w YouTube.

val videoClipEntity = VideoClipEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Video clip name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(600000) //10 minutes in milliseconds
    .setLastPlayBackPositionTimeMillis(300000) //5 minutes in milliseconds
    .addContentRating(contentRating)
    .build();

Opcjonalnie możesz ustawić twórcę, obraz twórcy, czas utworzenia w milisekundach lub okno dostępności .

LiveStreamingVideoEntity

Oto przykład utworzenia obiektu LiveStreamingVideoEntity ze wszystkimi polami wymaganymi.

val liveStreamingVideoEntity = LiveStreamingVideoEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Live streaming name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) //2 hours in milliseconds
    .setLastPlayBackPositionTimeMillis(36000000) //1 hour in milliseconds
    .addContentRating(contentRating)
    .build();

Opcjonalnie możesz ustawić czas rozpoczęcia, nadawcę, ikonę nadawcy lub przedział czasu dostępności dla treści dostępnych w ramach transmisji na żywo.

Szczegółowe informacje o atrybutach i wymaganiach znajdziesz w dokumentacji interfejsu API.

Przekazywanie danych klastra kontynuacji

AppEngagePublishClient odpowiada za publikowanie klastra kontynuacji. do publikowania obiektu ContinuationCluster używasz metody publishContinuationCluster().

Najpierw użyj funkcji isServiceAvailable(), aby sprawdzić, czy usługa jest dostępna do integracji.

client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster
                .Builder()
                .setAccountProfile(accountProfile)
                .addEntity(movieEntity1)
                .addEntity(movieEntity2)
                .addEntity(tvEpisodeEntity1)
                .addEntity(tvEpisodeEntity2)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build();
)

Gdy usługa otrzyma żądanie, w ramach jednej transakcji zostaną wykonane te działania:

  • Istniejące dane ContinuationCluster od partnera dewelopera zostaną usunięte.
  • Dane z żądania są analizowane i przechowywane w zaktualizowanym pliku ContinuationCluster.

W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.

Interfejsy API publikowania to interfejsy API upsert; zastępują one istniejące treści. Jeśli musisz zaktualizować konkretny element w grupie kontynuacji, musisz ponownie opublikować wszystkie elementy.

Dane z kont ContinuationCluster powinny być podawane tylko w przypadku kont należących do osób dorosłych. publikować tylko wtedy, gdy profil konta należy do osoby dorosłej;

Synchronizacja na różnych urządzeniach

Flaga synchronizacji między urządzeniami

Ten parametr określa, czy dane ContinuationCluster użytkownika są synchronizowane na jego urządzeniach (telewizor, telefon, tablet itp.). Domyślnie jest ustawiona wartość fałsz, co oznacza, że synchronizacja na różnych urządzeniach jest domyślnie wyłączona.

Wartości:

  • prawda: dane z grupy kontynuacji są udostępniane na wszystkich urządzeniach użytkownika, aby zapewnić płynne oglądanie. Zdecydowanie zalecamy tę opcję, aby zapewnić sobie jak najlepsze działanie na różnych urządzeniach.
  • false: dane z ContinuationCluster są ograniczone do bieżącego urządzenia.

Aplikacja multimedialna musi zawierać wyraźne ustawienie umożliwiające włączanie i wyłączanie synchronizacji między urządzeniami. Wyjaśnij użytkownikowi korzyści i zapisz jego preferencje, aby zastosować je w ramach publikowania ContinuationCluster.

// Example to allow cross device syncing.
client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster
                .Builder()
                .setAccountProfile(accountProfile)
                .setSyncAcrossDevices(true)
                .build();
        )
        .build();
)

Aby w pełni korzystać z funkcji obsługiwanej na wielu urządzeniach, upewnij się, że Twoja aplikacja uzyskuje zgodę użytkownika, a wartość opcji SyncAcrossDevices jest ustawiona na „true”. Dzięki temu treści są płynnie synchronizowane na różnych urządzeniach, co przekłada się na lepsze wrażenia użytkowników i większe zaangażowanie. Na przykład jeden z partnerów, który wdrożył tę funkcję, odnotował wzrost liczby kliknięć przycisku „Ciąg dalszego oglądania” o 40%, ponieważ jego treści były wyświetlane na wielu urządzeniach.

Usuwanie danych z reklam wideo Discovery

Aby ręcznie usunąć dane użytkownika z serwera Google TV przed standardowym okresem przechowywania wynoszącym 60 dni, użyj metody client.deleteClusters(). Po otrzymaniu prośby usługa usunie wszystkie istniejące dane dotyczące odkrywania filmów na profilu konta lub na całym koncie.

Wyliczenie DeleteReason określa powód usunięcia danych. Poniższy kod usuwa dane dotyczące kontynuowania oglądania po wylogowaniu.


// If the user logs out from your media app, you must make the following call
// to remove continue watching data from the current google TV device,
// otherwise, the continue watching data will persist on the current
// google TV device until 60 days later.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

Testowanie

Użyj aplikacji do weryfikacji, aby sprawdzić, czy integracja pakietu Engage SDK działa prawidłowo. Ta aplikacja na Androida zawiera narzędzia, które pomogą Ci zweryfikować dane i sprawdzić, czy intencje transmisji są obsługiwane prawidłowo.

Po wywołaniu interfejsu API publikowania sprawdź, czy dane są prawidłowo publikowane, sprawdzając aplikację weryfikacyjną. Klaster kontynuacji powinien być wyświetlany jako osobny wiersz w interfejsie aplikacji.

  • Upewnij się, że flaga usługi Engage NIE jest ustawiona na produkcję w pliku manifestu Androida aplikacji.
  • Zainstaluj i otwórz aplikację Engage Verify.
  • Jeśli isServiceAvailable = false, kliknij przycisk „Przełącz”, aby włączyć tę opcję.
  • Wpisz nazwę pakietu aplikacji, aby automatycznie wyświetlać opublikowane dane po rozpoczęciu publikowania.
  • Przetestuj te działania w aplikacji:
    • Zaloguj się.
    • przełączać się między profilami(w razie potrzeby).
    • Rozpocznij, a następnie wstrzymaj film lub wróć na stronę główną.
    • Zamknij aplikację podczas odtwarzania filmu.
    • Usuń element z wiersza „Kontynuuj oglądanie” (jeśli jest obsługiwany).
  • Po wykonaniu każdego działania sprawdź, czy Twoja aplikacja wywołała interfejs API publishContinuationClusters i czy dane są prawidłowo wyświetlane w aplikacji weryfikacyjnej.

  • W przypadku prawidłowo zaimplementowanych elementów aplikacja do weryfikacji wyświetli zieloną ikonę „Wszystko w porządku”.

    Zrzut ekranu z weryfikacją aplikacji
    Rysunek 1. Weryfikacja aplikacji – sukces

  • Aplikacja do weryfikacji wskaże wszystkie problematyczne elementy.

    Zrzut ekranu z błędem aplikacji do weryfikacji
    Rysunek 2. Błąd aplikacji do weryfikacji

  • Aby rozwiązać problemy z elementami, których dotyczy błąd, użyj pilota do telewizora, aby wybrać i kliknąć element w aplikacji do weryfikacji. Problemy zostaną wyświetlone i wyróżnione na czerwono (patrz przykład poniżej).

    Szczegóły błędu aplikacji weryfikacyjnej
    Rysunek 3. Szczegóły błędu aplikacji weryfikacyjnej