AdSelectionManager

get

public static AdSelectionManager get (Context context)

Método de fábrica para criar uma instância do AdSelectionManager.

getAdSelectionData

public void getAdSelectionData (GetAdSelectionDataRequest request, 
                Executor executor, 
                OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

Coleta dados de público-alvo personalizado do dispositivo. Retorna um blob compactado e criptografado para enviar servidores de leilão para seleção de anúncios. Para mais detalhes, acesse Lances e os serviços de leilão.

Os anúncios de público-alvo personalizado precisam ter uma ad_render_id para que possam ser coletados.

Consulte AdSelectionManager#persistAdSelectionResult para saber como processar os resultados de a seleção de anúncios executada no lado do servidor com o blob gerado por esta API.

A saída é transmitida pelo receptor, que retorna um GetAdSelectionDataOutcome para uma execução bem-sucedida ou um Exception inclui o tipo de a exceção gerada e a mensagem de erro correspondente.

Se a IllegalArgumentException for gerada, ela será causada por um argumento de entrada inválido. que a API recebeu para executar a seleção de anúncios.

Se a IllegalStateException for gerada com a mensagem de erro "Falha do AdSelection". serviços", é causado por uma falha interna do serviço de seleção de anúncios.

Se a TimeoutException for gerada, isso será causado quando um tempo limite for encontrado. durante a licitação, pontuação ou processo de seleção geral para encontrar o anúncio vencedor.

Se a LimitExceededException for gerada, isso será causado quando o pacote de chamada excede os limites de taxa permitidos e é limitado.

Se o SecurityException for gerado, isso será causado quando o autor da chamada não for autorizado. ou a permissão não é solicitada.
Requer AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

getTestAdSelectionManager

public TestAdSelectionManager getTestAdSelectionManager ()

persistAdSelectionResult

public void persistAdSelectionResult (PersistAdSelectionResultRequest request, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Mantém os resultados da seleção de anúncios do lado do servidor. Para mais detalhes, acesse Lances e os serviços de leilão

Consulte AdSelectionManager#getAdSelectionData para saber como gerar um blob criptografado para executar uma seleção de anúncios no lado do servidor.

A saída é transmitida pelo receptor, que retorna uma AdSelectionOutcome para uma execução bem-sucedida, ou um Exception inclui o tipo da exceção gerada e a mensagem de erro correspondente.

Se a IllegalArgumentException for gerada, ela será causada por um argumento de entrada inválido. que a API recebeu para executar a seleção de anúncios.

Se a IllegalStateException for gerada com a mensagem de erro "Falha do AdSelection". serviços", é causado por uma falha interna do serviço de seleção de anúncios.

Se a TimeoutException for gerada, isso será causado quando um tempo limite for encontrado. durante a licitação, pontuação ou processo de seleção geral para encontrar o anúncio vencedor.

Se a LimitExceededException for gerada, isso será causado quando o pacote de chamada excede os limites de taxa permitidos e é limitado.

Se o SecurityException for gerado, isso será causado quando o autor da chamada não for autorizado. ou a permissão não é solicitada.
Requer AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

reportEvent

public void reportEvent (ReportEventRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

Notifica o serviço de que há um novo evento de anúncio a ser relatado para o anúncio selecionado pelo de seleção de anúncios identificada por adSelectionId. Um evento de anúncio é qualquer ocorrência que acontece com um anúncio associado ao adSelectionId especificado. Não há garantia de que quando o evento de anúncio será informado. A geração de relatórios de eventos pode atrasar, e os relatórios podem ser em lotes.

Usando ReportEventRequest#getKey(), o serviço vai buscar a reportingUri que foi registrado em registerAdBeacon. Consulte a documentação de reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) para saber mais sobre registerAdBeacon. Em seguida, o serviço anexa ReportEventRequest#getData() ao corpo de uma solicitação POST e envie a solicitação. O corpo da solicitação POST terá o content-type de text/plain, e os dados serão transmitidos em charset=UTF-8.

A saída é transmitida pelo receptor, que retorna um Object vazio para um executado corretamente, ou um Exception inclui o tipo da exceção gerada e o mensagem de erro correspondente.

Se a IllegalArgumentException for gerada, ela será causada por um argumento de entrada inválido. que a API recebeu para informar o evento de anúncio.

Se a IllegalStateException for gerada com a mensagem de erro "Falha do AdSelection". serviços", é causado por uma falha interna do serviço de seleção de anúncios.

Se a LimitExceededException for gerada, isso será causado quando o pacote de chamada excede os limites de taxa permitidos e é limitado.

Se o SecurityException for gerado, isso será causado quando o autor da chamada não for autorizado. ou a permissão não é solicitada.

Os eventos serão informados no máximo uma vez como uma tentativa de melhor esforço.
Requer AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

reportImpression

public void reportImpression (ReportImpressionRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

Notifica o serviço de que há uma nova impressão a ser informada para o anúncio selecionado pelo de seleção de anúncios identificada por adSelectionId. Não há garantia de quando impressão será informada. A geração de relatórios de impressões pode ser atrasada, e os relatórios podem ser em lotes.

Para calcular o URL de relatório do vendedor vencedor, o serviço busca o JavaScript do vendedor lógica do AdSelectionConfig#getDecisionLogicUri() encontrada em ReportImpressionRequest.getAdSelectionConfig(). Em seguida, o serviço executa uma das encontradas no JavaScript do vendedor chamadas reportResult, fornecendo indicadores no dispositivo como bem como ReportImpressionRequest#getAdSelectionConfig() como parâmetros de entrada.

A definição da função de reportResult é:

function reportResult(ad_selection_config, render_url, bid, contextual_signals) { return { 'status': status, 'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url } }; }

Para calcular o URL de relatório do comprador vencedor, o serviço busca o URL A lógica do JavaScript, que é buscada pelo CustomAudience.getBiddingLogicUri() do comprador. Em seguida, o serviço executa uma das funções encontradas no JS do comprador, chamada reportWin, fornecendo indicadores no dispositivo, signals_for_buyer calculados por reportResult, e métricas campos de ReportImpressionRequest#getAdSelectionConfig() como parâmetros de entrada.

A definição da função de reportWin é:

function reportWin(ad_selection_signals, per_buyer_signals, signals_for_buyer, contextual_signals, custom_audience_reporting_signals) { return {'status': 0, 'results': {'reporting_url': reporting_url } }; }

Além disso, compradores e vendedores têm a opção de se registrar para receber relatórios sobre eventos de anúncio. Para fazer isso, ele pode invocar a função registerAdBeacon fornecida pela plataforma em reportWin e reportResult para compradores e vendedores, respectivamente.

A definição da função de registerBeacon é:

function registerAdBeacon(beacons), em que beacons é um dict de string para pares de strings

Para cada evento de anúncio para o qual um comprador/vendedor tem interesse em relatórios, ele precisa adicionar um par event_key: event_reporting_uri ao dicionário beacons, em que event_key é um identificador desse evento específico. Este event_key precisa corresponder ReportEventRequest#getKey() quando o SDK invoca reportEvent(ReportEventRequest, Executor, OutcomeReceiver). Além disso, cada event_reporting_uri precisa ser analisado corretamente em um Uri. Isso será o Uri informado quando o SDK invocar reportEvent(ReportEventRequest, Executor, OutcomeReceiver).

Depois que o comprador/vendedor adicionar todas as combinações de que quer receber eventos, poderá invoque registerAdBeacon(beacons), em que beacons é o nome do dicionário usado em que os pares foram adicionados.

A registerAdBeacon gera uma TypeError nestas situações:

1. registerAdBeacon é chamado mais de uma vez. Se esse erro for capturado reportWin/reportResult, o conjunto original de pareamentos será registrado
2. registerAdBeacon não tem exatamente um argumento dict.
3. O conteúdo do argumento de 1 dict não são todos pares de String: String.

A saída é transmitida por receiver, que retorna um Object vazio. para uma execução bem-sucedida, ou uma Exception inclui o tipo da exceção gerada e a mensagem de erro correspondente.

Se a IllegalArgumentException for gerada, ela será causada por um argumento de entrada inválido. que a API recebeu para relatar a impressão.

Se a IllegalStateException for gerada com a mensagem de erro "Falha do AdSelection". serviços", é causado por uma falha interna do serviço de seleção de anúncios.

Se a LimitExceededException for gerada, isso será causado quando o pacote de chamada excede os limites de taxa permitidos e é limitado.

Se o SecurityException for gerado, isso será causado quando o autor da chamada não for autorizado. ou a permissão não é solicitada.

As impressões serão informadas no máximo uma vez como tentativa de melhor esforço.
Requer AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

selectAds

public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Seleciona um anúncio entre os resultados de seleções de anúncios executadas anteriormente.

A entrada adSelectionFromOutcomesConfig é fornecida pelo SDK de anúncios, e o objeto AdSelectionFromOutcomesConfig é transferido por uma chamada de vinculação. Por esse motivo, a o tamanho total desses objetos está vinculado às limitações de IPC do Android. Falhas na transferência do AdSelectionFromOutcomesConfig vai gerar uma TransactionTooLargeException.

A saída é transmitida pelo receptor, que retorna uma AdSelectionOutcome para uma execução bem-sucedida, ou um Exception inclui o tipo da exceção gerada e a mensagem de erro correspondente.

A entrada adSelectionFromOutcomesConfig contém:

• Seller precisa ser um AdTechIdentifier registrado. Caso contrário, IllegalStateException será gerado.
• List of ad selection ids precisa existir e vir de chamadas selectAds(AdSelectionConfig, Executor, OutcomeReceiver) originadas do mesmo aplicativo. Caso contrário, IllegalArgumentException para validação de entrada vai aumentar a listagem que viola a política IDs de seleção.
• Selection logic URI que pode seguir o HTTPS ou a seleção de anúncios pré-criada de rede.

  Se o URI segue o esquema HTTPS, o host precisa corresponder ao seller. Caso contrário, uma IllegalArgumentException será gerada.

  URIs pré-criados são uma forma de substituir uma lógica genérica pré-criada pelo JavaScripts para selectOutcome. O URI pré-criado para esse endpoint deve ser o seguinte:

  • ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>

  Se um URI pré-criado sem suporte for transmitido ou se o recurso de URI pré-criado for desativado pelo serviço, IllegalArgumentException será gerado.

  Consulte AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri para saber quais são os recursos <name> e <script-generation-parameters> obrigatórios.

Se a IllegalArgumentException for gerada, ela será causada por um argumento de entrada inválido. que a API recebeu para executar a seleção de anúncios.

Se a IllegalStateException for gerada com a mensagem de erro "Falha do AdSelection". serviços", é causado por uma falha interna do serviço de seleção de anúncios.

Se a TimeoutException for gerada, isso será causado quando um tempo limite for encontrado. durante a licitação, pontuação ou processo de seleção geral para encontrar o anúncio vencedor.

Se a LimitExceededException for gerada, isso será causado quando o pacote de chamada excede os limites de taxa permitidos e é limitado.

Se o SecurityException for gerado, isso será causado quando o autor da chamada não for autorizado. ou a permissão não é solicitada.
Requer AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

selectAds

public void selectAds (AdSelectionConfig adSelectionConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Executa o processo de seleção de anúncios no dispositivo para selecionar um anúncio de remarketing para o autor da chamada para o aplicativo.

A entrada adSelectionConfig é fornecida pelo SDK de anúncios, e o objeto AdSelectionConfig é transferido por uma chamada de vinculação. Por isso, o tamanho total desses objetos está vinculado às limitações da IPC do Android. Falhas na transferência do AdSelectionConfig vão gerar uma TransactionTooLargeException.

A entrada adSelectionConfig contém Decision Logic Uri que pode seguir os esquemas HTTPS ou pré-criados da seleção de anúncios.

Se o URI segue o esquema HTTPS, o host precisa corresponder ao seller. Caso contrário, IllegalArgumentException será gerado.

URIs pré-criados são uma forma de substituir uma lógica genérica pré-criada pelo JavaScripts para scoreAds. O URI pré-criado para esse endpoint deve ser o seguinte:

• ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>

Se um URI pré-criado sem suporte for transmitido ou se o recurso de URI pré-criado for desativado pelo serviço, IllegalArgumentException será gerado.

Consulte AdSelectionConfig.Builder#setDecisionLogicUri para conferir os <name> e <script-generation-parameters> obrigatório.

A saída é transmitida pelo receptor, que retorna uma AdSelectionOutcome para uma execução bem-sucedida, ou um Exception inclui o tipo da exceção gerada e a mensagem de erro correspondente.

Se a IllegalArgumentException for gerada, ela será causada por um argumento de entrada inválido. que a API recebeu para executar a seleção de anúncios.

Se a IllegalStateException for gerada com a mensagem de erro "Falha do AdSelection". serviços", é causado por uma falha interna do serviço de seleção de anúncios.

Se a TimeoutException for gerada, isso será causado quando um tempo limite for encontrado. durante a licitação, pontuação ou processo de seleção geral para encontrar o anúncio vencedor.

Se a LimitExceededException for gerada, isso será causado quando o pacote de chamada excede os limites de taxa permitidos e é limitado.

Se o SecurityException for gerado, isso será causado quando o autor da chamada não for autorizado. ou a permissão não é solicitada.
Requer AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

updateAdCounterHistogram

public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> outcomeReceiver)

Atualiza os histogramas de contador de um anúncio que foi selecionado anteriormente por uma chamada para selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver).

Os histogramas de contador são usados na seleção de anúncios para informar a filtragem do limite de frequência anúncios candidatos, nos quais os anúncios cujos limites de frequência foram atingidos ou excedidos são removidos da de lances durante a seleção de anúncios.

Os histogramas de contador só podem ser atualizados para anúncios especificados pelo adSelectionId especificado, retornado por uma chamada recente para a seleção de anúncios do FLEDGE no mesmo app autor da chamada.

Um SecurityException será retornado pelo outcomeReceiver se:

1. o app não tiver declarado as permissões corretas no manifesto; ou
2. o app ou a entidade identificada por callerAdTechIdentifier não estão autorizados para usar a API.

Um LimitExceededException vai ser retornado pelo outcomeReceiver se a chamada excede a limitação da API do app de chamada.

Em todos os outros casos de falha, o outcomeReceiver vai retornar um Object vazio. Para proteger a privacidade do usuário, erros internos não serão devolvidos por um exceção.
Requer AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE