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

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

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

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

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

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

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

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

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

  • Время активации . Пользовательская аудитория может участвовать в выборе рекламы и ежедневных обновлениях только после времени ее активации. Это может быть полезно, например, для привлечения устаревших пользователей приложения.
  • Срок действия : будущее время, по истечении которого пользовательская аудитория будет удалена с устройства.
  • Сигналы пользовательских ставок : строка JSON, содержащая пользовательские сигналы, такие как предпочтительный языковой стандарт пользователя, которые JavaScript-логика назначения ставок покупателя использует для создания ставок в процессе выбора объявления. Этот формат помогает платформам рекламных технологий повторно использовать код на разных платформах и упрощает использование функций JavaScript.
  • Доверенные данные о ставках : URL-адрес HTTPS и список строк, используемых в процессе выбора объявлений, которые получают сигналы ставок от доверенной службы ключей и значений.
  • Объявления : список объектов AdData , соответствующих объявлениям, которые участвуют в выборе объявлений. Каждый объект AdData состоит из:
    • URL-адрес отображения : 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()

Ява 

/**
 * @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 должен указывать на конечную точку сервера, управляемую покупателем, который вернет объект 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 для возврата данных индивидуально настроенной аудитории, вы можете протестировать делегирование присоединения к индивидуально настроенной аудитории. Перед запуском приложения вам необходимо будет выполнить команды на странице настройки тестирования . После выполнения этих команд вы сможете начать успешно совершать вызовы с помощью Fetch API.

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

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

Если у вас уже есть вся информация, необходимая для создания пользовательской аудитории и присоединения к ней, вы можете сделать это напрямую с помощью асинхронного вызова 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)

Ява 

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

Ява 

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)

Ява 

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, независимо от того, успешно ли удалена соответствующая пользовательская аудитория.