AdSelectionManager

get

public static AdSelectionManager get (Context context)

Método Factory 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

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 que será enviado aos servidores de leilão para a seleção de anúncios. Para mais detalhes, acesse Explicação sobre lances e serviços de leilão.

Os anúncios de público-alvo personalizados precisam ter um ad_render_id para serem coletados.

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

A saída é transmitida pelo receptor, que retorna um GetAdSelectionDataOutcome para uma execução bem-sucedida ou um Exception inclui o tipo de 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 IllegalStateException for gerado com uma mensagem de erro "Falha nos serviços AdSelection.", isso será causado por uma falha interna do serviço de seleção de anúncios.

Se o TimeoutException for gerado, ele vai ocorrer quando um tempo limite for encontrado durante os lances, a pontuação ou o processo de seleção geral para encontrar o anúncio vencedor.

Se o LimitExceededException for gerado, ele será causado quando o pacote de chamada exceder os limites de taxa permitidos e será limitado.

Se o SecurityException for gerado, ele será causado quando o autor da chamada não é 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 callback e listener são enviados por esse Executor, oferecendo uma maneira fácil de controlar qual linha de execução é usada. Para enviar eventos com a linha de execução principal do aplicativo, use 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

public TestAdSelectionManager getTestAdSelectionManager ()

Retorna
TestAdSelectionManager	Esse valor não pode ser null.

persistênciaAdSelectionResult

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 Explicação sobre lances e 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 um AdSelectionOutcome para uma execução bem-sucedida ou um Exception inclui o tipo de 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 IllegalStateException for gerado com uma mensagem de erro "Falha nos serviços AdSelection.", isso será causado por uma falha interna do serviço de seleção de anúncios.

Se o TimeoutException for gerado, ele vai ocorrer quando um tempo limite for encontrado durante os lances, a pontuação ou o processo de seleção geral para encontrar o anúncio vencedor.

Se o LimitExceededException for gerado, ele será causado quando o pacote de chamada exceder os limites de taxa permitidos e será limitado.

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

Parâmetros
request	PersistAdSelectionResultRequest: este valor não pode ser null.
executor	Executor: este valor não pode ser null. Eventos de callback e listener são enviados por esse Executor, oferecendo uma maneira fácil de controlar qual linha de execução é usada. Para enviar eventos com a linha de execução principal do aplicativo, use 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

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 informado para o anúncio selecionado pela seleção de anúncios identificada por adSelectionId. Um evento de anúncio é qualquer ocorrência que aconteça com um anúncio associado ao adSelectionId especificado. Não há garantia sobre quando o evento de anúncio será informado. Os relatórios de eventos podem estar atrasados e os relatórios podem ser agrupados.

Usando ReportEventRequest#getKey(), o serviço buscará o reportingUri registrado em registerAdBeacon. Consulte a documentação de reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) para mais detalhes sobre registerAdBeacon Em seguida, o serviço anexa ReportEventRequest#getData() ao corpo de uma solicitação POST e envia 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 uma execução bem-sucedida ou um Exception inclui o tipo de 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 informar o evento de anúncio.

Se IllegalStateException for gerado com uma mensagem de erro "Falha nos serviços AdSelection.", isso será causado por uma falha interna do serviço de seleção de anúncios.

Se o LimitExceededException for gerado, ele será causado quando o pacote de chamada exceder os limites de taxa permitidos e será limitado.

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

Os eventos serão informados no máximo uma vez para tentar resolver o problema.
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

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 pela seleção de anúncios identificada por adSelectionId. Não há garantias sobre quando a impressão vai ser informada. Os relatórios de impressão podem estar atrasados e os relatórios podem ser agrupados.

Para calcular o URL de relatório do vendedor vencedor, o serviço busca a lógica do JavaScript do vendedor no AdSelectionConfig#getDecisionLogicUri() encontrado em ReportImpressionRequest.getAdSelectionConfig(). Em seguida, o serviço executa uma das funções encontradas no JS do vendedor, chamada reportResult, fornecendo indicadores no dispositivo, 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 a lógica JavaScript do comprador vencedor, que é buscada por CustomAudience.getBiddingLogicUri(). Em seguida, o serviço executa uma das funções encontradas no JS do comprador, chamada reportWin, fornecendo indicadores no dispositivo, signals_for_buyer calculado por reportResult e campos específicos 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úncios específicos. Para fazer isso, eles podem invocar a função registerAdBeacon fornecida pela plataforma dentro de 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 pares de strings para strings.

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

Quando o comprador/vendedor tiver adicionado todos os pareamentos para que quer receber eventos, ele pode invocar registerAdBeacon(beacons), em que beacons é o nome do dict a que os pares foram adicionados.

registerAdBeacon vai gerar uma TypeError nestas situações:

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

A saída é transmitida pelo receiver, que retorna um Object vazio para uma execução bem-sucedida, ou um Exception inclui o tipo de 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 informar a impressão.

