Esta página foi traduzida pela API Cloud Translation.

Adicionado no nível 34 da API
Também está nas Extensões de serviços de publicidade 4

AdSelectionManager

public class AdSelectionManager
extends Object

java.lang.Object
↳	android.adservices.adselection.AdSelectionManager

O AdSelection Manager oferece APIs para que apps e SDKs de anúncios executem processos de seleção de anúncios, além de no relatório de impressões.

Resumo

Métodos públicos
`static AdSelectionManager`	`get(Context context)` Método de fábrica para criar uma instância do AdSelectionManager.
`void`	`getAdSelectionData(GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)` Coleta dados de público-alvo personalizado do dispositivo.
`TestAdSelectionManager`	`getTestAdSelectionManager()`
`void`	`persistAdSelectionResult(PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)` Mantém os resultados da seleção de anúncios do lado do servidor.
`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`.
`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`.
`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.
`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.
`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)`.

Métodos herdados

Da classe


        
          java.lang.Object

`Object`	`clone()` Cria e retorna uma cópia desse objeto.
`boolean`	`equals(Object obj)` Indica se algum outro objeto é "igual a" esse.
`void`	`finalize()` Chamado pelo coletor de lixo em um objeto quando a coleta de lixo determina que não há mais referências ao objeto.
`final Class<?>`	`getClass()` Retorna a classe de execução desse `Object`.
`int`	`hashCode()` Retorna um valor de código hash para o objeto.
`final void`	`notify()` Ativa uma única linha de execução que está em espera no monitor desse objeto.
`final void`	`notifyAll()` Ativa todos os threads que estão aguardando no monitor desse objeto.
`String`	`toString()` Retorna uma representação em string do objeto.
`final void`	`wait(long timeoutMillis, int nanos)` Faz com que a linha de execução atual espere até ser ativada, normalmente sendo notificada ou interrompida, ou até que um determinado período de tempo real tenha passado.
`final void`	`wait(long timeoutMillis)` Faz com que a linha de execução atual espere até ser ativada, normalmente sendo notificada ou interrompida, ou até que um determinado período de tempo real tenha passado.
`final void`	`wait()` Faz com que a linha de execução atual espere até ser ativada, normalmente sendo notificada ou interrompida.

Métodos públicos

get

Adicionado no nível 34 da API
Também nas Extensões de serviços de publicidade 6

public static AdSelectionManager get (Context context)

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

Parâmetros
`context`	`Context`: o `Context` a ser usado. Esse valor não pode ser `null`.

Retorna
`AdSelectionManager`	Uma instância `AdSelectionManager` Esse valor não pode ser `null`.

getAdSelectionData

Adicionado no UpsideDownCakePrivacySandbox do Android

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

Parâmetros
`request`	`GetAdSelectionDataRequest`: este valor não pode ser `null`.
`executor`	`Executor`: este valor não pode ser `null`. Eventos de retorno de chamada e escuta são despachados através deste `Executor`, que oferece uma maneira fácil de controlar qual linha de execução é usados. Para enviar eventos pela linha de execução principal do você pode usar `Context.getMainExecutor()`: Caso contrário, forneça um `Executor` que seja enviado para uma linha de execução adequada.
`receiver`	`OutcomeReceiver`: este valor não pode ser `null`.

getTestAdSelectionManager

Adicionado no nível 34 da API
Também está nas Extensões de serviços de publicidade 4

public TestAdSelectionManager getTestAdSelectionManager ()

Retorna
`TestAdSelectionManager`	Esse valor não pode ser `null`.

persistAdSelectionResult

Adicionado no UpsideDownCakePrivacySandbox do Android

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.

Parâmetros
`request`	`PersistAdSelectionResultRequest`: este valor não pode ser `null`.
`executor`	`Executor`: este valor não pode ser `null`. Eventos de retorno de chamada e escuta são despachados através deste `Executor`, que oferece uma maneira fácil de controlar qual linha de execução é usados. Para enviar eventos pela linha de execução principal do você pode usar `Context.getMainExecutor()`: Caso contrário, forneça um `Executor` que seja enviado para uma linha de execução adequada.
`receiver`	`OutcomeReceiver`: este valor não pode ser `null`.

reportEvent

Adicionado no UpsideDownCakePrivacySandbox do Android

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

Parâmetros
`request`	`ReportEventRequest`: este valor não pode ser `null`.
`executor`	`Executor`: este valor não pode ser `null`.
`receiver`	`OutcomeReceiver`: este valor não pode ser `null`.

reportImpression

Adicionado no nível 34 da API
Também está nas Extensões de serviços de publicidade 4

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:

registerAdBeacon é chamado mais de uma vez. Se esse erro for capturado reportWin/reportResult, o conjunto original de pareamentos será registrado
registerAdBeacon não tem exatamente um argumento dict.
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

Parâmetros
`request`	`ReportImpressionRequest`: este valor não pode ser `null`.
`executor`	`Executor`: este valor não pode ser `null`.
`receiver`	`OutcomeReceiver`: este valor não pode ser `null`.

selectAds

Adicionado no UpsideDownCakePrivacySandbox do Android

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.

Parâmetros
`adSelectionFromOutcomesConfig`	`AdSelectionFromOutcomesConfig`: este valor não pode ser `null`.
`executor`	`Executor`: este valor não pode ser `null`. Eventos de retorno de chamada e escuta são despachados através deste `Executor`, que oferece uma maneira fácil de controlar qual linha de execução é usados. Para enviar eventos pela linha de execução principal do você pode usar `Context.getMainExecutor()`: Caso contrário, forneça um `Executor` que seja enviado para uma linha de execução adequada.
`receiver`	`OutcomeReceiver`: este valor não pode ser `null`.

selectAds

Adicionado no nível 34 da API

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.

Parâmetros
`adSelectionConfig`	`AdSelectionConfig`: este valor não pode ser `null`.
`executor`	`Executor`: este valor não pode ser `null`. Eventos de retorno de chamada e escuta são despachados através deste `Executor`, que oferece uma maneira fácil de controlar qual linha de execução é usados. Para enviar eventos pela linha de execução principal do você pode usar `Context.getMainExecutor()`: Caso contrário, forneça um `Executor` que seja enviado para uma linha de execução adequada.
`receiver`	`OutcomeReceiver`: este valor não pode ser `null`.

updateAdCounterHistogram

Adicionado no UpsideDownCakePrivacySandbox do Android

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:

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

. Um IllegalStateException vai ser retornado pelo outcomeReceiver se a chamada não não pode ser proveniente de um app com uma atividade em primeiro plano.

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

Parâmetros
`updateAdCounterHistogramRequest`	`UpdateAdCounterHistogramRequest`: este valor não pode ser `null`.
`executor`	`Executor`: este valor não pode ser `null`. Eventos de retorno de chamada e escuta são despachados através deste `Executor`, que oferece uma maneira fácil de controlar qual linha de execução é usados. Para enviar eventos pela linha de execução principal do você pode usar `Context.getMainExecutor()`: Caso contrário, forneça um `Executor` que seja enviado para uma linha de execução adequada.
`outcomeReceiver`	`OutcomeReceiver`: este valor não pode ser `null`.