Definiowanie danych odbiorców

Lista odbiorców niestandardowych to grupa użytkowników o podobnych zamiarach lub zainteresowaniach, określonych przez aplikację reklamodawcy. Aplikacja lub pakiet SDK może używać listy odbiorców niestandardowych do wskazywania konkretnych odbiorców, np. osób, które zostawiły produkty w koszyku.

Interfejs Protected Audience API na Androidzie może służyć do dołączania do niestandardowych grup odbiorców i opuszczania ich na urządzeniu użytkownika. Podczas tworzenia listy niestandardowych odbiorców i dołączania do niej możesz przekazać do serwera, z którego pobierzesz niektóre lub wszystkie właściwości listy niestandardowych odbiorców, albo określić te informacje podczas bezpośredniego wywoływania interfejsu API.

Niestandardowi odbiorcy

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

  • owner: nazwa pakietu aplikacji będącej właścicielem. Jest ona niejawnie ustawiona na nazwę pakietu aplikacji wywołującej.
  • buyer: Identyfikator sieci reklamowej kupującego, która zarządza reklamami kierowanymi na tę niestandardową listę odbiorców.
  • name: dowolna nazwa lub identyfikator listy odbiorców niestandardowych.

Dodatkowo CustomAudience musi być utworzony z tymi wymaganymi parametrami:

  • URL codziennej aktualizacji: adres URL HTTPS odpytywany codziennie w tle w celu aktualizowania sygnałów licytowania użytkowników, zaufanych danych o licytowaniu oraz adresów URL renderowania i metadanych reklam na potrzeby niestandardowej listy odbiorców.
  • Adres URL logiki określania stawek: adres URL HTTPS, do którego wysyłane jest zapytanie podczas wybierania reklamy w celu pobrania logiki określania stawek w JavaScript kupującego. Wymagane sygnatury funkcji znajdziesz w tym kodzie JavaScript.
  • Identyfikatory renderowania reklamy: dowolny identyfikator ustawiony przez technologię reklamową kupującego. Jest to optymalizacja generowania ładunku na potrzeby B&A.

Opcjonalne parametry obiektu CustomAudience mogą obejmować:

  • Czas aktywacji: lista odbiorców niestandardowych może uczestniczyć w wybieraniu reklam i codziennych aktualizacjach dopiero po upływie czasu 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 określania stawek użytkownika: ciąg JSON zawierający sygnały użytkownika, takie jak preferowane ustawienia regionalne użytkownika, które są wykorzystywane przez kod JavaScript logiki określania stawek kupującego do generowania stawek podczas procesu wyboru reklamy. Ten format pomaga platformom technologii reklamowej ponownie wykorzystywać kod na różnych platformach i ułatwia korzystanie z funkcji JavaScriptu.
  • Zaufane dane określania stawek: adres URL HTTPS i lista ciągów znaków używane podczas procesu wyboru reklam, które pobierają sygnały określania stawek z zaufanej usługi klucz/wartość.
  • Ads: 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:
    • Adres URL renderowania: adres URL HTTPS, do którego wysyłane jest zapytanie w celu renderowania ostatecznej reklamy.
    • Metadane: obiekt JSON zserializowany jako ciąg znaków zawierający informacje, które będą wykorzystywane przez logikę określania stawek kupującego podczas procesu wyboru reklamy.
    • Filtry reklam: klasa zawierająca wszystkie niezbędne informacje do filtrowania reklam zachęcających do instalacji aplikacji i ograniczania częstotliwości wyświetlania podczas wyboru reklam.

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

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

Aby to działało, wywołujący na urządzeniu (czyli pakiet SDK MMP lub SSP) tworzy fetchAndJoinCustomAudienceRequest, który wygląda tak:

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 pobierania, ich danych nie można zastąpić danymi zwróconymi przez kupującego, co daje wywołującemu na urządzeniu dodatkową kontrolę nad tym, która lista odbiorców niestandardowych jest zachowywana.

Symbol fetchUri powinien wskazywać punkt końcowy serwera obsługiwany przez kupującego, który będzie zwracać obiekt JSON niestandardowej listy odbiorców 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 projekcie dotyczącym przekazywania uprawnień do łączenia się z urzędem certyfikacji.

Testowanie

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

Przykład tego procesu znajdziesz w wywołaniach pobierania dodanych do repozytorium przykładów Piaskownicy prywatności w GitHubie.

Bezpośrednie dołączanie do grupy odbiorców niestandardowych

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

  1. Zainicjuj 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() z obiektem JoinCustomAudienceRequest oraz odpowiednimi obiektami 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 wywołania funkcji joinCustomAudience()

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

  • Wywołanie zwrotne onResult() oznacza, że lista odbiorców niestandardowych 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 grupy odbiorców niestandardowych

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

  1. Zainicjuj obiekt CustomAudienceManager.
  2. Zainicjuj LeaveCustomAudienceRequest za pomocą buyer i name niestandardowych odbiorców. Więcej informacji o tych polach do wprowadzania danych znajdziesz w artykule „Dołączanie do odbiorców niestandardowych bezpośrednio”.
  3. Wywołaj asynchroniczną metodę leaveCustomAudience() z obiektem LeaveCustomAudienceRequest oraz odpowiednimi obiektami 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 joinCustomAudience(), znak OutcomeReceiver oznacza koniec wywołania interfejsu API. Aby chronić prywatność, wynik błędu nie rozróżnia błędów wewnętrznych od nieprawidłowych argumentów. onResult()Wywołanie zwrotne jest wywoływane po zakończeniu wywołania interfejsu API, niezależnie od tego, czy pasująca lista odbiorców niestandardowych została usunięta.