Codelab Engage SDK

1. Pengantar

Terakhir Diperbarui: 14-05-2024

Apa itu Engage SDK?

Engage SDK dapat membantu meningkatkan engagement aplikasi dengan menghadirkan konten aplikasi yang dipersonalisasi ke tempat pengguna berada di beberapa platform Google di perangkat. Dengan Engage SDK, aplikasi Anda dapat memberikan rekomendasi dan konten lanjutan yang dipersonalisasi (1:1) untuk berinteraksi dengan pengguna yang menginstal aplikasi Anda sebelum mereka membuka aplikasi Anda.

Platform Konten

Koleksi	Entertainment Space	Play Store (segera hadir)

Hadirkan konten Anda langsung ke layar utama pengguna dengan widget Play Store baru.	Membuat poin kontak baru untuk konten hiburan di tablet Android tertentu.	Akses platform tambahan, mulai dengan Play Store pada musim panas ini.

Yang akan Anda bangun

Setelah menyelesaikan codelab ini, Anda akan memiliki aplikasi video Android yang dapat mengirim konten ke platform Google.

Yang akan Anda butuhkan

Android SDK terbaru.
Android Studio terbaru
Satu perangkat seluler dengan Android 10 atau yang lebih baru.
Kabel data USB untuk menyambungkan perangkat seluler ke komputer pengembangan.

Pengalaman

Anda harus memiliki pengalaman menggunakan Java atau Kotlin.
Anda harus memiliki pengetahuan pengembangan terkait Android.

2. Menjalankan aplikasi contoh

Untuk memulai, download kode aplikasi contoh untuk membantu Anda mengikuti codelab ini.

Clone repositori jika Anda telah menginstal git.

git clone https://github.com/googlesamples/engage-sdk-samples.git

Atau, klik link ini untuk mendownload kode sumber dan mengekstrak file zip yang didownload.

Project ini menggunakan sistem build Gradle. Untuk membuat project ini, gunakan perintah build gradlew atau gunakan "Import Project" di Android Studio.

Setelah mendownload kode, Anda akan melihat dua contoh project.

Untuk developer Java - Gunakan aplikasi contoh baca

Aplikasi ini adalah koleksi buku dasar. Pengguna dapat memilih buku dari daftar, lalu dapat mulai membaca buku tersebut. Aplikasi ini menunjukkan cara data Rekomendasi & Lanjutan dipublikasikan.

Untuk developer Kotlin - Gunakan aplikasi contoh tonton

Aplikasi ini adalah koleksi video dasar. Pengguna dapat memilih video dari daftar, lalu dapat mulai menonton video tersebut. Aplikasi ini menunjukkan cara data Rekomendasi & Lanjutan dipublikasikan.

Untuk mengetahui referensi selengkapnya tentang mempelajari pengembangan Android, buka Panduan Developer di developer.android.com

3. Membuat Entity

Dalam codelab ini, kita akan merujuk ke Panduan integrasi Engage SDK Baca dan Panduan integrasi Engage SDK Tonton untuk aplikasi contoh baca dan tonton.

Entity adalah objek yang mewakili satu item dalam cluster. Entity dapat berupa eBook, film, atau jenis konten yang relevan.

Untuk konten baca, SDK memiliki Jenis Entity berikut

EbookEntity
AudiobookEntity
BookSeriesEntity

Untuk konten tonton, SDK memiliki Jenis Entity berikut

MovieEntity
TvShowEntity
TvSeasonEntity
TvEpisodeEntity
LiveStreamingVideoEntity
VideoClipEntity

Di aplikasi contoh baca, buka file EbookToEntityConverter.java yang berisi metode untuk membuat EbookEntity untuk dipublikasikan.

EbookEntity.Builder entityBuilder = new EbookEntity.Builder()
        .setName("NAME OF EBOOK")
        .addAuthor("AUTHOR NAME")
        .setActionLinkUri(Uri.parse("DEEPLINK URI OF THIS EBOOK"))
        ...
         .build()

Di aplikasi contoh tonton, buka file ItemToEntityConverter.kt yang berisi metode untuk membuat MovieEntity untuk dipublikasikan.

val movieBuilder: MovieEntity.Builder =
      MovieEntity.Builder()
        .setName("NAME OF THE MOVIE")
        .addPosterImage(
          Image.Builder()
            .setImageUri(
              Uri.parse("android.resource://movie")
            )
            .setImageWidthInPixel(408)
            .setImageHeightInPixel(960)
            .setImageTheme(ImageTheme.IMAGE_THEME_LIGHT)
            .build()
        )
        .setPlayBackUri(Uri.parse(movie.playbackUri))
        .setReleaseDateEpochMillis(movie.releaseDate)
        .setAvailability(movie.availability)
        .setDurationMillis(movie.durationMillis)
        .addGenre(movie.genre)
          ..
           .build()

Demikian pula dalam aplikasi, Anda juga dapat mengonversi item data Anda sendiri ke Entity Engage yang sesuai untuk dipublikasikan.

4. Membuat Cluster Rekomendasi

Setelah membuat Entity, kita dapat mengelompokkannya dalam Cluster.

Cluster adalah kumpulan konten yang dipaketkan bersama. Cluster dapat divisualisasikan sebagai tampilan UI yang berisi sekumpulan grup item konten dari satu partner developer.

Gambar.

UI Entertainment Space menampilkan Cluster Rekomendasi dengan Entity Ebook dari satu partner.

Untuk sebagian besar kategori, termasuk konten baca dan konten tonton, SDK memiliki Jenis Cluster berikut

Cluster Rekomendasi dapat dipersonalisasi berdasarkan perilaku pengguna di aplikasi Anda dan diatur menurut tema, seperti rilis baru, penurunan harga, atau topik favorit pengguna. Setiap aplikasi dapat memberikan hingga 5 cluster rekomendasi per pengguna.
Cluster Lanjutan membantu pengguna melanjutkan konten yang sedang berlangsung, seperti film atau eBook yang belum selesai, dalam satu pengelompokan UI dengan konten dari beberapa aplikasi.
Cluster Unggulan dapat menyoroti konten utama Anda dalam cluster multi-aplikasi menggunakan template UI yang lebih besar dan premium.

Kita akan membuat cluster Rekomendasi untuk konten baca dan tonton.

Di aplikasi contoh baca, buka file GetRecommendationClusters.java, yang menunjukkan contoh cara membuat cluster Rekomendasi.

RecommendationCluster.Builder clusterBuilder = new RecommendationCluster.Builder();
// Set the cluster title
clusterBuilder.setTitle("For You");
for (int id : ebookIds) {
  //Create an ebook entity.
  EbookEntity entity = EbookToEntityConverter.convert(id); 
  // Add the ebook entity to the cluster
  clusterBuilder.addEntity(entity);
}
// Build the cluster
return clusterBuilder.build();

Di aplikasi contoh tonton, buka file ClusterRequestFactory.kt, yang menunjukkan contoh cara membuat cluster Rekomendasi.

// Loads all the movie data 
val recommendationsList = movieDao.loadMovieIsCurrentlyWatching(false)
val recommendationCluster = RecommendationCluster.Builder()
for (item in recommendationsList) {
   //Create a movie entity.
    val movieEntity = ItemToEntityConverter.convertMovie(item)
    // Add the movie entity to the cluster
    recommendationCluster.addEntity(movieEntity)
}
// Build the cluster
return recommendationCluster.build

5. Memublikasikan Cluster Rekomendasi

Setelah kita mempelajari cara membuat Entity dan cara mengelompokkan Entity ini ke dalam Cluster. Langkah berikutnya adalah mempelajari cara memublikasikan cluster.

AppEngagePublishClient bertanggung jawab untuk membuat koneksi guna memublikasikan cluster.

Langkah 1: Lakukan inisialisasi klien.

// Java version
AppEngagePublishClient client = new AppEngagePublishClient(context);

// Kotlin version
val client = AppEngagePublishClient(context)

Langkah 2: Buat permintaan untuk memublikasikan cluster

Di aplikasi contoh baca, periksa metode setRecommendations di EngageServiceWorker.java

// Initialize the builder
PublishRecommendationClustersRequest.Builder publishRequestBuilder = new PublishRecommendationClustersRequest.Builder();

// Add all Recommendation Clusters
for (RecommendationCluster cluster : clusters) {
   publishRequestBuilder.addRecommendationCluster(cluster);
}
// Build the request    
publishRequestBuilder.build();

