SDK Kümesi yayınlama yönergeleri

Bu kılavuzda, geliştiricilerin Engage SDK'sı ile entegrasyon yaparken kullanabileceği, küme yayınlamayla ilgili bir dizi yönerge yer alır.

Öneri kümeleri

Küme Başlığı

Kullanıcılara kümenin içeriği hakkında daha fazla bilgi sağlayan benzersiz ve alakalı bir küme başlığı sağlamanızı öneririz.

İçeriğe göre iyi küme başlıklarına bazı örnekler aşağıda verilmiştir:

  • Alışverişle ilgili kümeler
    • Yıldırım Fırsatları
    • Haftalık satın alımlar
    • Pixel Buds satın alma işleminizle ilgili
    • Kadın yağmur botları
  • Sağlık konulu kitaplar
    • Sağlık, zihin ve beden
    • Sağlık uygulamasında sizin için önerilenler
    • Fitness alanında çok satanlar

Küme İçeriği

Öneri kümeleri yayınlarken kullanıcının, geliştiricinin uygulamasında oturum açmış olup olmadığını dikkate alması gerekir.

Kullanıcı oturum açtığında

Kullanıcı, geliştirici uygulamasında oturum açmışsa kişiselleştirilmiş veya kullanıcı tarafından oluşturulan içerik kümeleri yayınlamanızı öneririz. Kişiselleştirilmiş ve kullanıcı tarafından oluşturulan içerik kullanıcı açısından daha alakalı olduğundan, kullanıcılar geliştirici uygulamasını Google yüzeyinden ziyaret etmeye daha istekli olur.

  • Kişiselleştirilmiş öneriler yayınlanabilir.
    • Kişiselleştirilmiş önerilerle ilgili bazı örnekleri aşağıda bulabilirsiniz:
      • Kullanıcının izleme geçmişine dayalı en iyi seçimler.
      • Kullanıcının okuma geçmişindeki kitaplara benzer kitaplar.
      • Kullanıcının en sevdiği sanatçıların şarkıları.
  • Kullanıcı tarafından oluşturulan içerik kitaplıkları yayınlanabilir.
    • Kullanıcı tarafından oluşturulan içerik kitaplıklarıyla ilgili bazı örnekleri aşağıda bulabilirsiniz:
      • Geliştirici uygulamasındaki kullanıcının izleme listesi.
      • Geliştirici uygulamasında kullanıcının en sevdiği sanatçıların yer aldığı bir liste
Öneri türü İçerik güncelliği stratejisi İçeriğin güncelliğiyle ilgili yönerge
Kişiselleştirilmiş öneriler

Renk Uyumlu

Kullanıcıların yeni önerileri her gün görebilmesi için önerileri günde bir kez güncellemenizi öneririz.

 Kullanıcılar öneri içeriğinin nasıl olacağına dair kesin bir beklenti içinde olmadıklarından içerik güncelliği stratejisi esnek olabilir.
Kullanıcı tarafından oluşturulan içerik kitaplıkları

Yüksek Düzeyli

Kullanıcılar geliştirici uygulamasından çıktıkça içerik kitaplığını güncellemenizi öneririz.

 Bu içeriğin Google platformlarında gösterilen verilerle senkronize olması önemlidir. Bunun nedeni, kişiselleştirilmiş önerilerin aksine kullanıcının belirli bir içerik grubunu beklemesidir. Yayınlamadaki önemli bir gecikme kullanıcıların kafasını karıştırır. Bu nedenle, içerik güncelliği stratejisi katı olmalıdır.

Kullanıcı oturum açmadığında

Bir kullanıcı geliştirici uygulamasında oturum açmamışsa yine de kullanıcıların Google yüzeyinden geliştirici uygulamasını ziyaret etmesini sağlamak için kümeler yayınlamanızı öneririz.

  • Kişiselleştirilmemiş öneri kümeleri yayınlanmalıdır.
    • Aşağıda, kişiselleştirilmemiş önerilerle ilgili bazı örnekler verilmiştir:
      • Bu yıl en çok okunan 10 kitap.
      • Yeni yayınlanan filmler.
      • Trend podcast'ler.
  • Bir oturum açma kartı yayınlayın.
    • Geliştiriciler, kullanıcıları geliştirici uygulamasında oturum açmaya teşvik etmek için kişiselleştirilmemiş öneri kümesiyle birlikte bir oturum açma kartı yayınlamayı tercih edebilir. Oturum Açma Kartının nasıl yayınlanacağıyla ilgili daha fazla bilgi için aşağıdaki bölüme göz atın.
