AdSelectionManager
public
class
AdSelectionManager
extends Object
java.lang.Object (link em inglês) | |
↳ | 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 informar impressões.
Resumo
Métodos públicos | |
---|---|
static
AdSelectionManager
|
get(Context context)
Método Factory 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 informado para o anúncio selecionado pela
seleção de anúncios identificada por |
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 |
void
|
selectAds(AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Seleciona um anúncio dos 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 aplicativo do autor da chamada. |
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 |
Métodos herdados | |
---|---|
Métodos públicos
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:
registerAdBeacon
é chamado mais de uma vez. Se esse erro for detectado em reportWin/reportResult, o conjunto original de pareamentos será registrado.registerAdBeacon
não tem exatamente 1 argumento dict.- 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 umAdTechIdentifier
registrado. Caso contrário, será gerado umIllegalStateException
.List of ad selection ids
precisa existir e ser proveniente de chamadasselectAds(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 umIllegalArgumentException
.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:
- o app não declarou as permissões corretas no manifesto; ou
- o app ou a entidade identificada pelo
callerAdTechIdentifier
não estão autorizados a usar a API.
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 . |