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

Google, cihaz üzerinde kullanıcıların cihazlarını ve sektörlere göre uygulamalar Ayrıca kişiselleştirilmiş uygulama içeriği tüketimi için yeni ve etkileyici bir deneyim sunar. keşfedeceğiz. Bu tam ekran deneyimi, geliştirici iş ortaklarına En iyi zengin içeriklerini YouTube dışındaki özel bir kanalda sergileme fırsatı en iyi yoludur.

Bu kılavuz, geliştirici iş ortaklarının seslerini entegre etmeleri için talimatlar içerir. hem bu yeni yüzey alanını hem de içeriği doldurmak için Engage SDK'sını kullanarak mevcut Google platformlarında

Entegrasyon ayrıntıları

Terminoloji

Bu entegrasyon şu üç küme türünü içerir: Öneri, devamı ve Öne çıkan bölümleri.

• Öneri kümeleri, okunacak içerik için kişiselleştirilmiş öneriler gösterir Google Analytics 4'te e-posta alırsınız.

  Önerileriniz aşağıdaki yapıya sahiptir:

  • Öneri Kümesi: Bir kullanıcı arayüzü görünümü aynı geliştirici iş ortağından gelen önerilerle ilgilidir.

    

    'nı inceleyin.

  • Varlık: Kümedeki tek bir öğeyi temsil eden nesne. Varlık Oynatma listesi, sesli kitap, podcast ve daha fazlası olabilir. Daha fazla bilgi için Desteklenen varlık listesinin listesi için varlık verileri bölümü bulunur.

    

    'nı inceleyin.

• Devam kümesi, kullanıcıların son zamanlarda etkileşimde bulunduğu ses içeriğini gösterir birden fazla geliştirici iş ortağından gelen verileri gösterir. Her geliştirici iş ortağının aynı ülkede en fazla 10 tüzel kişi yayınlamasına izin verilir Devam kümesi.

  

  'nı inceleyin.

• Öne Çıkanlar kümesi, birden çok kaynaktan seçilen öğeleri gösterir. geliştirici iş ortaklarını tek bir kullanıcı arayüzü gruplandırmasında gösterir. Tek bir tane Öne Çıkan olacak üst kısmına yakın bir yerde, belirli bir öncelik sırasına Tüm Öneri kümelerinin üzerinde görünür. Her geliştirici iş ortağı, Öne Çıkanlar kümesinde en fazla 10 varlık yayınlamasına izin verilir.

  

  'nı inceleyin.

Ön çalışma

Minimum API düzeyi: 19

com.google.android.engage:engage-core 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.5.2'
}

Özet

Tasarım, hizmet.

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

1. adım: Öğe verilerini sağlayın

SDK'da her öğe türünü temsil eden farklı varlıklar tanımlanmıştır. Destek verdiğimiz yerler Listen kategorisi için aşağıdaki varlıklar:

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 özetlenmektedir.

MusicAlbumEntity

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

MusicArtistEntity

MusicArtistEntity nesnesi bir müzikaristi (örneğin, Adele) temsil eder.

MusicTrackEntity

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

MusicVideoEntity

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

PlaylistEntity

PlaylistEntity nesnesi, bir müzik oynatma listesini (örneğin, US Top) temsil eder 10 Oynatma Listesi).

PodcastSeriesEntity

PodcastSeriesEntity nesnesi bir podcast serisini temsil eder (örneğin, Bu American Life) tıklayın.

PodcastEpisodeEntity

PodcastEpisodeEntity nesnesi bir podcast serisini (ör. Spark Bird, Bölüm 754: This American Life).

LiveRadioStationEntity

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

AudiobookEntity

AudiobookEntity nesnesi bir sesli kitabı (örneğin, sesli kitap) temsil eder Michelle Obama tarafından Becoming gibi).

Resim özellikleri

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

Dosya biçimleri

PNG, JPG, statik GIF, WebP

Maksimum dosya boyutu

5.120 KB

Ek öneriler

• Resim güvenli alanı: Önemli içeriğinizi yatay ve dikey yönde ortalanmış olarak görüntüsüdür.

