Engage SDK'sı Dinleme: Üçüncü taraf teknik entegrasyon talimatları

Google, kullanıcıların uygulamalarını sektörlere göre düzenleyen ve kişiselleştirilmiş uygulama içeriğinin tüketilmesi ve keşfedilmesi için yeni ve etkileyici bir deneyim sağlayan bir cihaz yüzeyi geliştirmektedir. Bu tam ekran deneyimi, geliştirici iş ortaklarına en iyi zengin içeriklerini uygulamalarının dışında özel bir kanalda gösterme fırsatı sunar.

Bu kılavuzda, geliştirici iş ortaklarının hem bu yeni yüzey alanını hem de mevcut Google yüzeylerini doldurmak için Engage SDK'sını kullanarak ses içeriklerini entegre etmelerine yönelik talimatlar bulunmaktadır.

Entegrasyon ayrıntısı

Terminoloji

Bu entegrasyon şu üç küme türünü içerir: Öneri, Devam ve Öne Çıkan.

  • Öneri kümeleri, belirli bir geliştirici iş ortağının okuyacağı içerik için kişiselleştirilmiş öneriler gösterir.

    Önerileriniz aşağıdaki yapıyı alır:

    • Öneri Kümesi: Aynı geliştirici iş ortağından bir dizi öneri içeren kullanıcı arayüzü görünümü.

      Şekil 1. Tek bir iş ortağından bir Öneri Kümesini gösteren Entertainment Space kullanıcı arayüzü.

    • Varlık: Bir kümedeki tek bir öğeyi temsil eden bir nesne. Varlık; bir oynatma listesi, sesli kitap, podcast ve daha fazlası olabilir. Desteklenen varlık türlerinin listesi için Varlık verileri sağlama bölümüne bakın.

      Şekil 2. Tek bir iş ortağının Öneri Kümesindeki tek bir varlığı gösteren Entertainment Space kullanıcı arayüzü.

  • Devam kümesi, tek bir kullanıcı arayüzü gruplandırmasında birden fazla geliştirici iş ortağının kullanıcıları tarafından yakın zamanda etkileşimde bulunulan ses içeriğini gösterir. Her geliştirici iş ortağının Devam kümesinde en fazla 10 varlık yayınlamasına izin verilir.

    Şekil 3. Birden çok iş ortağından tamamlanmamış öneriler içeren bir Devamlılık kümesini gösteren Entertainment Space kullanıcı arayüzü (şu anda yalnızca bir öneri bulunmaktadır).

  • Öne Çıkan kümesi, tek bir kullanıcı arayüzü grubunda birden fazla geliştirici iş ortağından seçilmiş öğeleri gösterir. Kullanıcı arayüzünün üst kısmına yakın bir yerde gösterilecek tek bir Öne Çıkan küme olacaktır. Bu küme, tüm Öneri kümelerinin üzerinde öncelikli bir yerleşimle birlikte gösterilecektir. Her geliştirici iş ortağının Öne Çıkanlar kümesinde en fazla 10 varlık yayınlamasına izin verilir.

    Şekil 4. Birden fazla iş ortağının önerilerinin yer aldığı bir Öne çıkan kümeyi gösteren Entertainment Space kullanıcı arayüzü (şu anda yalnızca bir öneri görünür).

Çalışma öncesi

Minimum API düzeyi: 19

com.google.android.play:engage kitaplığını uygulamanıza ekleyin:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.4.0'
}

Özet

Tasarım, bağlı bir hizmetin uygulanmasına dayanır.

Bir istemcinin yayınlayabileceği veriler, farklı küme türleri için aşağıdaki sınırlara tabidir:

Küme türü Küme sınırları Bir kümedeki maksimum varlık sınırları
Öneri Kümeleri En fazla 5 En fazla 50
Devam Kümesi En fazla 1 En fazla 10
Öne Çıkan Küme En fazla 1 En fazla 10

1. adım: Varlık verileri sağlayın

SDK, her bir öğe türünü temsil edecek farklı varlıklar tanımlamıştır. Dinleme kategorisi için aşağıdaki varlıkları destekliyoruz:

  1. MusicAlbumEntity
  2. MusicArtistEntity
  3. MusicTrackEntity
  4. MusicVideoEntity
  5. PlaylistEntity
  6. PodcastSeriesEntity
  7. PodcastEpisodeEntity
  8. LiveRadioStationEntity
  9. AudiobookEntity

