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 im Einkaufswagen gelassen haben.

Mit der Android Protected Audience API können Nutzer benutzerdefinierten Zielgruppen auf ihrem Gerät beitreten und diese verlassen. Wenn Sie eine benutzerdefinierte Zielgruppe erstellen und ihr beitreten, können Sie entweder einen Server delegieren, von dem Sie einige oder alle Eigenschaften der benutzerdefinierte Zielgruppe abrufen, oder diese Informationen angeben, wenn Sie die API direkt aufrufen.

Benutzerdefinierte Zielgruppen

Die Kombination der folgenden Parameter identifiziert jedes CustomAudience Objekt auf einem Gerät eindeutig:

  • owner: Paketname der Inhaber-App. Dieser wird implizit auf den Paketnamen der Aufrufer-App festgelegt.
  • buyer: Kennung für das Käufer-Werbenetzwerk, 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 diesen erforderlichen Parametern erstellt werden:

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

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

  • Aktivierungszeit: Eine benutzerdefinierte Zielgruppe kann erst nach ihrer Aktivierungszeit an der Anzeigenauswahl und den täglichen Aktualisierungen teilnehmen. Dies kann beispielsweise nützlich sein, um inaktive Nutzer einer App anzusprechen.
  • Ablaufzeit: Ein zukünftiger Zeitpunkt, nach dem die benutzerdefinierte Zielgruppe vom Gerät entfernt wird.
  • Gebotssignale der Nutzer: Ein JSON-String mit Nutzersignalen, z. B. dem bevorzugten Gebietsschema des Nutzers, die vom JavaScript der Gebotslogik eines Käufers verwendet werden, 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:
    • Rendering-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 für die Filterung von App Installationsanzeigen und die Häufigkeitsbegrenzung während der Anzeigenauswahl enthält.

Benutzerdefinierte Zielgruppe abrufen und ihr beitreten

Mit der fetchAndJoinCustomAudience-API können Käufer den Beitritt zu einer benutzerdefinierten Zielgruppe delegieren, indem sie die auf dem Gerät vorhandenen MMPs oder SSPs ihrer Partner 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 optionale Parameter in der Abrufanfrage festgelegt werden, können ihre Daten nicht durch die vom Käufer zurückgegebenen Daten überschrieben werden. So hat der Aufrufer auf dem Gerät mehr Kontrolle darüber, welche benutzerdefinierte Zielgruppe beibehalten wird.

Die fetchUri sollte auf einen Serverendpunkt verweisen, der vom Käufer betrieben wird und ein JSON-Objekt für die benutzerdefinierte Zielgruppe zurückgibt, das dem hier gezeigten Format entspricht:

//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 dies auf der API-Seite aufgelöst wird, finden Sie im Designvorschlag für die Delegierung des Beitritts zu benutzerdefinierten Zielgruppen.

Test

Nachdem Sie den Abruf im Clientcode implementiert und einen Endpunkt auf der DSP-Seite eingerichtet haben, um die Daten der benutzerdefinierten Zielgruppe zurückzugeben, 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. Danach sollten Sie in der Lage sein, Aufrufe mit der Fetch API auszuführen.

Ein Beispiel für diesen Ablauf finden Sie im Privacy Sandbox Samples-Repository auf GitHub.

Benutzerdefinierter 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 mit einem 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 Schlüsselparameter 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 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 joinCustomAudience() Methode verwendet das OutcomeReceiver Objekt, 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 signalisiert zwei mögliche Bedingungen.

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 der Nutzer die geschäftlichen Kriterien 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 eine CustomAudience anhand ihrer eindeutigen Parameter:

  1. Initialisieren Sie das CustomAudienceManager-Objekt.
  2. Initialisieren Sie LeaveCustomAudienceRequest mit dem buyer und name der benutzerdefinierten Zielgruppe. Weitere Informationen zu diesen Eingabefeldern finden Sie unter "Benutzerdefinierter Zielgruppe direkt beitreten."
  3. Rufen Sie die asynchrone leaveCustomAudience() Methode mit dem LeaveCustomAudienceRequest Objekt und 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 Aufruf 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.