Se IllegalStateException for gerado com uma mensagem de erro "Falha nos serviços AdSelection.", isso será causado por uma falha interna do serviço de seleção de anúncios.

Se o LimitExceededException for gerado, ele será causado quando o pacote de chamada exceder os limites de taxa permitidos e será limitado.

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

As impressões vão ser registradas 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.

Selecionar Anúncios

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

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

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

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

A entrada adSelectionFromOutcomesConfig contém:

• Seller é necessário para ser um AdTechIdentifier registrado. Caso contrário, será gerado um IllegalStateException.
• List of ad selection ids precisa existir e ser proveniente de chamadas selectAds(AdSelectionConfig, Executor, OutcomeReceiver) provenientes do mesmo aplicativo. Caso contrário, IllegalArgumentException para validação de entrada vai aumentar a listagem dos IDs que violam a seleção de anúncios.
• Selection logic URI, que pode seguir os esquemas predefinidos de HTTPS ou de seleção de anúncios.

  Se o URI seguir o esquema HTTPS, o host precisará corresponder a seller. Caso contrário, será gerado um IllegalArgumentException.

  URIs pré-criados são uma maneira de substituir para selectOutcome uma lógica predefinida genérica pelos JavaScripts necessários. O URI pré-criado para esse endpoint precisa ser a seguinte:

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

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

  Consulte AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri para <name> compatível e <script-generation-parameters> obrigatório.

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 IllegalStateException for gerado com uma mensagem de erro "Falha nos serviços AdSelection.", isso será causado por uma falha interna do serviço de seleção de anúncios.

Se o TimeoutException for gerado, ele vai ocorrer quando um tempo limite for encontrado durante os lances, a pontuação ou o processo de seleção geral para encontrar o anúncio vencedor.

Se o LimitExceededException for gerado, ele será causado quando o pacote de chamada exceder os limites de taxa permitidos e será limitado.

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

Parâmetros
adSelectionFromOutcomesConfig	AdSelectionFromOutcomesConfig: este valor não pode ser null.
executor	Executor: este valor não pode ser null. Eventos de callback e listener são enviados por esse Executor, oferecendo uma maneira fácil de controlar qual linha de execução é usada. Para enviar eventos com a linha de execução principal do aplicativo, use 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.

Selecionar Anúncios

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 aplicativo do autor da chamada.

A entrada adSelectionConfig é fornecida pelo SDK do Google Ads, e o objeto AdSelectionConfig é transferido por uma chamada de vinculação. Por esse motivo, 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 pré-criados de HTTPS ou de seleção de anúncios.

Se o URI seguir o esquema HTTPS, o host precisará corresponder a seller. Caso contrário, IllegalArgumentException será gerado.

URIs pré-criados são uma maneira de substituir para scoreAds uma lógica predefinida genérica pelos JavaScripts necessários. O URI pré-criado para esse endpoint precisa ser a seguinte:

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

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

Consulte AdSelectionConfig.Builder#setDecisionLogicUri para saber quais são os <name> compatíveis e o <script-generation-parameters> obrigatório.

A saída é transmitida pelo receptor, que retorna um AdSelectionOutcome para uma execução bem-sucedida ou um Exception inclui o tipo de 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 IllegalStateException for gerado com uma mensagem de erro "Falha nos serviços AdSelection.", isso será causado por uma falha interna do serviço de seleção de anúncios.

Se o TimeoutException for gerado, ele vai ocorrer quando um tempo limite for encontrado durante os lances, a pontuação ou o processo de seleção geral para encontrar o anúncio vencedor.

Se o LimitExceededException for gerado, ele será causado quando o pacote de chamada exceder os limites de taxa permitidos e será limitado.

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

Parâmetros
adSelectionConfig	AdSelectionConfig: este valor não pode ser null.
executor	Executor: este valor não pode ser null. Eventos de callback e listener são enviados por esse Executor, oferecendo uma maneira fácil de controlar qual linha de execução é usada. Para enviar eventos com a linha de execução principal do aplicativo, use 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.

updateAdCounterHistograma

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

Atualiza os histogramas de contador para 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 em anúncios candidatos, em que os anúncios com limites de frequência atingidos ou excedidos são removidos do processo de lances durante a seleção de anúncios.

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

Um SecurityException vai ser retornado pelo outcomeReceiver se:

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

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

Um LimitExceededException vai ser retornado pelo outcomeReceiver se a chamada exceder o limite da API do app de chamada.

Em todos os outros casos de falha, o outcomeReceiver retorna um Object vazio. Para proteger a privacidade do usuário, os erros internos não serão retornados por uma 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 callback e listener são enviados por esse Executor, oferecendo uma maneira fácil de controlar qual linha de execução é usada. Para enviar eventos com a linha de execução principal do aplicativo, use 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.