Definiowanie danych odbiorców

Niestandardowa lista odbiorców to grupa użytkowników o wspólnych zamiarach lub zainteresowaniach, określonych przez aplikację reklamodawcy. Aplikacja lub pakiet SDK może używać niestandardowej listy odbiorców do wskazania określonej grupy, np. osób, które dodały produkty do koszyka na zakupy.

Interfejs Android Protected Audience API może służyć do dołączania do niestandardowych list odbiorców i opuszczania ich na urządzeniu użytkownika. Gdy tworzysz niestandardową listę odbiorców i dołączasz do niej, możesz albo przekazać te zadania serwerowi, z którego pobierzesz niektóre lub wszystkie właściwości niestandardowej listy odbiorców, albo możesz określić te informacje podczas bezpośredniego wywoływania interfejsu API.

Niestandardowe listy odbiorców

Kombinacja tych parametrów jednoznacznie identyfikuje każdy CustomAudience obiekt na urządzeniu:

  • owner: nazwa pakietu aplikacji właściciela. Jest ona domyślnie ustawiona na nazwę pakietu aplikacji wywołującej.
  • buyer: identyfikator sieci reklamowej kupującego, która zarządza reklamami na tej niestandardowej liście odbiorców.
  • name: dowolna nazwa lub identyfikator niestandardowej listy odbiorców.

Dodatkowo obiekt CustomAudience musi zostać utworzony z tymi wymaganymi parametrami:

  • URL codziennej aktualizacji: adres URL HTTPS, który jest codziennie sprawdzany w tle w celu aktualizacji sygnałów określania stawek użytkowników, zaufanych danych określania stawek oraz adresów URL renderowania i metadanych reklam.
  • URL logiki określania stawek: adres URL HTTPS, który jest sprawdzany podczas wyboru reklamy w celu pobrania logiki określania stawek kupującego w JavaScript. Wymagane sygnatury funkcji znajdziesz w tym kodzie JavaScript.
  • Identyfikatory renderowania reklam: dowolny identyfikator ustawiony przez technologię reklamową kupującego. Jest to optymalizacja generowania ładunku dla B&A.

Opcjonalne parametry obiektu CustomAudience mogą obejmować:

  • Czas aktywacji: niestandardowa lista odbiorców może uczestniczyć w wyborze reklam i codziennych aktualizacjach dopiero po upływie czasu aktywacji. Może to być przydatne np. do angażowania użytkowników, którzy przestali korzystać z aplikacji.
  • Czas wygaśnięcia: przyszły czas, po którym niestandardowa lista odbiorców zostanie usunięta z urządzenia.
  • Sygnały określania stawek użytkowników: ciąg znaków JSON zawierający sygnały użytkowników, np. preferowane ustawienia regionalne użytkownika, które są wykorzystywane przez logikę określania stawek kupującego w JavaScript do generowania stawek podczas procesu wyboru reklamy. Ten format pomaga platformom technologii reklamowej w ponownym wykorzystywaniu kodu na różnych platformach i ułatwia korzystanie z funkcji JavaScript.
  • Zaufane dane określania stawek: adres URL HTTPS i lista ciągów znaków używanych podczas procesu wyboru reklamy, które pobierają sygnały określania stawek z zaufanej usługi klucz/wartość.
  • Reklamy: lista obiektów AdData odpowiadających reklamom, które biorą udział w wyborze reklam. Każdy AdData obiekt składa się z tych elementów:
    • URL renderowania: adres URL HTTPS, który jest sprawdzany w celu renderowania ostatecznej reklamy.
    • Metadane: obiekt JSON serializowany jako ciąg znaków zawierający informacje, które mają być wykorzystywane przez logikę określania stawek kupującego podczas procesu wyboru reklamy.
    • Filtry reklam: klasa zawierająca wszystkie informacje niezbędne do filtrowania reklam promujących instalację aplikacji i ograniczania częstotliwości wyświetlania podczas wyboru reklamy.

Pobieranie i dołączanie do niestandardowej listy odbiorców

Interfejs fetchAndJoinCustomAudience API umożliwia kupującym delegowanie dołączania do niestandardowej listy odbiorców poprzez wykorzystanie obecności na urządzeniu ich partnerów MMP lub SSP.