Di aplikasi contoh tonton, periksa metode constructRecommendationClustersRequest di ClusterRequestFactory.kt

// Initialize the builder
val request = PublishRecommendationClustersRequest.Builder()
// Add all Recommendation Cluster
.addRecommendationCluster(recommendationCluster)
// Build the request    
.build()

Langkah 3: Panggil metode publishRecommendationClusters di AppEngagePublishClient

Di aplikasi contoh baca, periksa metode setRecommendations di EngageServiceWorker.java

client.publishRecommendationClusters(publishRequest);

Di aplikasi contoh tonton, periksa metode publishRecommendations di EngageServiceWorker.kt

client.publishRecommendationClusters(request)

Menggunakan isServiceAvailable API

Sebelum memanggil API publikasi, Anda harus memanggil isServiceAvailable untuk memastikan publikasi diizinkan.

Di aplikasi contoh baca, periksa metode startWork di EngageServiceWorker.java

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
          client.publishRecommendationClusters(request)
        } else {
          // Service is not available, do not publish.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Di aplikasi contoh tonton, periksa metode doWork di EngageServiceWorker.kt

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
          client.publishRecommendationClusters(request)
        } else {
          // Service is not available, do not publish.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

6. Memublikasikan Status

Sebaiknya gunakan updatePublishStatus API untuk menunjukkan alasan konten tidak dipublikasikan. Hal ini membantu Google menghindari notifikasi palsu saat aplikasi Anda sengaja tidak memublikasikan konten, memandu pengguna untuk mengambil tindakan korektif guna mengakses konten Anda, dan memberikan insight kepada Anda tentang kondisi publikasi konten Anda.

Lihat situs developer untuk mengetahui kode status. Misalnya, jika tidak ada konten yang ditampilkan karena pengguna harus login, gunakan NOT_PUBLISHED_REQUIRES_SIGN_IN. Kita akan menerapkan kode ini di langkah berikutnya.

Di aplikasi contoh baca, periksa metode publishAndSetResult di EngageServiceWorker.kt

int publishStatusCode;
              if (loggedInAccount.isPresent()) {
                // If an account is logged in and content is published
                publishStatusCode = AppEngagePublishStatusCode.PUBLISHED;
              } else {
                // If an account is not logged in and no content is published
                publishStatusCode = AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN;
              }
              setPublishStatus(client, publishStatusCode);
            })

Di aplikasi contoh tonton, periksa metode publishUserAccountManagement di EngageServiceWorker.kt

private suspend fun publishUserAccountManagement(): Result {
    val publishTask: Task<Void>
    val statusCode: Int
    if (db.accountDao().isAccountSignedIn()) {
      // If an account is logged in and content is published
statusCode = AppEngagePublishStatusCode.PUBLISHED
    } else {
     // If an account is not logged in and no content is published
      statusCode = AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN
    }
    return publishAndProvideResult(publishTask, statusCode)
  }

7. Work Manager & Intent Siaran

Work Manager

Sebaiknya jalankan tugas publikasi konten di latar belakang (menggunakan WorkManager). Jadwalkan secara rutin (misalnya, setiap hari) dan/atau berdasarkan peristiwa pengguna (misalnya, saat aplikasi dibuka atau setelah pengguna menyelesaikan sesi membaca). Contoh di bawah berfokus pada publikasi terjadwal.

Di aplikasi contoh baca, queuePeriodicSetEngageStateWorker dalam file SetEngageState.java menunjukkan contoh cara menyiapkan WorkManager

// Create a work manager
WorkManager workManager = WorkManager.getInstance(appContext);

// Set up a periodic work request for 24 hrs.
PeriodicWorkRequest publishRequest =
        new PeriodicWorkRequest.Builder(
                EngageServiceWorker.class, /* repeatInterval= */ 24, TimeUnit.HOURS)
            .setInputData(clusterToPublishData)
            .build();
// Add the work request to queue
workManager.enqueueUniquePeriodicWork(
        publishWorkName, ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE, publishRequest);

Di aplikasi contoh tonton, periodicallyCallEngageServiceWorker di Publisher.kt menunjukkan contoh cara menyiapkan WorkManager

