Kitle verilerini tanımlama

Özel kitle, reklamveren uygulaması tarafından karar verilen ortak amaçları veya ilgi alanlarını paylaşan bir kullanıcı grubunu temsil eder. Bir uygulama veya SDK, belirli bir kitleyi (ör. alışveriş sepetine ürün ekleyip alışverişi tamamlamayan kullanıcılar) belirtmek için özel kitle kullanabilir.

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

Özel kitleler

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

  • owner: Sahip uygulamanın paket adı. Bu, çağıran uygulamanın paket adıyla dolaylı olarak ayarlanır.
  • buyer: Bu özel kitlenin reklamlarını yöneten alıcı reklam ağının tanımlayıcısıdır.
  • 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ı teklifli sistem sinyallerini, güvenilir teklifli sistem verilerini güncellemek ve reklamlar için URL'leri ve meta verileri oluşturmak amacıyla arka planda günlük olarak sorgulanan bir HTTPS URL'sidir.
  • Teklif verme mantığı URL'si: Alıcıya ait JavaScript teklif verme mantığını getirmek için reklam seçimi sırasında sorgulanan bir HTTPS URL'sidir. Bu JavaScript'de gerekli işlev imzalarına bakın.
  • 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şme zamanı: Özel kitleler, reklam seçimine ve günlük güncellemelere yalnızca etkinleşme zamanlarından sonra katılabilir. Bu, örneğin bir uygulamanın etkin olmayan kullanıcılarıyla etkileşime geçmek için yararlı olabilir.
  • Süre sonu: Özel kitlenin cihazdan kaldırılacağı gelecekteki bir zaman.
  • Kullanıcı teklif sinyalleri: Kullanıcının tercih ettiği yerel ayar gibi kullanıcı sinyallerini içeren bir JSON dizesi. Bu dize, reklam seçim süreci sırasında teklif oluşturmak için bir alıcının teklif mantığı JavaScript'i tarafından tüketilir. Bu biçim, reklam teknolojisi platformlarının kodu platformlar arasında yeniden kullanmasına yardımcı olur ve JavaScript işlevlerinde tüketimi kolaylaştırır.
  • Güvenilir teklifli sistem verileri: Güvenilir bir anahtar/değer hizmetinden teklifli sistem sinyalleri getiren reklam seçimi sürecinde kullanılan bir HTTPS URL'si ve dize listesi.
  • Reklamlar: Reklam seçimine katılan reklamlara karşılık gelen AdData nesnelerinin listesi. Her AdData nesnesi şunları içerir:
    • Oluşturma URL'si: Nihai reklamı oluşturmak için sorgulanan bir HTTPS URL'si.
    • Meta veri: Reklam seçim süreci sırasında alıcı teklif verme mantığı tarafından kullanılacak bilgileri içeren ve 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ırı için gerekli tüm bilgileri içeren bir sınıf.

Özel kitle getirme ve özel kitleye katılma

fetchAndJoinCustomAudience API, alıcıların iş ortağı MMP'lerinin veya SSP'lerinin cihaz üzerindeki varlığından yararlanarak özel bir kitleye katılma yetkisini devretmesine olanak tanır.

Bunun işe yaraması için cihaz üzerinde arayan (MMP veya SSP SDK'sı olsun) aşağıdaki gibi görünen bir fetchAndJoinCustomAudienceRequest oluşturur:

KotlinJava
/**
 * @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, getirme isteğinin içinde ayarlanırlarsa verilerinin Alıcı'dan döndürülen verilerle geçersiz kılınamaması ve cihaz üzerinde arayana hangi özel kitlenin devam ettirileceği konusunda ek denetimler sunmasıdır.

fetchUri, Alıcı tarafından işletilen ve burada görülen biçimle eşleşen bir Özel Kitle JSON nesnesi döndürecek bir sunucu uç noktasını 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üleceği hakkında daha fazla bilgiyi Join CA Delegation için Tasarım Önerisi'nde bulabilirsiniz.

Test

Getir çağrısını istemci kodunun içine uyguladıktan ve DSP tarafında Özel Kitle verilerini döndürmek için bir uç nokta oluşturduktan sonra, Özel Kitleye katılma yetkilendirmesini 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ışa örnek olarak, getirme çağrıları GitHub'daki Privacy Sandbox Örnekleri deposuna eklenmiştir.

Özel bir kitleye doğrudan katılma

Özel kitle oluşturmak ve katılmak için ihtiyacınız olan tüm bilgilere sahipseniz bunu doğrudan asenkron bir Protected Audience API çağrısı kullanarak yapabilirsiniz. Doğrudan özel kitle oluşturmak veya bir ö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 birlikte asenkron joinCustomAudience()'ü çağırın.
KotlinJava
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ğırma, özel kitlenin başarıyla oluşturulduğunu veya güncellendiğini gösterir.
  • onError() geri çağırma, iki olası durumu belirtir.

joinCustomAudience() sonucunun işlenmesiyle ilgili bir örneği aşağıda bulabilirsiniz:

KotlinJava
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 kitleden ayrılma

Kullanıcı artık belirli bir özel kitlenin işletme ölçütlerini karşılamıyorsa uygulama veya SDK, özel kitleyi cihazdan kaldırmak için leaveCustomAudience() işlevini çağırabilir. Bir CustomAudience parametrelerine göre 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 bir kitleye katılma" başlıklı makaleyi okuyun.
  3. LeaveCustomAudienceRequest nesnesi ve ilgili Executor ve OutcomeReceiver nesneleriyle birlikte asenkron leaveCustomAudience() yöntemini çağırın.
KotlinJava
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, 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. Eşleşen bir özel kitlenin başarıyla kaldırılıp kaldırılmadığına bakılmaksızın, API çağrısı tamamlandığında onResult() geri çağırma işlevi çağrılır.