Definiowanie danych odbiorców

Lista niestandardowych odbiorców to grupa użytkowników o wspólnych zamiarach lub zainteresowaniach, jaką określa aplikacja reklamodawcy. Aplikacja lub pakiet SDK może używać listy niestandardowych odbiorców, aby wskazać konkretną grupę odbiorców, np. użytkowników, którzy porzucili produkty w koszyku.

Interfejsu Protected Audience API na Androida można używać do dołączania do niestandardowych grup odbiorców i z nich wychodzenia na urządzeniu użytkownika. Podczas tworzenia i dołączania listy odbiorców niestandardowej możesz przekazać tę funkcję serwerowi, z którego pobierzesz niektóre lub wszystkie właściwości listy odbiorców niestandardowej, albo podać te informacje bezpośrednio w wywołaniu interfejsu API.

Niestandardowi odbiorcy

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

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

Dodatkowo musisz utworzyć CustomAudience z tymi wymaganymi parametrami:

  • URL do codziennej aktualizacji: adres URL HTTPS, który jest codziennie wywoływany w tle, aby aktualizować sygnały licytowania użytkowników w listach niestandardowych, dane zaufanej licytacji oraz renderować adresy URL i metadane reklam.
  • URL logiki ustalania stawek: adres URL HTTPS zapytany podczas wyboru reklamy w celu pobrania logiki ustalania stawek w kodzie JavaScript kupującego. W tym kodzie JavaScript znajdziesz wymagane funkcje.
  • Identyfikatory renderowania reklam: dowolny identyfikator ustawiony przez technologię reklamową kupującego. Jest to optymalizacja służąca do generowania danych dla B&A.

Opcjonalne parametry obiektu CustomAudience:

  • Czas aktywacji: lista odbiorców niestandardowych może uczestniczyć w wybieraniu reklam i ich codziennych aktualizacjach dopiero po jej aktywacji. Może to być przydatne np. do ponownego zaangażowania użytkowników, którzy przestali korzystać z aplikacji.
  • Czas wygaśnięcia: przyszły czas, po którym lista niestandardowych odbiorców zostanie usunięta z urządzenia.
  • Sygnały dotyczące określania stawek przez użytkownika: ciąg znaków JSON zawierający sygnały użytkownika, np. preferowaną przez niego lokalizację, które logika JavaScript dotycząca określania stawek przez kupującego wykorzystuje do generowania stawek podczas procesu wyboru reklamy. Ten format pomaga platformom reklamowym korzystać z kodu na różnych platformach i ułatwia jego wykorzystanie w funkcjach JavaScript.
  • Zaufane dane ustalania stawek: adres URL HTTPS i lista ciągów znaków używanych podczas procesu wyboru reklam, które pobierają sygnały ustalania stawek z usługi zaufanego klucza/wartości.
  • Reklamy: lista obiektów AdData odpowiadających reklamom, które biorą udział w wybieraniu reklam. Każdy obiekt AdData składa się z tych elementów:
    • URL renderowania: adres URL HTTPS, który jest wyszukiwany w celu renderowania ostatecznej reklamy.
    • Metadane: obiekt JSON zserializowany jako ciąg znaków zawierający informacje, które są wykorzystywane przez logikę określania stawek przez kupującego podczas procesu wyboru reklamy.
    • Filtry reklam: klasa zawierająca wszystkie informacje potrzebne do filtrowania reklam w celu instalacji aplikacji i określania limitu wyświetleń na użytkownika podczas wyboru reklam.

Pobieranie i łączenie z listą odbiorców niestandardowych

Interfejs API fetchAndJoinCustomAudience pozwala kupującym delegować dołączanie do listy odbiorców niestandardowych, korzystając z obecności na urządzeniu partnerskich MMP lub SSP.

Aby to zadziałało, wywołujący na urządzeniu (czy to MMP, czy SSP SDK) fetchAndJoinCustomAudienceRequest musi wyglądać tak:

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

Ważna uwaga dotycząca wszystkich parametrów opcjonalnych: jeśli są one ustawione w ramach żądania pobierania, ich danych nie można zastąpić danymi zwracanymi przez kupującego. Dzięki temu wywołujący na urządzeniu ma większą kontrolę nad tym, jakie dane dotyczące listy niestandardowych odbiorców są zapisywane.

Wartość fetchUri powinna wskazywać punkt końcowy serwera obsługiwany przez kupującego, który zwróci obiekt JSON Custom Audience zgodny z formatem widocznym tutaj:

//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 dotyczącej delegacji dołączenia CA.

Testowanie

Po zaimplementowaniu wywołania Fetch w kodzie klienta i skonfigurowaniu punktu końcowego po stronie DSP w celu zwracania danych niestandardowych odbiorców możesz przetestować delegowanie dołączania niestandardowych odbiorców. Zanim uruchomisz aplikację, musisz uruchomić polecenia na stronie Konfiguracja testów. Po wykonaniu tych poleceń możesz zacząć wykonywać wywołania za pomocą interfejsu Fetch API.

Aby zobaczyć przykład tego procesu, do repozytorium Privacy Sandbox Samples na GitHubie dodano wywołania metody fetch.

Dołączanie bezpośrednio do grupy odbiorców niestandardowych

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

  1. Inicjuje obiekt CustomAudienceManager.
  2. Utwórz obiekt CustomAudience, podają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.
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);

Obsługa wyników funkcji joinCustomAudience()

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

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

Oto przykład obsługi wyniku funkcji joinCustomAudience():

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

Dodawanie i usuwanie odbiorców niestandardowych

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

  1. Inicjuje obiekt CustomAudienceManager.
  2. Inicjalizacja LeaveCustomAudienceRequest z użyciem wartości buyer i name z listy niestandardowych odbiorców. Więcej informacji o tych polach znajdziesz w artykule „Dołączanie bezpośrednio do listy niestandardowych odbiorców”.
  3. Wywołaj asynchroniczną metodę leaveCustomAudience() z obiektem LeaveCustomAudienceRequest oraz odpowiednimi obiektami Executor i OutcomeReceiver.
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);

Podobnie jak w przypadku wywołania joinCustomAudience(), OutcomeReceiver sygnalizuje koniec wywołania interfejsu API. Aby chronić prywatność, wynik błędu nie rozróżnia błędów wewnętrznych od nieprawidłowych argumentów. Funkcja onResult() zostaje wywołana po zakończeniu wywołania interfejsu API, niezależnie od tego, czy udało się usunąć pasującą listę odbiorców.