// Set up a periodic work request for 24 hrs.
val workRequest = PeriodicWorkRequestBuilder<EngageServiceWorker>(
          repeatInterval = 24,
          repeatIntervalTimeUnit = TimeUnit.HOURS
        )
        .setInputData(workDataOf(PUBLISH_TYPE to publishType))
        .build()

// Create a work manager and add the work request to queue
WorkManager.getInstance(context)
.enqueueUniquePeriodicWork(
workerName,
ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
workRequest
)

Intent Siaran

Selain melakukan panggilan API publikasi konten melalui tugas, Anda juga harus menyiapkan BroadcastReceiver untuk menerima permintaan publikasi konten.

Tujuan intent siaran terutama untuk pengaktifan kembali aplikasi dan memaksa sinkronisasi data. Intent siaran tidak didesain untuk dikirim terlalu sering. Intent siaran hanya dipicu jika Layanan Engage menyimpulkan bahwa konten mungkin sudah tidak berlaku (misalnya, seminggu yang lalu). Dengan demikian, pengguna menjadi lebih yakin bahwa mereka dapat memiliki pengalaman konten baru meskipun aplikasi tidak dijalankan dalam waktu yang lama.

BroadcastReceiver harus disiapkan dengan dua cara berikut:

Daftarkan instance class BroadcastReceiver secara dinamis menggunakan Context.registerReceiver(). Hal ini memungkinkan komunikasi dari aplikasi yang masih aktif dalam memori.

Buka file MainActivity.java di aplikasi contoh baca untuk memeriksa hal berikut :

private void registerReceiver() {
    BroadcastReceiver publishReceiver = new EngageServiceBroadcastReceiver();
    IntentFilter filter = new IntentFilter();
    filter.addAction(Intents.ACTION_PUBLISH_RECOMMENDATION);
    filter.addAction(Intents.ACTION_PUBLISH_FEATURED);
    filter.addAction(Intents.ACTION_PUBLISH_CONTINUATION);
    int flags = ContextCompat.RECEIVER_EXPORTED;
    ContextCompat.registerReceiver(getApplicationContext(), publishReceiver, filter, flags);
  }

Deklarasikan penerapan secara statis dengan tag <receiver> di file AndroidManifes.xml Anda. Hal ini memungkinkan aplikasi menerima intent siaran ketika tidak sedang berjalan, dan juga memungkinkan aplikasi untuk memublikasikan konten.

Buka file AndroidManifest.xml di aplikasi contoh baca untuk memeriksa hal berikut :

<receiver
        android:name=".publish.EngageServiceBroadcastReceiver"
        android:exported="true">
      <intent-filter>
        <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
        <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
        <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
             </intent-filter>
 </receiver>

Intent berikut dikirim oleh layanan:

com.google.android.engage.action.PUBLISH_RECOMMENDATION Sebaiknya mulai panggilan publishRecommendationClusters saat menerima intent ini.
com.google.android.engage.action.PUBLISH_FEATURED Sebaiknya mulai panggilan publishFeaturedCluster saat menerima intent ini.
com.google.android.engage.action.PUBLISH_CONTINUATION Sebaiknya mulai panggilan publishContinuationCluster saat menerima intent ini.

8. Menggunakan Aplikasi Verifikasi untuk Pengujian

Download dan gunakan aplikasi verifikasi untuk memverifikasi integrasi Anda

Aplikasi verifikasi harus menampilkan setiap cluster sebagai baris terpisah.

Masukkan nama paket yang memublikasikan data.

Pastikan semua entity dalam cluster telah dipublikasikan.

Pastikan semua kolom dalam entity dipublikasikan. Untuk setiap item dalam baris, developer dapat mengklik gambar poster untuk memverifikasi intent.

Memverifikasi alur intent siaran

Gunakan aplikasi verifikasi untuk memverifikasi intent siaran, klik tombol di bagian atas UI untuk memicu logika untuk mengirim siaran.

9. Selamat

Sekarang Anda sudah mengetahui cara menambahkan Engage SDK ke aplikasi Android.

Untuk mengetahui detail selengkapnya, lihat panduan developer Engage SDK dan Situs Bisnis.

Referensi

Berdasarkan jenis konten yang dipublikasikan, SDK berisi berbagai jenis class Entity. Anda dapat melihat daftar entity yang tersedia di panduan integrasi untuk setiap kategori yang tercantum di bawah -

Codelab Engage SDK Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.