Ö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 önerilir (örneğin, WorkManager kullanarak) düzenlenecek ve düzenli olarak veya etkinlik temelli olarak (örneğin, Kullanıcı uygulamayı açtığında veya kullanıcı sepetine yeni bir ürün eklediğinde).

AppEngagePublishClient, kümeleri yayınlamaktan sorumludur. Takip edilenler İstemcide 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ı kontrol etmek ve içeriğin cihazda sunulup sunulamayacağını belirler.

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

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 nesnelerin listesini yayınlamak için kullanılır.

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

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

Hizmet isteği aldıktan sonra, bir işlem:

• Geliştirici iş ortağındaki mevcut RecommendationCluster verileri kaldırılır.
• İstekten elde edilen veriler ayrıştırılır ve güncellenen Öneride depolanır Küme.

Bir hata olması durumunda isteğin tamamı reddedilir ve mevcut durum elde edilir.

publishFeaturedCluster

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

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

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

Hizmet isteği aldıktan sonra, bir işlem:

• Geliştirici iş ortağındaki mevcut FeaturedCluster verileri kaldırılır.
• İstekteki veriler ayrıştırılır ve güncellenmiş Öne Çıkan Kümede depolanır.

Bir hata olması durumunda isteğin tamamı reddedilir ve mevcut durum elde edilir.

publishContinuationCluster

Bu API, ContinuationCluster nesnesi yayınlamak için kullanılır.

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

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

Hizmet isteği aldıktan sonra, bir işlem:

• Geliştirici iş ortağındaki mevcut ContinuationCluster verileri kaldırılır.
• İstekten elde edilen veriler ayrıştırılır ve güncellenmiş Devamlılık'ta depolanır Küme.

Bir hata olması durumunda isteğin tamamı reddedilir ve mevcut durum elde edilir.

publishUserAccountManagementRequest

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

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

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

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ıktan sonra, bir işlem:

• Geliştirici iş ortağındaki mevcut UserAccountManagementCluster verileri: emin olun.
• İstekten elde edilen veriler ayrıştırılır ve güncellenen UserAccountManagementCluster Kümesi.

Bir hata olması durumunda isteğin tamamı reddedilir ve mevcut durum elde edilir.

updatePublishStatus

Şirket içi işle ilgili herhangi bir nedenle kümelerden hiçbiri yayınlanmazsa yayınlama durumunu, updatePublishStatus API'si. Bu önemlidir, çünkü :

• İçerik yayınlandığında bile tüm senaryolarda durumu bildirmek (STATUS == YAYINLANDI), bunu kullanan gösterge tablolarının doldurulması için açık durumunu kullanarak entegrasyonunuzun durumunu ve diğer metriklerini aktarın.
• İçerik yayınlanmadıysa ancak entegrasyon durumu bozuk değilse (STATUS == NOT_PUBLISHED) kullanıyorsanız Google, uygulamada uyarıları tetiklemekten kaçınabilir. sağlık kontrol panelleridir. İçeriğin şu nedenden dolayı yayınlanmadığını onaylar: beklenen durumu ifade eder.
• Geliştiricilerin verilerin ne zaman yayınlandığı ve ne zaman yayınlandığı değil.
• Google, kullanıcıları belirli işlemleri yapmaya teşvik etmek için uygulama içeriğini görmelerine veya içeriğin üstesinden gelmelerine yardımcı olur.

Uygun yayınlama durum kodlarının listesi şunlardır :

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

İçerik, bir kullanıcının giriş yapmaması nedeniyle yayınlanmazsa Google, Oturum Açma kartını yayınlamanızı önerir. Sağlayıcılar herhangi bir nedenle Oturum Açma kartını yayınlayamazsa updatePublishStatus API'sini çağırmanızı öneririz. NOT_PUBLISHED_REQUIRES_SIGN_IN durum koduyla

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

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.

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

Hizmet isteği aldıktan sonra, mevcut verileri Öneri Kümeleri. Bir hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

deleteFeaturedCluster

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

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

Hizmet isteği aldıktan sonra, mevcut verileri Öne Çıkan Küme. Bir hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

