Zielgruppendaten definieren

Eine benutzerdefinierte Zielgruppe stellt eine Gruppe von Nutzern mit gemeinsamen Absichten oder Interessen dar, die von einer Werbetreibenden-App festgelegt werden. Eine App oder ein SDK kann eine benutzerdefinierte Zielgruppe verwenden, um eine bestimmte Zielgruppe anzugeben, z. B. Nutzer, die Artikel in einem Einkaufswagen zurückgelassen haben.

Mit der Android Protected Audience API können Nutzer auf dem Gerät benutzerdefinierten Zielgruppen hinzugefügt und aus diesen entfernt werden. Wenn Sie eine benutzerdefinierte Zielgruppe erstellen und ihr beitreten, können Sie entweder an einen Server delegieren, von dem Sie einige oder alle Eigenschaften der benutzerdefinierten Zielgruppe abrufen, oder diese Informationen beim direkten Aufrufen der API angeben.

Benutzerdefinierte Zielgruppen

Jedes CustomAudience-Objekt auf einem Gerät wird durch die Kombination der folgenden Parameter eindeutig identifiziert:

  • owner: Paketname der Inhaber-App. Dieser wird implizit auf den Paketnamen der aufrufenden App festgelegt.
  • buyer: Kennung für das Anzeigennetzwerk des Käufers, das Anzeigen für diese benutzerdefinierte Zielgruppe verwaltet.
  • name: Ein beliebiger Name oder eine beliebige Kennung für die benutzerdefinierte Zielgruppe.

Außerdem muss die CustomAudience mit den folgenden erforderlichen Parametern erstellt werden:

  • URL für tägliche Aktualisierung: Eine HTTPS-URL, die täglich im Hintergrund aufgerufen wird, um die Gebotssignale, vertrauenswürdigen Gebotsdaten, Render-URLs und Metadaten für Anzeigen einer benutzerdefinierten Zielgruppe zu aktualisieren.
  • URL für Gebotslogik: Eine HTTPS-URL, die während der Anzeigenauswahl abgefragt wird, um die JavaScript-Gebotslogik eines Käufers abzurufen. Die erforderlichen Funktionssignaturen finden Sie in diesem JavaScript.
  • IDs für die Anzeigendarstellung: Eine beliebige ID, die vom Ad-Tech-Unternehmen des Käufers festgelegt wird. Dies ist eine Optimierung für die Nutzlastgenerierung für B&A.

Optionale Parameter für ein CustomAudience-Objekt können sein:

  • Aktivierungszeit: Eine benutzerdefinierte Zielgruppe kann erst nach der Aktivierungszeit an der Anzeigenauswahl und an täglichen Aktualisierungen teilnehmen. Das kann beispielsweise nützlich sein, um inaktive Nutzer einer App wieder zu aktivieren.
  • Ablaufzeit: Ein zukünftiger Zeitpunkt, nach dem die benutzerdefinierte Zielgruppe vom Gerät entfernt wird.
  • Gebotssignale für Nutzer: Ein JSON-String mit Nutzersignalen, z. B. dem bevorzugten Gebietsschema des Nutzers, der von der JavaScript-Gebotslogik eines Käufers verwendet wird, um während der Anzeigenauswahl Gebote zu generieren. Dieses Format hilft Ad-Tech-Plattformen, Code plattformübergreifend wiederzuverwenden, und erleichtert die Verwendung in JavaScript-Funktionen.
  • Vertrauenswürdige Gebotsdaten: Eine HTTPS-URL und eine Liste von Strings, die während der Anzeigenauswahl verwendet werden, um Gebotssignale von einem vertrauenswürdigen Schlüssel/Wert-Dienst abzurufen.
  • Anzeigen: Eine Liste von AdData-Objekten, die den Anzeigen entsprechen, die an der Anzeigenauswahl teilnehmen. Jedes AdData-Objekt besteht aus:
    • Render-URL: Eine HTTPS-URL, die abgefragt wird, um die endgültige Anzeige zu rendern.
    • Metadaten: Ein als String serialisiertes JSON-Objekt mit Informationen, die von der Gebotslogik des Käufers während der Anzeigenauswahl verwendet werden.
    • Anzeigenfilter: Eine Klasse, die alle erforderlichen Informationen zum Filtern von App-Install-Anzeigen und zum Festlegen der Häufigkeitsobergrenze bei der Anzeigenauswahl enthält.

Benutzerdefinierte Zielgruppe abrufen und zusammenführen

Mit der fetchAndJoinCustomAudience API können Käufer das Beitreten einer benutzerdefinierten Zielgruppe delegieren, indem sie die On-Device-Präsenz ihrer Partner-MMPs oder ‑SSPs nutzen.

Dazu erstellt der Aufrufer auf dem Gerät (entweder ein MMP- oder ein SSP-SDK) eine fetchAndJoinCustomAudienceRequest, die so aussieht:

Kotlin

/**
 * @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()

Java

/**
 * @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();

Wichtig: Wenn die optionalen Parameter in der Abrufanfrage festgelegt sind, können ihre Daten nicht durch die vom Käufer zurückgegebenen Daten überschrieben werden. So hat der Aufrufer auf dem Gerät zusätzliche Kontrolle darüber, welche benutzerdefinierte Zielgruppe beibehalten wird.

fetchUri sollte auf einen vom Käufer betriebenen Serverendpunkt verweisen, der ein JSON-Objekt für benutzerdefinierte Zielgruppen im folgenden Format zurückgibt:

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

Weitere Informationen dazu, wie dieses Problem auf der API-Seite behoben wird, finden Sie im Design Proposal for Join CA Delegation.

Test

Nachdem Sie den Fetch-Aufruf im Clientcode implementiert und auf der DSP-Seite einen Endpunkt eingerichtet haben, über den die Daten der benutzerdefinierten Zielgruppe zurückgegeben werden, können Sie die Delegierung des Beitritts zu einer benutzerdefinierten Zielgruppe testen. Bevor Sie Ihre App ausführen, müssen Sie die Befehle auf der Seite Testeinrichtung ausführen. Nachdem Sie diese Befehle ausgeführt haben, sollten Sie Anrufe mit der Fetch API starten können.

Ein Beispiel für diesen Ablauf finden Sie im Privacy Sandbox Samples-Repository auf GitHub, in dem Fetch-Aufrufe hinzugefügt wurden.

Einer benutzerdefinierten Zielgruppe direkt beitreten

Wenn Sie bereits alle Informationen haben, die Sie zum Erstellen und Beitreten einer benutzerdefinierten Zielgruppe benötigen, können Sie dies direkt über einen asynchronen Protected Audience API-Aufruf tun. So erstellen Sie eine benutzerdefinierte Zielgruppe oder treten ihr direkt bei:

  1. Initialisieren Sie das CustomAudienceManager-Objekt.
  2. Erstellen Sie ein CustomAudience-Objekt, indem Sie wichtige Parameter wie das Paket des Käufers und einen relevanten Namen angeben. Initialisieren Sie dann das JoinCustomAudienceRequest-Objekt mit dem CustomAudience-Objekt.
  3. Rufen Sie die asynchrone Funktion joinCustomAudience() mit dem JoinCustomAudienceRequest-Objekt und den relevanten Executor- und OutcomeReceiver-Objekten auf.

Kotlin

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)

Java

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

Ergebnisse von joinCustomAudience() verarbeiten

Die asynchrone Methode joinCustomAudience() verwendet das Objekt OutcomeReceiver, um das Ergebnis des API-Aufrufs zu signalisieren.

  • Der onResult()-Callback gibt an, dass die benutzerdefinierte Zielgruppe erfolgreich erstellt oder aktualisiert wurde.
  • Der onError()-Callback kann zwei mögliche Bedingungen signalisieren.

Hier ein Beispiel für die Verarbeitung des Ergebnisses von joinCustomAudience():

Kotlin

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

Java

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

Benutzerdefinierte Zielgruppe verlassen

Wenn ein Nutzer die Geschäftskriterien für eine bestimmte benutzerdefinierte Zielgruppe nicht mehr erfüllt, kann eine App oder ein SDK leaveCustomAudience() aufrufen, um die benutzerdefinierte Zielgruppe vom Gerät zu entfernen. So entfernen Sie ein CustomAudience anhand seiner eindeutigen Parameter:

  1. Initialisieren Sie das CustomAudienceManager-Objekt.
  2. Initialisieren Sie LeaveCustomAudienceRequest mit buyer und name der benutzerdefinierten Zielgruppe. Weitere Informationen zu diesen Eingabefeldern
  3. Rufen Sie die asynchrone Methode leaveCustomAudience() mit dem LeaveCustomAudienceRequest-Objekt und den relevanten Executor- und OutcomeReceiver-Objekten auf.

Kotlin

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)

Java

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

Ähnlich wie beim Aufrufen von joinCustomAudience() signalisiert OutcomeReceiver das Ende eines API-Aufrufs. Aus Datenschutzgründen wird bei einem Fehlerergebnis nicht zwischen internen Fehlern und ungültigen Argumenten unterschieden. Der onResult()-Callback wird aufgerufen, wenn der API-Aufruf abgeschlossen ist, unabhängig davon, ob eine übereinstimmende benutzerdefinierte Zielgruppe erfolgreich entfernt wurde.