Aby to działało, wywołujący na urządzeniu (MMP lub pakiet SDK SSP) tworzy fetchAndJoinCustomAudienceRequest w tym formacie:

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

Ważna uwaga dotycząca wszystkich parametrów opcjonalnych: jeśli są one ustawione w żądaniu pobrania, ich danych nie można zastąpić danymi zwróconymi przez kupującego. Dzięki temu wywołujący na urządzeniu ma dodatkową kontrolę nad tym, która niestandardowa lista odbiorców jest zachowywana.

fetchUri powinien wskazywać punkt końcowy serwera obsługiwany przez kupującego, który zwróci obiekt JSON niestandardowej listy odbiorców zgodny z tym formatem:

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

Więcej informacji o tym, jak to działa po stronie interfejsu API, znajdziesz w propozycji projektu delegowania dołączania do CA.

Testowanie

Gdy zaimplementujesz wywołanie pobierania w kodzie klienta i skonfigurujesz punkt końcowy po stronie DSP, aby zwracał dane niestandardowej listy odbiorców, możesz przetestować delegowanie dołączania do niestandardowej listy odbiorców. Zanim uruchomisz aplikację, musisz wykonać polecenia na stronie konfiguracji testowania. Po wykonaniu tych poleceń możesz zacząć wykonywać wywołania za pomocą interfejsu Fetch API.

Przykład tego procesu znajdziesz w repozytorium próbek Privacy Sandbox na GitHubie.

Bezpośrednie dołączanie do niestandardowej listy odbiorców

Jeśli masz już wszystkie informacje potrzebne do utworzenia niestandardowej listy odbiorców i dołączenia do niej, możesz to zrobić bezpośrednio za pomocą asynchronicznego wywołania interfejsu Protected Audience API. Aby bezpośrednio utworzyć niestandardową listę odbiorców lub dołączyć do niej:

  1. Zainicjuj obiekt CustomAudienceManager.
  2. Utwórz obiekt CustomAudience, określając kluczowe parametry, takie jak pakiet kupującego i odpowiednia nazwa. Następnie zainicjuj obiekt JoinCustomAudienceRequest za pomocą obiektu CustomAudience.
  3. Wywołaj asynchroniczną funkcję joinCustomAudience() za pomocą obiektu JoinCustomAudienceRequest oraz odpowiednich obiektów Executor i OutcomeReceiver.

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

Obsługa wyników funkcji joinCustomAudience()

Asynchroniczna metoda joinCustomAudience() używa obiektu OutcomeReceiver do sygnalizowania wyniku wywołania interfejsu API.

  • Wywołanie zwrotne onResult() oznacza, że niestandardowa lista odbiorców została utworzona lub zaktualizowana.
  • Wywołanie zwrotne onError() oznacza 2 możliwe warunki.

Oto przykład obsługi wyniku funkcji 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);
    }
};

Opuszczanie niestandardowej listy odbiorców

Jeśli użytkownik nie spełnia już kryteriów biznesowych dla danej niestandardowej listy odbiorców, aplikacja lub pakiet SDK może wywołać funkcję leaveCustomAudience(), aby usunąć niestandardową listę odbiorców z urządzenia. Aby usunąć CustomAudience na podstawie jej unikalnych parametrów:

  1. Zainicjuj obiekt CustomAudienceManager.
  2. Zainicjuj LeaveCustomAudienceRequest za pomocą buyer i name niestandardowej listy odbiorców. Więcej informacji o tych polach do wprowadzania danych znajdziesz w sekcji "Bezpośrednie dołączanie do niestandardowej listy odbiorców."
  3. Wywołaj asynchroniczną metodę leaveCustomAudience() za pomocą obiektu LeaveCustomAudienceRequest oraz odpowiednich obiektów Executor i OutcomeReceiver.

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

Podobnie jak w przypadku wywołania funkcji joinCustomAudience(), OutcomeReceiver sygnalizuje koniec wywołania interfejsu API. Aby chronić prywatność, wynik błędu nie rozróżnia błędów wewnętrznych i nieprawidłowych argumentów. Wywołanie zwrotne onResult() jest wywoływane po zakończeniu wywołania interfejsu API, niezależnie od tego, czy pasująca niestandardowa lista odbiorców została usunięta.