deleteContinuationCluster

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

client.deleteContinuationCluster()

client.deleteContinuationCluster();

Hizmet isteği aldıktan sonra, mevcut verileri Devam Kümesi. Bir hata olması durumunda isteğin tamamı reddedilir ve mevcut durum korunur.

deleteUserManagementCluster

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

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

Hizmet isteği aldıktan sonra, mevcut verileri UserAccountManagement Kümesi. Bir 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.

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

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

Hizmet isteği aldıktan sonra, tüm hizmetlerden mevcut verileri belirtilen küme türleriyle eşleşen kümeler. Müşteriler, tek bir veya daha fazla bulunur. Bir hata olması durumunda, isteğin tamamı reddedilir ve mevcut durumun sürdürülmesini sağlar.

Hata işleme

Örneğin, yayınlanan API'lerin görev sonucunu dinlemeniz önerilir. bir takip eylemi uygulanarak başarılı bir görevi kurtarıp yeniden gönderin.

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, nedeni bir AppEngageException olarak döndürülür. hata kodu.

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

Bir iş üzerinden publish Content API çağrıları yapmanın yanı sıra ayarlamak için gereken Almak için BroadcastReceiver bir içerik yayınlama isteğidir.

Amaca dayalı yayınların amacı, temel olarak uygulamanın yeniden etkinleştirilmesi ve verilerin zorunlu kılınmasıdır. senkronize edin. Yayın amaçları çok sık gönderilecek şekilde tasarlanmamıştır. Yalnızca Etkileşim Hizmeti içeriğin eski olabileceğini belirlediğinde ( örneğin bir hafta önce oluşturulmuş olmalıdır). Bu şekilde kullanıcının uygulama yalnızca bir kez çalıştırılmamış olsa bile, uzun süre korunuyor.

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

• BroadcastReceiver sınıfının bir örneğini Context.registerReceiver(). Bu, uygulamalardan iletişim kurulmasını hale getirebilirsiniz.

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

}

• <receiver> AndroidManifest.xml dosya Bu, uygulamanın yayın almasına izin verir amaçlarına ulaşmasını sağlar ve ayrıca uygulamanın, uygulama daha iyi olur.

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

Aşağıdaki amaçlar, hizmet:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION. Aşağıdaki durumlarda publishRecommendationClusters araması başlatmanız önerilir: unutmayın.
• com.google.android.engage.action.PUBLISH_FEATURED. Bunu alırken publishFeaturedCluster araması başlatmanız önerilir isteyebilirsiniz.
• com.google.android.engage.action.PUBLISH_CONTINUATION. Alırken publishContinuationCluster araması başlatmanız önerilir daha iyi olur.

Entegrasyon iş akışı

İşlem tamamlandıktan sonra entegrasyonunuzu doğrulamayla ilgili adım adım açıklamalı kılavuz için Etkileşim kurma geliştirici entegrasyonu iş akışı

SSS

Etkileşim SDK'sıyla İlgili Sık Sorulan Sorular bölümüne bakın. SSS

İletişim

İletişim varsa engagement-developers@google.com entegrasyon sürecinde herhangi bir sorunuz olursa Ekibimiz en kısa sürede sizinle iletişime yapmasını sağlar.

Sonraki adımlar

Bu entegrasyonu tamamladıktan sonra şu adımları uygulayabilirsiniz:

• Şu adrese e-posta gönder: Engage-developers@google.com adresini ziyaret edin ve Google tarafından test edilmeye hazır entegre APK'nızdır.
• Google, web sitenizin alan adının entegrasyonun beklendiği gibi çalıştığından emin olun. Değişiklik gerekirse Google sizinle iletişime geçer e-posta gönderin.
• Test tamamlandığında ve değişiklik gerekmiyorsa Google, Güncellenmiş ve entegre APK'yı şurada yayınlamaya başlayabileceğinizi bildirir: Play Store'a gidin.
• Google, güncellenen APK'nızın Play Store, Öneriniz, Öne Çıkanlar ve Devam kümeler yayınlanacak ve kullanıcılar tarafından görülebilecek.