Öneri türü İçerik güncelliği stratejisi İçeriğin güncelliğiyle ilgili yönerge
Kişiselleştirilmemiş öneriler

Renk Uyumlu

Önerileri günde bir kez güncellemenizi öneririz.

 Kullanıcılar öneri içeriğinin nasıl olacağına dair kesin bir beklenti içinde olmadıklarından içerik güncelliği stratejisi esnek olabilir.
Oturum açma kartı önerileri

Yüksek Düzeyli

Kullanıcılar geliştirici uygulamasından çıktıkça oturum açma kartı durumunu güncellemenizi öneririz.

Kullanıcılar oturum açtıktan sonra geliştiricilerin deleteUserManagementCluster() API'yi çağırarak kartı silmeleri gerekir.

Oturum açma durumunun Google platformuyla senkronize olması önemlidir. Bir kullanıcının önceden oturum açmış durumdayken Google yüzeyinde bir oturum açma kartı görmesi kafa karıştırıcıdır. Bu nedenle, içerik güncelliği stratejisi katı olmalıdır.

Devam kümeleri

Devamlı kümeler yayınlarken geliştiriciler, kullanıcının geliştiricinin uygulamasında oturum açıp açmadığını dikkate almalıdır.

Kullanıcı oturum açtığında

  • Kullanıcı tarafından oluşturulan devam kümeleri yayınlanmalıdır.
    • Aşağıda, kullanıcı tarafından oluşturulan devam kümeleriyle ilgili bazı örnekler verilmiştir:
      • İzlemeye kullanıcının kaldığı yerden devam etme
      • Kullanıcının kaldığı yerden Okumaya devam et.
Devam türü İçerik güncelliği stratejisi İçeriğin güncelliğiyle ilgili yönerge
Kullanıcı tarafından oluşturulan devam kümeleri

Yüksek Düzeyli

Kullanıcılar geliştirici uygulamasından çıktıkça içerik kitaplığını güncellemenizi öneririz.

 Bu içeriğin Google platformlarında görüntülenen verilerle senkronize olması önemlidir. Bunun nedeni, kişiselleştirilmiş önerilerin aksine kullanıcının belirli bir içerik grubunu beklemesidir. Yayınlamadaki önemli bir gecikme kullanıcıların kafasını karıştırır. Bu nedenle, içerik güncelliği stratejisi katı olmalıdır.

Kullanıcı oturum açmadığında

Devam yolculukları özellikle oturum açmış kullanıcılara yöneliktir. Bununla birlikte, uygulamanız misafir oturumlarını destekliyorsa oturumu kapalı olan kullanıcılar için de devam kümeleri yayınlayabilirsiniz.

Kullanıcı Yönetimi Kümesi

Kullanıcı Yönetimi Kümesi'nin asıl amacı, kullanıcıları sağlayıcı uygulamasında belirli işlemler yapmaya teşvik etmektir. 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.

Oturum Açma Kartı

Özellik Şartlar Açıklama
İşlem URI'sı Zorunlu İşleme derin bağlantı (ör. uygulamanın 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 Karttaki Başlık
İşlem Metni İsteğe bağlı CTA'da Gösterilen Metin (ör. Oturum Aç)
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()

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

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

Kullanıcılar oturum açtıktan sonra geliştiricilerin deleteUserManagementCluster() API'yi çağırarak kartı silmeleri gerekir.

Yayınlama Durumunu Güncelle

İşle ilgili herhangi bir nedenden dolayı kümelerden hiçbiri yayınlanmazsa updateYayınlamaDurum API'sini kullanarak yayınlama durumunu güncellemenizi önemle öneririz. Bu önemlidir, çünkü :

  • Tüm senaryolarda durumu sağlamak, içerik yayınlandığında bile (DURUM == YAYINLANDI), entegrasyonunuzun durumunu ve diğer metriklerini iletmek için bu açık durumu kullanan kontrol panellerinin doldurulması için son derece önemlidir.
  • 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 onay, içeriğin sağlayıcının bakış açısından beklenen bir durum nedeniyle 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ı kullanarak kullanıcıyı uygulama içinde belirli işlemleri yapmaya teşvik edebilir. Böylece kullanıcı, uygulama içeriğini görebilir veya içeriği aşabilir.

