Kitle verilerini tanımlama

Özel kitle, bir reklamveren uygulaması tarafından belirlenen ortak amaçlara veya ilgi alanlarına sahip bir kullanıcı grubunu temsil eder. Bir uygulama ya da SDK, belirli bir kitleyi (ör. alışveriş sepetinde ürün bırakan bir kullanıcı) belirtmek için özel kitle kullanabilir.

Android Protected Audience API, kullanıcının cihazında özel kitlelere katılmak ve bu kitlelerden ayrılmak için kullanılabilir. Özel bir kitle oluşturup bu kitleye katıldığınızda, özel kitle özelliklerinin bir kısmını veya tamamını getireceğiniz bir sunucuya yetki verebilir ya da API'yi doğrudan çağırırken bu bilgileri belirtebilirsiniz.

Özel kitleler

Aşağıdaki parametrelerin kombinasyonu, bir cihazdaki her CustomAudience nesneyi benzersiz bir şekilde tanımlar:

• owner: Sahip uygulamanın paket adı. Bu, arayan uygulamanın paket adı olarak dolaylı şekilde ayarlanır.
• buyer: Bu özel kitle için reklamları yöneten alıcı reklam ağının tanımlayıcısı.
• name: Özel kitle için rastgele bir ad veya tanımlayıcı.

Ayrıca, CustomAudience aşağıdaki zorunlu parametrelerle oluşturulmalıdır:

• Günlük güncelleme URL'si: Özel bir kitlenin kullanıcı teklifi sinyallerini, güvenilir teklif verilerini ve reklamların oluşturma URL'lerini ve meta verilerini güncellemek için arka planda günlük olarak sorgulanan bir HTTPS URL'si.
• Teklif verme mantığı URL'si: Bir alıcının JavaScript teklif verme mantığını getirmek için reklam seçimi sırasında sorgulanan bir HTTPS URL'si. Bu JavaScript'te gerekli işlev imzalarını inceleyin.
• Reklam Oluşturma Kimlikleri: Alıcı reklam teknolojisi tarafından ayarlanan rastgele bir kimliktir. Bu, B&A için yük oluşturmaya yönelik bir optimizasyondur.

CustomAudience nesnesi için isteğe bağlı parametreler şunları içerebilir:

• Etkinleştirme süresi: Özel kitleler, yalnızca etkinleştirme süresinden sonra reklam seçimine ve günlük güncellemelere katılabilir. Bu özellik, örneğin bir uygulamayı kullanmayı bırakmış kullanıcılarla yeniden etkileşim kurmak için yararlı olabilir.
• Geçerlilik bitiş zamanı: Özel kitlenin cihazdan kaldırılacağı gelecekteki bir zaman.
• Kullanıcı teklif sinyalleri: Bir alıcının teklif verme mantığı JavaScript'inin, reklam seçimi sürecinde teklif oluşturmak için kullandığı, kullanıcının tercih ettiği yerel ayar gibi kullanıcı sinyallerini içeren bir JSON dizesi. Bu biçim, reklam teknolojisi platformlarının kodları platformlar arasında yeniden kullanmasına yardımcı olur ve JavaScript işlevlerinde tüketimi kolaylaştırır.
• Güvenilir teklif verileri: Güvenilir bir anahtar/değer hizmetinden teklif sinyallerini getiren, reklam seçimi sürecinde kullanılan bir HTTPS URL'si ve bir dizi dize.
• Reklamlar: Reklam seçimine katılan reklamlara karşılık gelen AdData nesnelerinin listesi. Her AdData nesnesi şunlardan oluşur:
  • Oluşturma URL'si: Nihai reklamın oluşturulması için sorgulanan bir HTTPS URL'si.
  • Meta veri: Reklam seçimi sürecinde alıcı teklif verme mantığı tarafından kullanılacak bilgileri içeren, dize olarak serileştirilmiş bir JSON nesnesi.
  • Reklam Filtreleri: Reklam seçimi sırasında uygulama yükleme reklamı filtreleme ve sıklık sınırlama için gerekli tüm bilgileri içeren bir sınıf.

Özel kitleyi getirme ve birleştirme

fetchAndJoinCustomAudience API, alıcıların iş ortağı MMP'lerinin veya SSP'lerinin cihazdaki varlığından yararlanarak özel bir kitleye katılmayı temsilci olarak yapmasına olanak tanır.