Aşağıdaki grafiklerde, her tür için kullanılabilir özellikler ve gereksinimler özetlenmiştir.

MusicAlbumEntity

MusicAlbumEntity nesnesi bir müzik albümünü (örneğin, Taylor Swift'in Midnights) temsil eder.

Özellik Şartlar Notlar
Ad Zorunlu Müzik albümünün başlığı.
Poster resimleri Zorunlu En az bir resim sağlanmalıdır. Yardım için Resim Özellikleri bölümüne bakın.
Bilgi sayfası URI'sı Zorunlu

Müzik albümüyle ilgili ayrıntılar için sağlayıcı uygulamasının derin bağlantısı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Sanatçılar Zorunlu Müzik albümündeki sanatçıların listesi.
Oynatma URI'si İsteğe bağlı

Albümü sağlayıcı uygulamasında çalmaya başlayan bir derin bağlantı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Açıklama İsteğe bağlı Sağlanmışsa 200 karakteri aşmamalıdır.
Şarkı sayısı İsteğe bağlı Müzik albümündeki şarkı sayısı.
Türler İsteğe bağlı Müzik albümündeki türlerin listesi.
Albüm Biçimi İsteğe bağlı

ALBÜM (LP ve çift LP dahil)

EP

TEK

Karışık Liste
Plak şirketleri İsteğe bağlı Albümle ilişkili müzik etiketlerinin listesi.
Cihaza indirildi İsteğe bağlı Müzik albümünün cihaza indirilip indirilmediğini gösteren boole değeri.
Müstehcen İsteğe bağlı

İçeriğin uygunsuz olup olmadığını gösteren boole

Uygunsuz materyal içeren veya ebeveyn tavsiyesi uyarısı olan öğeler DOĞRU olarak ayarlanmalıdır. Uygunsuz öğeler "E" etiketiyle görünür.

Yayın tarihi İsteğe bağlı Dönem milisaniye cinsinden albümün çıkış tarihi.
Süre İsteğe bağlı Albümün milisaniye cinsinden süresi.
Son etkileşim zamanı İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir. Sıralama için kullanılabilir.

Dönem milisaniye cinsinden
Tamamlanan ilerleme yüzdesi İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir.

0 ile 100 arasında bir tam sayı

MusicArtistEntity

MusicArtistEntity nesnesi bir müzik yazarını temsil eder (örneğin, Adele).

Özellik Şartlar Notlar
Ad Zorunlu Müzik sanatçısının adı.
Poster resimleri Zorunlu En az bir resim sağlanmalıdır. Yardım için Resim Özellikleri bölümüne bakın.
Bilgi sayfası URI'sı Zorunlu

Müzik sanatçısıyla ilgili ayrıntılar için sağlayıcı uygulamasının derin bağlantısı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Oynatma URI'si İsteğe bağlı

Sanatçının şarkılarını sağlayıcı uygulamasında çalmaya başlayan derin bağlantı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Açıklama İsteğe bağlı Sağlanmışsa 200 karakteri aşmamalıdır.
Son etkileşim zamanı İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir. Sıralama için kullanılabilir.

Dönem milisaniye cinsinden

MusicTrackEntity

MusicTrackEntity nesnesi bir müzik parçasını temsil eder (örneğin, Coldplay'den Yellow).

Özellik Şartlar Notlar
Ad Zorunlu Müzik parçasının başlığı.
Poster resimleri Zorunlu En az bir resim sağlanmalıdır. Yardım için Resim Özellikleri bölümüne bakın.
Oynatma URI'si Zorunlu

Müzik parçasını sağlayıcı uygulamasında çalmaya başlayan bir derin bağlantı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Bilgi sayfası URI'sı İsteğe bağlı

Müzik parçasıyla ilgili ayrıntılar için sağlayıcı uygulamasına yönlendiren derin bağlantı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Açıklama İsteğe bağlı Sağlanmışsa 200 karakteri aşmamalıdır.
Süre İsteğe bağlı Parçanın milisaniye cinsinden süresi.
Albüm İsteğe bağlı Şarkının ait olduğu albümün adı.
Sanatçılar Zorunlu Müzik parçası için sanatçıların listesi.
Cihaza indirildi İsteğe bağlı Müzik parçasının cihaza indirilip indirilmediğini gösteren boole değeri.
Müstehcen İsteğe bağlı

İçeriğin uygunsuz olup olmadığını gösteren boole

Uygunsuz materyal içeren veya ebeveyn tavsiyesi uyarısı olan öğeler DOĞRU olarak ayarlanmalıdır. Uygunsuz öğeler "E" etiketiyle görünür.

Son etkileşim zamanı İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir. Sıralama için kullanılabilir.

Dönem milisaniye cinsinden
Tamamlanan ilerleme yüzdesi İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir.

0 ile 100 arasında bir tam sayı

MusicVideoEntity

MusicVideoEntity nesnesi bir müzik videosunu temsil eder (örneğin, The Weeknd - Take My Breath (Resmi Müzik Videosu)).

Özellik Şartlar Notlar
Ad Zorunlu Müzik videosunun başlığı.
Poster resimleri Zorunlu En az bir resim sağlanmalıdır. Yardım için Resim Özellikleri bölümüne bakın.
Oynatma URI'si Zorunlu

Müzik videosunu sağlayıcı uygulamasında oynatmaya başlayan derin bağlantı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Bilgi sayfası URI'sı İsteğe bağlı

Müzik videosuyla ilgili ayrıntılar için sağlayıcı uygulamasına yönlendiren derin bağlantı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Süre İsteğe bağlı Videonun milisaniye cinsinden süresi.
İzlenme sayısı İsteğe bağlı Serbest metin biçimindeki videonun görüntüleme sayısıdır.
Sanatçılar İsteğe bağlı Müzik videosunda kullanan sanatçıların listesi.
İçerik derecelendirmesi İsteğe bağlı Parçanın içerik derecelendirmelerinin listesi.
Açıklama İsteğe bağlı Sağlanmışsa 200 karakteri aşmamalıdır.
Cihaza indirildi İsteğe bağlı Müzik videosunun cihaza indirilip indirilmediğini gösteren boole değeri.
Müstehcen İsteğe bağlı

İçeriğin uygunsuz olup olmadığını gösteren boole

Uygunsuz materyal içeren veya ebeveyn tavsiyesi uyarısı olan öğeler DOĞRU olarak ayarlanmalıdır. Uygunsuz öğeler "E" etiketiyle görünür.

Son etkileşim zamanı İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir. Sıralama için kullanılabilir.

Dönem milisaniye cinsinden
Tamamlanan ilerleme yüzdesi İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir.

0 ile 100 arasında bir tam sayı

PlaylistEntity

PlaylistEntity nesnesi bir müzik şarkı listesini (örneğin, ABD'nin En İyi 10 Şarkı Listesi) temsil eder.

Özellik Şartlar Notlar
Ad Zorunlu Oynatma listesinin başlığı.
Poster resimleri Zorunlu En az bir resim sağlanmalıdır. Yardım için Resim Özellikleri bölümüne bakın.
Oynatma URI'si Zorunlu

Sağlayıcı uygulamasında müzik şarkı listesini çalmaya başlayan bir derin bağlantı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Bilgi sayfası URI'sı İsteğe bağlı

Müzik oynatma listesiyle ilgili ayrıntılar için sağlayıcı uygulamasına yönlendiren derin bağlantı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Süre İsteğe bağlı Oynatma listesinin milisaniye cinsinden süresi.
Şarkı sayısı İsteğe bağlı Müzik oynatma listesindeki şarkı sayısı.
Açıklama İsteğe bağlı Sağlanmışsa 200 karakteri aşmamalıdır.
Cihaza indirildi İsteğe bağlı Oynatma listesinin cihaza indirilip indirilmediğini gösteren boole değeri.
Müstehcen İsteğe bağlı

İçeriğin uygunsuz olup olmadığını gösteren boole

Uygunsuz materyal içeren veya ebeveyn tavsiyesi uyarısı olan öğeler DOĞRU olarak ayarlanmalıdır. Uygunsuz öğeler "E" etiketiyle görünür.

Son etkileşim zamanı İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir. Sıralama için kullanılabilir.

Dönem milisaniye cinsinden
Tamamlanan ilerleme yüzdesi İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir.

0 ile 100 arasında bir tam sayı

PodcastSeriesEntity

PodcastSeriesEntity nesnesi bir podcast serisini temsil eder (örneğin, This American Life).

Özellik Şartlar Notlar
Ad Zorunlu Podcast dizisinin adı.
Poster resimleri Zorunlu En az bir resim sağlanmalıdır. Yardım için Resim Özellikleri bölümüne bakın.
Bilgi sayfası URI'sı Zorunlu

Podcast serisiyle ilgili ayrıntılar için sağlayıcı uygulamasının derin bağlantısı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Oynatma URI'si İsteğe bağlı

Podcast dizisini sağlayıcı uygulamasında oynatmaya başlayan derin bağlantı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Bölüm sayısı İsteğe bağlı Podcast dizisindeki bölüm sayısı.
Prodüksiyon adı İsteğe bağlı Podcast serisinin prodüksiyonunun adı.
Düzenleyenler İsteğe bağlı Podcast dizisinin sunucularının listesi.
Türler İsteğe bağlı Podcast dizisinin türlerinin listesi.
Cihaza indirildi İsteğe bağlı Podcast'in cihaza indirilip indirilmediğini gösteren boole değeri.
Açıklama İsteğe bağlı Sağlanmışsa 200 karakteri aşmamalıdır.
Müstehcen İsteğe bağlı

İçeriğin uygunsuz olup olmadığını gösteren boole

Uygunsuz materyal içeren veya ebeveyn tavsiyesi uyarısı olan öğeler DOĞRU olarak ayarlanmalıdır. Uygunsuz öğeler "E" etiketiyle görünür.

Son etkileşim zamanı İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir. Sıralama için kullanılabilir.

Dönem milisaniye cinsinden

PodcastEpisodeEntity

PodcastEpisodeEntity nesnesi bir podcast serisini temsil eder (örneğin, Spark Bird, 754. Bölüm: This American Life).

Özellik Şartlar Notlar
Ad Zorunlu Podcast bölümünün başlığı.
Poster resimleri Zorunlu En az bir resim sağlanmalıdır. Yardım için Resim Özellikleri bölümüne bakın.
Oynatma URI'si Zorunlu

Podcast bölümünü sağlayıcı uygulamasında oynatmaya başlayan derin bağlantı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Prodüksiyon serisinin adı Zorunlu Bölümün ait olduğu podcast dizisinin adı.
Süre Zorunlu Podcast bölümünün milisaniye cinsinden süresi.
Yayınlanma Tarihi Zorunlu Podcast'in yayınlanma tarihi (sıfır milisaniye cinsinden)
Bilgi sayfası URI'sı İsteğe bağlı

Podcast bölümüyle ilgili ayrıntılar için sağlayıcı uygulamasının derin bağlantısı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Prodüksiyon adı İsteğe bağlı Podcast serisinin prodüksiyonunun adı.
Bölüm dizini İsteğe bağlı Serideki bölümün dizini (ilk dizin 1'dir).
Düzenleyenler İsteğe bağlı Podcast bölümünü düzenleyenlerin listesi.
Türler İsteğe bağlı Podcast bölümü türlerinin listesi.
Cihaza indirildi İsteğe bağlı Podcast bölümünün cihaza indirilip indirilmediğini gösteren boole değeri.
Açıklama İsteğe bağlı Sağlanmışsa 200 karakteri aşmamalıdır.
Video Podcast Aboneliği İsteğe bağlı Podcast bölümünde video içeriği olup olmadığını gösteren boole değeri
Müstehcen İsteğe bağlı

İçeriğin uygunsuz olup olmadığını gösteren boole

Uygunsuz materyal içeren veya ebeveyn tavsiyesi uyarısı olan öğeler DOĞRU olarak ayarlanmalıdır. Uygunsuz öğeler "E" etiketiyle görünür.

Sonrakini Dinle Türü İsteğe bağlı

Devam Kümesi'ndeki Öğeler için Önerilir

TYPE_CONTINUE - Tamamlanmamış bir ses öğesini devam ettirin.

TYPE_NEXT - Bir serinin yenisiyle devam edin.

TYPE_NEW - Yeni yayınlandı.
Son etkileşim zamanı İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir. Sıralama için kullanılabilir.

Dönem milisaniye cinsinden
Tamamlanan ilerleme yüzdesi İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir.

0 ile 100 arasında bir tam sayı

LiveRadioStationEntity

LiveRadioStationEntity nesnesi, canlı bir radyo istasyonunu (örneğin, 98.1 The Breeze) temsil eder.

Özellik Şartlar Notlar
Ad Zorunlu Canlı radyo istasyonunun adı.
Poster resimleri Zorunlu En az bir resim sağlanmalıdır. Yardım için Resim Özellikleri bölümüne bakın.
Oynatma URI'si Zorunlu

Sağlayıcı uygulamasında radyo istasyonunu çalmaya başlayan bir derin bağlantı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Bilgi sayfası URI'sı İsteğe bağlı

Radyo istasyonuyla ilgili ayrıntılar için sağlayıcı uygulamasının derin bağlantısı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Frekans İsteğe bağlı Radyo istasyonunun yayınlanma frekansı (örneğin, "98.1 FM").
Program adı İsteğe bağlı Radyo istasyonunda şu anda çalan program.
Düzenleyenler İsteğe bağlı Radyo istasyonu ana makinelerinin listesi.
Açıklama İsteğe bağlı Sağlanmışsa 200 karakteri aşmamalıdır.
Son etkileşim zamanı İsteğe bağlı

Devam Kümesi'ndeki öğeler için önerilir. Sıralama için kullanılabilir.

Dönem milisaniye cinsinden

AudiobookEntity

AudiobookEntity nesnesi bir sesli kitabı temsil eder (örneğin, Michelle Obama'nın Becoming adlı sesli kitabı).

Özellik Şartlar Notlar
Ad Zorunlu
Poster resimleri Zorunlu En az bir resim sağlanmalıdır. Yardım için Resim Özellikleri bölümüne bakın.
Yazar Zorunlu En az bir yazar adı sağlanmalıdır.
Anlatıcı Zorunlu En az bir anlatıcının adı sağlanmalıdır.
İşlem bağlantısı URI'si Zorunlu

Sesli kitabın sağlayıcı uygulamasının derin bağlantısı.

Not: İlişkilendirme için derin bağlantıları kullanabilirsiniz. Bu SSS bölümünü inceleyin

Yayınlanma tarihi İsteğe bağlı Sağlanmışsa sıfır milisaniye cinsinden.
Açıklama İsteğe bağlı Sağlanmışsa 200 karakteri aşmamalıdır.
Fiyat İsteğe bağlı Serbest metin
Süre İsteğe bağlı Sağlanması halinde pozitif bir değer olmalıdır.
Tür İsteğe bağlı Kitapla ilişkili türlerin listesi.
Dizi adı İsteğe bağlı Sesli kitabın ait olduğu serinin adı (ör. Harry Potter).
Seri birim dizini İsteğe bağlı Serideki sesli kitabın dizini. Burada 1, serideki ilk sesli kitaptır. Örneğin, Harry Potter and the Prisoner of Azkaban serinin 3. kitabıysa bu değer 3 olarak ayarlanmalıdır.
Kitap türüne devam et İsteğe bağlı

TYPE_CONTINUE - Tamamlanmamış bir kitabın üzerinde devam ettir.

TYPE_NEXT - Bir serinin yenisiyle devam edin.

TYPE_NEW - Yeni yayınlandı.
Son Etkileşim Zamanı Koşula bağlı olarak gerekli

Öğe, Devam kümesindeyken sağlanmalıdır.

Dönem milisaniye cinsinden.
Tamamlanan İlerleme Yüzdesi Koşula bağlı olarak gerekli

Öğe, Devam kümesindeyken sağlanmalıdır.

*Yeni* edinilen sesli kitaplar, devam eden okuma grubunun bir parçası olabilir.

Değer 0'dan büyük, 100'den küçük olmalıdır.
DisplayTimeWindow - İçeriğin yüzeyde gösterileceği zaman aralığını belirleyin
Başlangıç Zaman Damgası İsteğe bağlı

İçeriğin yüzeyde gösterilmesi gereken dönemin zaman damgası.

Politika ayarlanmazsa içerikler yüzeyde gösterilebilir.

Dönem milisaniye cinsinden.
Bitiş Zaman Damgası İsteğe bağlı

İçeriğin artık yüzeyde gösterilmediği dönemin zaman damgası.

Politika ayarlanmazsa içerikler yüzeyde gösterilebilir.

Dönem milisaniye cinsinden.

Resim özellikleri

Resim öğeleri için gerekli özellikler aşağıda listelenmiştir:

En boy oranı Şartlar Minimum piksel sayısı Önerilen piksel sayısı
Kare (1x1) Zorunlu 300x300 1.200x1.200
Yatay (1,91x1) İsteğe bağlı 600x314 1.200x628
Dikey (4x5) İsteğe bağlı 480x600 960 x 1.200

Dosya biçimleri

PNG, JPG, statik GIF, WebP

Maksimum dosya boyutu

5.120 KB

Ek öneriler

  • Resim güvenli alanı: Önemli içeriklerinizi yatay ve dikey yönde ortalanmış olarak resmin% 80'ini kaplayacak şekilde yerleştirin.

Örnekler

MusicAlbumEntity musicAlbumEntity =
        new MusicAlbumEntity.Builder()
            .setName(NAME)
             .addPosterImage(new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(960)
                  .setImageWidthInPixel(408)
                  .build())
            .setPlayBackUri("https://play.google/album/play")
            .setInfoPageUri("https://play.google/album/info")
            .setDescription("A description of this album.")
            .addArtist("Artist")
            .addGenre("Genre")
            .addMusicLabel("Label")
            .addContentRating("Rating")
            .setSongsCount(960)
            .setReleaseDateEpochMillis(1633032895L)
            .setDurationMillis(1633L)
            .build();

AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(new Image.Builder()
                 .setImageUri(Uri.parse("http://www.x.com/image.png"))
                 .setImageHeightInPixel(960)
                 .setImageWidthInPixel(408)
                  .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(
               Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .build();

2. Adım: Küme verilerini sağlayın

İçerik yayınlama işinin arka planda yürütülmesi (örneğin, WorkManager kullanılarak) ve düzenli olarak ya da etkinlik temelli olarak planlanması önerilir (örneğin, kullanıcı uygulamayı her açtığında veya kullanıcı sepetine yeni bir ürün eklediğinde).

AppEngagePublishClient, kümeleri yayınlamaktan sorumludur. İstemcide aşağıdaki API'ler kullanılabilir:

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishContinuationCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteContinuationCluster
  • deleteUserManagementCluster
  • deleteClusters

isServiceAvailable

Bu API, hizmetin entegrasyon için uygun olup olmadığını ve içeriğin cihazda sunulup sunulmadığını kontrol etmek için kullanılır.

Kotlin


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.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java


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

publishRecommendationClusters

Bu API, RecommendationCluster nesnelerinin listesini yayınlamak için kullanılır.

Kotlin


client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build())

Java


client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build());

Hizmet, isteği aldığında tek işlem içinde aşağıdaki işlemler gerçekleştirilir:

  • Geliştirici iş ortağından alınan mevcut RecommendationCluster verileri kaldırılır.
  • İstekteki veriler ayrıştırılır ve güncellenmiş Öneri Kümesinde depolanır.

Hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

publishFeaturedCluster

Bu API, FeaturedCluster nesnelerinin listesini yayınlamak için kullanılır.

Kotlin


client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

Java


client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        ...
                        .build())
                .build());

Hizmet, isteği aldığında tek işlem içinde aşağıdaki işlemler gerçekleştirilir:

  • Geliştirici iş ortağından alınan mevcut FeaturedCluster verileri kaldırılır.
  • İstekten elde edilen veriler ayrıştırılır ve güncellenmiş Öne Çıkan Küme'de depolanır.

Hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

publishContinuationCluster

Bu API bir ContinuationCluster nesnesini yayınlamak için kullanılır.

Kotlin


client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

Java


client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

Hizmet, isteği aldığında tek işlem içinde aşağıdaki işlemler gerçekleştirilir:

  • Geliştirici iş ortağından alınan mevcut ContinuationCluster verileri kaldırılır.
  • İstekten elde edilen veriler ayrıştırılır ve güncellenen Devam Kümesi'nde depolanır.

Hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

publishUserAccountManagementRequest

Bu API, Oturum Açma kartı yayınlamak için kullanılır . Oturum açma işlemi, uygulamanın içerik yayınlayabilmesi (veya daha kişiselleştirilmiş içerik sağlayabilmesi) için kullanıcıları uygulamanın oturum açma sayfasına yönlendirir

Aşağıdaki meta veriler Oturum Açma Kartının bir parçasıdır -

Özellik Şartlar Açıklama
İşlem URI'sı Zorunlu İşlem için derin bağlantı (ör. uygulamada oturum açma sayfasına yönlendirir)
Resim İsteğe bağlı - Sağlanmamışsa başlık sağlanmalıdır

Kartta Gösterilen Resim

1264x712 çözünürlüklü 16x9 en boy oranına sahip resimler
Başlık İsteğe bağlı - Sağlanmazsa Resim sağlanmalıdır Kartın Başlığı
İşlem Metni İsteğe bağlı CTA'da gösterilen metin (ör. oturum açma)
Alt başlık İsteğe bağlı Kartta İsteğe Bağlı Altyazı

Kotlin


var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java


SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Hizmet, isteği aldığında tek işlem içinde aşağıdaki işlemler gerçekleştirilir:

  • Geliştirici iş ortağından alınan mevcut UserAccountManagementCluster verileri kaldırılır.
  • İstekteki veriler ayrıştırılır ve güncellenmiş UserAccountManagementCluster Kümesinde depolanır.

Hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

updatePublishStatus

İşle ilgili herhangi bir nedenle kümelerin hiçbiri yayınlanmazsa updatePublishStatus API'sini kullanarak yayınlama durumunu güncellemenizi önemle öneririz. Bu önemlidir, çünkü :

  • İçerik yayınlandığında bile tüm senaryolarda durumun sağlanması (DURUM == YAYINLANDI), entegrasyonunuzun durumunu ve diğer metriklerini iletmek için bu uygunsuz durumu kullanan kontrol panellerinin doldurulması için kritik önem taşır.
  • Hiçbir içerik yayınlanmadıysa ancak entegrasyon durumu bozuk değilse (STATUS == NOT_PUBLISHED) Google, uygulama durumu kontrol panellerinde uyarı tetiklemekten kaçınabilir. Bu işlem, sağlayıcının açısından beklenen bir durum nedeniyle içeriğin yayınlanmadığını onaylar.
  • Geliştiricilerin, verilerin ne zaman yayınlanıp yayınlanmadığına dair analizler sağlamasına yardımcı olur.
  • Google, durum kodlarını kullanıcının uygulama içeriğini görebilmesi veya aşması için uygulamada belirli işlemleri yapmasını yönlendirmek amacıyla kullanabilir.

Uygun yayınlama durum kodlarının listesi şu şekildedir :

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

Kullanıcı giriş yapmadığı için içerik yayınlanmazsa Google, Oturum Açma Kartının yayınlanmasını önerir. Sağlayıcılar Oturum Açma Kartını herhangi bir nedenle yayınlayamazsa updatePublishStatus API'sinin NOT_PUBLISHED_REQUIRES_SIGN_IN durum koduyla çağrılmasını öneririz

Kotlin


client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java


client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

deleteRecommendationClusters

Bu API, Öneri Kümelerinin içeriğini silmek için kullanılır.

Kotlin


client.deleteRecommendationClusters()

Java


client.deleteRecommendationClusters();

Hizmet, isteği aldığında mevcut verileri Öneri Kümelerinden kaldırır. Hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

deleteFeaturedCluster

Bu API, Öne Çıkan Kümenin içeriğini silmek için kullanılır.

Kotlin


client.deleteFeaturedCluster()

Java


client.deleteFeaturedCluster();

Hizmet, isteği aldığında mevcut verileri Öne Çıkan Küme'den kaldırır. Hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

deleteContinuationCluster

Bu API, Devam Kümesi içeriğini silmek için kullanılır.

Kotlin


client.deleteContinuationCluster()

Java


client.deleteContinuationCluster();

Hizmet, isteği aldığında mevcut verileri Devam Kümesi'nden kaldırır. Hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

deleteUserManagementCluster

Bu API, UserAccountManagement Cluster'ın içeriğini silmek için kullanılır.

Kotlin


client.deleteUserManagementCluster()

Java


client.deleteUserManagementCluster();

Hizmet, isteği aldığında mevcut verileri UserAccountManagement Cluster'dan kaldırır. Hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

deleteClusters

Bu API, belirli bir küme türünün içeriğini silmek için kullanılır.

Kotlin


client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      ...
      .build())

Java


client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                ...
                .build());

Hizmet isteği aldığında, belirtilen küme türleriyle eşleşen tüm kümelerden mevcut verileri kaldırır. Müşteriler bir veya daha fazla küme türünü geçirebilir. Hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

Hata işleme

Yayınlama API'lerinden gelen görev sonucunu dinlemeniz önemle tavsiye edilir. Böylece başarılı bir görevi kurtarıp yeniden göndermek için takip işlemi gerçekleştirilebilir.

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

Hata, neden hata kodu olarak eklenmiş şekilde AppEngageException biçiminde döndürülür.

Hata kodu Not
SERVICE_NOT_FOUND Hizmet belirtilen cihazda kullanılamıyor.
SERVICE_NOT_AVAILABLE Hizmet, belirtilen cihazda kullanılabilir ancak çağrı sırasında kullanılamaz (örneğin, açıkça devre dışı bırakılmıştır).
SERVICE_CALL_EXECUTION_FAILURE İleti dizisi sorunları nedeniyle görev yürütülemedi. Bu durumda, işlem yeniden denenebilir.
SERVICE_CALL_PERMISSION_DENIED Arayanın servis araması yapma izni yok.
SERVICE_CALL_INVALID_ARGUMENT İstek geçersiz veriler içeriyor (örneğin, izin verilen küme sayısından fazla).
SERVICE_CALL_INTERNAL Hizmet tarafında bir hata var.
SERVICE_CALL_RESOURCE_EXHAUSTED Servis çağrısı çok sık yapılıyor.

3. Adım: Yayın amaçlarını ele alın

Bir iş aracılığıyla publish Content API çağrıları yapmaya ek olarak, bir içerik yayınlama isteğini almak için BroadcastReceiver kurulumu da gerekir.

Yayın amaçlarının amacı, temel olarak uygulamayı yeniden etkinleştirmek ve veri senkronizasyonunu zorlamaktır. Yayın amaçları çok sık gönderilecek şekilde tasarlanmamıştır. Yalnızca İnternet Reklamcılığı Programı içeriğin eski olabileceğini (örneğin, bir haftalık) belirlediğinde tetiklenir. Bu sayede, uygulama uzun süre çalıştırılmamış olsa bile kullanıcının yeni bir içerik deneyimine sahip olabileceğine dair daha fazla güven duyulur.

BroadcastReceiver aşağıdaki iki şekilde ayarlanmalıdır:

  • Context.registerReceiver() kullanarak BroadcastReceiver sınıfının bir örneğini dinamik olarak kaydedin. Bu, hâlâ bellekte bulunan uygulamalardan iletişim kurulmasını sağlar.
class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));


// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}
  • Statik olarak AndroidManifest.xml dosyanızda <receiver> etiketiyle bir uygulama tanımlayın. Bu, uygulamanın çalışmadığında yayın amaçlarını almasına ve aynı zamanda uygulamanın içeriği yayınlamasına olanak tanır.
<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

Hizmet tarafından aşağıdaki amaçlar gönderilir:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION Bu amacı alırken bir publishRecommendationClusters çağrısı başlatmanız önerilir.
  • com.google.android.engage.action.PUBLISH_FEATURED Bu niyeti alırken bir publishFeaturedCluster araması başlatmanız önerilir.
  • com.google.android.engage.action.PUBLISH_CONTINUATION Bu amacı alırken bir publishContinuationCluster çağrısı başlatmanız önerilir.

Entegrasyon iş akışı

Entegrasyonun tamamlandıktan sonra doğrulanmasıyla ilgili adım adım açıklamalı bir kılavuz için Geliştirici entegrasyonu iş akışını etkileşim kurma başlıklı makaleyi inceleyin.

SSS

SSS için Engage SDK'sı ile İlgili Sık Sorulan Sorular bölümüne bakın.

İletişim

Entegrasyon işlemi sırasında herhangi bir sorunuz olursa lütfen engagement-developers@google.com ile iletişime geçin. Ekibimiz mümkün olan en kısa sürede size yanıt verecektir.

Sonraki adımlar

Bu entegrasyonu tamamladıktan sonra uygulamanız gereken adımlar şunlardır:

  • engagement-developers@google.com adresine e-posta gönderin ve Google tarafından test edilmeye hazır olan entegre APK'nızı ekleyin.
  • Google, entegrasyonun beklendiği gibi çalıştığından emin olmak için bir doğrulama ve dahili inceleme gerçekleştirir. Değişiklik yapılması gerekirse Google gerekli ayrıntıları vermek için sizinle iletişime geçecektir.
  • Test tamamlandığında ve herhangi bir değişiklik gerekmediğinde Google, güncellenmiş ve entegre APK'yı Play Store'da yayınlamaya başlayabileceğinizi bildirmek için sizinle iletişime geçecektir.
  • Google, güncellenen APK'nızın Play Store'da yayınlandığını onayladıktan sonra Öneri, Öne Çıkan ve Devam kümeleriniz yayınlanır ve kullanıcılar tarafından görülebilir.