Определите данные об аудитории

Пользовательская аудитория представляет собой группу пользователей с общими намерениями или интересами, определяемую рекламным приложением. Приложение или SDK могут использовать пользовательскую аудиторию для обозначения конкретной группы пользователей, например, тех, кто оставил товары в корзине покупок.

API защищенных аудиторий Android можно использовать для присоединения к пользовательским аудиториям и выхода из них на устройстве пользователя. При создании и присоединении к пользовательской аудитории вы можете либо делегировать запрос серверу, с которого будете получать некоторые или все свойства пользовательской аудитории, либо указать эту информацию при прямом вызове API .

Пользовательские аудитории

Сочетание следующих параметров однозначно идентифицирует каждый объект CustomAudience на устройстве:

  • owner : Имя пакета приложения-владельца. По умолчанию устанавливается имя пакета вызывающего приложения.
  • buyer : Идентификатор рекламной сети покупателя, которая управляет показом рекламы для этой пользовательской аудитории.
  • name : Произвольное имя или идентификатор для пользовательской аудитории.

Кроме того, необходимо создать объект CustomAudience со следующими обязательными параметрами:

  • URL для ежедневного обновления : HTTPS-адрес, который ежедневно запрашивается в фоновом режиме для обновления сигналов ставок пользователей пользовательской аудитории, достоверных данных о ставках, а также URL-адресов отображения и метаданных для объявлений.
  • URL-адрес логики назначения ставок : HTTPS-адрес, запрашиваемый во время выбора объявления для получения логики назначения ставок покупателя в JavaScript. См. необходимые сигнатуры функций в этом JavaScript-коде.
  • Идентификаторы рендеринга рекламы : произвольный идентификатор, устанавливаемый рекламной платформой покупателя. Это оптимизация для генерации полезной нагрузки для B&A .

В качестве необязательных параметров для объекта CustomAudience могут выступать следующие:

  • Время активации : Пользовательская аудитория может участвовать в выборе рекламы и ежедневных обновлениях только после времени активации. Это может быть полезно, например, для привлечения пользователей, которые перестали пользоваться приложением.
  • Срок действия : Будущий момент времени, по истечении которого пользовательская аудитория будет удалена с устройства.
  • Сигналы для ставок пользователя : строка JSON, содержащая сигналы пользователя, такие как предпочитаемая языковая версия, которые JavaScript-код логики ставок покупателя использует для генерации ставок в процессе выбора рекламы. Этот формат помогает платформам рекламных технологий повторно использовать код на разных платформах и упрощает его использование в функциях JavaScript.
  • Достоверные данные для торгов : URL-адрес HTTPS и список строк, используемых в процессе выбора объявлений для получения сигналов торгов от доверенного сервиса «ключ/значение».
  • Ads : Список объектов AdData , соответствующих объявлениям, участвующим в выборе рекламы. Каждый объект AdData состоит из:
    • URL для отображения : HTTPS-адрес, используемый для отображения конечного рекламного объявления.
    • Метаданные : JSON-объект, сериализованный в строку, содержащий информацию, используемую логикой формирования ставок покупателями в процессе выбора объявления.
    • Фильтры рекламы : Класс, содержащий всю необходимую информацию для фильтрации рекламы при установке приложений и ограничения частоты показа рекламы во время её выбора.

Получить и присоединиться к пользовательской аудитории

API fetchAndJoinCustomAudience позволяет покупателям делегировать присоединение к пользовательской аудитории, используя данные о присутствии на устройствах их партнеров — MMP-платформ или SSP-сервисов.

Для корректной работы этой функции вызывающий процесс на устройстве (будь то MMP или SSP SDK) создает запрос fetchAndJoinCustomAudienceRequest , который выглядит следующим образом:

Котлин 

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

Важно отметить, что если все необязательные параметры заданы внутри запроса на получение данных, их значения не могут быть переопределены данными, возвращаемыми от покупателя, что дает вызывающей стороне устройства дополнительные возможности управления сохранением пользовательской аудитории.

Параметр fetchUri должен указывать на серверную конечную точку, управляемую Покупателем, которая вернет объект Custom Audience в формате JSON, соответствующем представленному здесь формату:

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

Более подробную информацию о том, как это решается на стороне API, можно найти в проекте решения для делегирования полномочий центру сертификации при присоединении .

Тестирование

После того, как вы реализовали вызов Fetch в клиентском коде и настроили конечную точку на стороне DSP для возврата данных пользовательской аудитории, вы можете протестировать делегирование присоединения к пользовательской аудитории. Перед запуском приложения вам необходимо выполнить команды на странице настройки тестирования . После выполнения этих команд вы сможете успешно совершать вызовы с помощью API Fetch.

Чтобы увидеть пример такого алгоритма, в репозиторий Privacy Sandbox Samples на GitHub были добавлены вызовы функции fetch.

Присоединяйтесь к пользовательской аудитории напрямую

Если у вас уже есть вся необходимая информация для создания и присоединения к пользовательской аудитории, вы можете сделать это напрямую, используя асинхронный вызов API защищенной аудитории. Чтобы создать или присоединиться к пользовательской аудитории напрямую, выполните следующие действия:

  1. Инициализируйте объект CustomAudienceManager .
  2. Создайте объект CustomAudience , указав ключевые параметры, такие как пакет услуг покупателя и соответствующее имя. Затем инициализируйте объект JoinCustomAudienceRequest объектом CustomAudience .
  3. Вызовите асинхронный joinCustomAudience() с объектом JoinCustomAudienceRequest и соответствующими объектами Executor и OutcomeReceiver .

Котлин 

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

Обрабатывайте результаты функции joinCustomAudience()

Асинхронный метод joinCustomAudience() использует объект OutcomeReceiver для передачи результата вызова API.

  • Функция обратного вызова onResult() означает, что пользовательская аудитория успешно создана или обновлена.
  • Функция обратного вызова onError() указывает на два возможных условия.
    • Если объект JoinCustomAudienceRequest инициализирован недопустимыми аргументами, в сообщении AdServicesException будет указано исключение IllegalArgumentException как причина.
    • Все остальные ошибки сопровождаются исключением AdServicesException с указанием причины IllegalStateException .

Вот пример обработки результата вызова joinCustomAudience() :

Котлин 

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

Укажите пользовательскую аудиторию

Если пользователь больше не соответствует бизнес-критериям для заданной пользовательской аудитории, приложение или SDK могут вызвать метод leaveCustomAudience() для удаления пользовательской аудитории с устройства. Чтобы удалить CustomAudience на основе ее уникальных параметров, выполните следующие действия:

  1. Инициализируйте объект CustomAudienceManager .
  2. Инициализируйте объект LeaveCustomAudienceRequest указав buyer и name пользовательской аудитории. Для получения дополнительной информации об этих полях ввода, прочитайте статью « Присоединиться к пользовательской аудитории напрямую ».
  3. Вызовите асинхронный метод leaveCustomAudience() с объектом LeaveCustomAudienceRequest и соответствующими объектами Executor и OutcomeReceiver .

Котлин 

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

Аналогично вызову joinCustomAudience() , OutcomeReceiver сигнализирует об окончании вызова API. Для защиты конфиденциальности результат ошибки не различает внутренние ошибки и недопустимые аргументы. Функция обратного вызова onResult() вызывается после завершения вызова API, независимо от того, было ли успешно удалено соответствующее пользовательское окружение.