Bu işlemin çalışması için cihaz üzerinde arayan (MMP veya SSP SDK'sı olabilir) aşağıdaki gibi görünen bir fetchAndJoinCustomAudienceRequest oluşturur:

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

val request = FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
    .setName(name)
    .setActivationTime(activationTime)
    .setExpirationTime(expirationTime)
    .setUserBiddingSignals(userBiddingSignals)
    .build()

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

FetchAndJoinCustomAudienceRequest request =
 new FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
  .setName(name) //Optional
  .setActivationTime(activationTime) //Optional
  .setExpirationTime(expirationTime) //Optional
  .setUserBiddingSignals(userBiddingSignals) //Optional
  .build();

Tüm isteğe bağlı parametrelerle ilgili önemli bir not: Bu parametreler getirme isteği içinde ayarlanırsa verileri, alıcıdan döndürülenlerle geçersiz kılınamaz. Böylece cihazdaki arayan, hangi özel kitlenin kalıcı hale getirileceği konusunda ek kontroller elde eder.

fetchUri, alıcı tarafından işletilen ve burada görülen biçime uygun bir özel kitle JSON nesnesi döndüren bir sunucu uç noktasına işaret etmelidir:

//Return a 200 response with data matching the format of the following in the body
{
  "daily_update_uri": "https://js.example.com/bidding/daily",
  "bidding_logic_uri": "https://js.example.com/bidding",
  "user_bidding_signals": {
    "valid": true,
    "arbitrary": "yes"
  },
  "trusted_bidding_data": {
    "trusted_bidding_uri": "https://js.example.com/bidding/trusted",
    "trusted_bidding_keys": [
      "key1",
      "key2"
    ]
  },
  "ads": [
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad1",
      "metadata": {
        "valid": 1
      }
    },
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad2",
      "metadata": {
        "valid": 2
      }
    }
  ]
}

Bu sorunun API tarafında nasıl çözüldüğü hakkında daha fazla bilgiyi Join CA Delegation Tasarım Önerisi'nde bulabilirsiniz.

Test

Fetch çağrısını istemci kodunun içine uygulayıp DSP tarafında Özel Kitle Verileri'ni döndürecek bir uç nokta ayarladıktan sonra Özel Kitle'ye katılma yetkisini test edebilirsiniz. Uygulamanızı çalıştırmadan önce Test kurulumu sayfasındaki komutları çalıştırmanız gerekir. Bu komutları çalıştırdıktan sonra Fetch API'yi kullanarak başarılı bir şekilde çağrı yapmaya başlayabilirsiniz.

Bu akışın bir örneğini görmek için GitHub'daki Özel Korumalı Alan Örnekleri deposuna getirme çağrıları eklenmiştir.

Doğrudan özel kitleye katılma

Özel kitle oluşturmak ve bu kitleye katılmak için ihtiyacınız olan tüm bilgilere zaten sahipseniz bunu doğrudan eşzamansız bir Protected Audience API çağrısı kullanarak yapabilirsiniz. Doğrudan özel kitle oluşturmak veya özel kitleye katılmak için aşağıdakileri yapın:

1. CustomAudienceManager nesnesini başlatın.
2. Alıcının paketi ve alakalı bir ad gibi temel parametreleri belirterek bir CustomAudience nesnesi oluşturun. Ardından, JoinCustomAudienceRequest nesnesini CustomAudience nesnesiyle başlatın.
3. JoinCustomAudienceRequest nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle eşzamansız joinCustomAudience() işlevini çağırın.

val customAudienceManager: CustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java)

// Minimal initialization of a CustomAudience object
val audience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
  JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
  context.getSystemService(CustomAudienceManager.class);

// Minimal initialization of a CustomAudience object
CustomAudience audience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

joinCustomAudience() sonuçlarını işleme

Asenkron joinCustomAudience() yöntemi, API çağrısının sonucunu bildirmek için OutcomeReceiver nesnesini kullanır.

• onResult() geri çağırması, özel kitlenin başarıyla oluşturulduğunu veya güncellendiğini gösterir.
• onError() geri çağırma işlevi iki olası durumu gösterir.
  • JoinCustomAudienceRequest geçersiz bağımsız değişkenlerle başlatılırsa AdServicesException, neden olarak IllegalArgumentException'ı gösterir.
  • Diğer tüm hatalar, neden olarak IllegalStateException ile birlikte AdServicesException alır.

joinCustomAudience() sonucunun nasıl ele alınacağına dair bir örneği aşağıda bulabilirsiniz:

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

Özel kitle bırakma

Kullanıcı artık belirli bir özel kitle için işletme ölçütlerini karşılamıyorsa bir uygulama veya SDK, özel kitleyi cihazdan kaldırmak için leaveCustomAudience() işlevini çağırabilir. Benzersiz parametrelerine göre bir CustomAudience kaldırmak için aşağıdakileri yapın:

1. CustomAudienceManager nesnesini başlatın.
2. LeaveCustomAudienceRequest öğesini özel kitlenin buyer ve name ile başlatın. Bu giriş alanları hakkında daha fazla bilgi edinmek için "Doğrudan özel kitleye katılma" başlıklı makaleyi okuyun.
3. leaveCustomAudience() yöntemini LeaveCustomAudienceRequest nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte eşzamansız olarak çağırın.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

joinCustomAudience() çağrısına benzer şekilde, OutcomeReceiver sinyalleri bir API çağrısının sonunu gösterir. Gizliliğin korunmasına yardımcı olmak için hata sonucu, dahili hatalar ile geçersiz bağımsız değişkenler arasında ayrım yapmaz. onResult() Geri çağırma, eşleşen bir özel kitle başarıyla kaldırılmış olsun veya olmasın, API çağrısı tamamlandığında çağrılır.