Uygun yayınlama durum kodlarının listesi şöyledir :

// 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, kullanıcı giriş yapmadığı için yayınlanmıyorsa Oturum Açma Kartı'nı yayınlamanızı öneririz. Sağlayıcılar herhangi bir nedenle Oturum Açma Kartı'nı yayınlayamazsa updateYayınlamaDurum API'sini NOT_PUBLISHED_REQUIRES_SIGN_IN durum koduyla çağırmanızı ö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());

Küme yayınlama için WorkManager

WorkManager'ı, yürütme işleminin hem fırsatlı hem de garantili olması gereken arka plan çalışmaları için önerilen çözüm olduğundan kümeleri yayınlamak için kullanmanızı öneririz.

  • WorkManager, arka plandaki işlerinizi mümkün olan en kısa sürede gerçekleştirir.
  • WorkManager, kullanıcı uygulamanızdan ayrılsa bile çeşitli koşullar altında çalışmanıza başlamak için gereken mantığı yönetir.

Kullanıcı uygulamadan ayrıldığında, öneri kümeleriyle birlikte devam kümeleri yayınlayan bir arka plan işi başlatmanızı öneririz. Kullanıcı uygulamadan ayrıldığında çağrılan Activity.onStop(), bu mantığı yönetmek için iyi bir yerdir.

Kümeleri 24 saatte bir yayınlayan yinelenen bir iş planlamak için PeriodicWorkRequest kullanmanızı öneririz. İşi tetiklemek için bir CANCEL_AND_REENQUEUE politikası kullanarak, geliştiriciler, kullanıcı uygulamadan her ayrıldığında WorkManager'ın güncellenmiş verileri göndermesini sağlayabilir. Bu, kullanıcıların eski verileri görmesini önlemeye yardımcı olur.

Aşağıdaki örnekte bu durum gösterilmektedir:

// Define the PublishClusters Worker requiring input
public class PublishClusters extends Worker {

   public PublishClusters(Context appContext, WorkerParameters workerParams) {
       super(appContext, workerParams);
   }

   @NonNull
   @Override
   public Result doWork() {
       // publish clusters
   }
   ...
}

public static void schedulePublishClusters(Context appContext) {
// Create a PeriodicWorkRequest to schedule a recurring job to update
// clusters at a regular interval
PeriodicWorkRequest publishClustersEntertainmentSpace =
// Define the time for the periodic job
       new PeriodicWorkRequest.Builder(PublishClusters.class, 24, TimeUnit.HOURS)
// Set up a tag for the worker.
// Tags are Unique identifier, which can be used to identify that work
// later in order to cancel the work or observe its progress.
          .addTag("Publish Clusters to Entertainment Space")
          .build();

// Trigger Periodic Job, this will ensure that the periodic job is triggered
// only once since we have defined a uniqueWorkName
WorkManager.getInstance(appContext).enqueueUniquePeriodicWork(
// uniqueWorkName
     "publishClustersEntertainmentSpace",
// If a work with the uniqueWorkName is already running, it will cancel the
// existing running jobs and replace it with the new instance.
// ExistingPeriodicWorkPolicy#CANCEL_AND_REENQUEUE
     ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
// Recurring Work Request
publishClustersEntertainmentSpace);

}

Yayın amaçlarını işleme

Bir iş üzerinden publish Content API çağrıları yapmanın yanı sıra içerik yayınlama isteğini almak için bir BroadcastReceiver ayarlanması da gerekir.

Ancak, yalnızca belirli senaryolarda (özellikle uygulamanın yeniden etkinleştirilmesi ve veri senkronizasyonunu zorunlu kılma gibi) tetiklendiği için geliştiriciler yalnızca yayınlara bağlı kalmamaya dikkat etmelidir. Yalnızca İnternet Reklamcılığı Programı Hizmeti içeriğin eski olabileceğini belirlediğinde tetiklenir. Bu şekilde, uygulama uzun süredir açılmamış olsa bile kullanıcının yeni bir içerik deneyimi yaşayacağına dair güven artar.

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

  • Context.registerReceiver() ile BroadcastReceiver sınıfının bir örneğini dinamik olarak kaydedin. Bu da hâlâ bellekte bulunan uygulamalardan iletişim kurulmasını sağlar.
  • 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.