Esta página foi traduzida pela API Cloud Translation.

Visão geral da API Topics para dispositivos móveis

Sobre a API Topics

Na publicidade em dispositivos móveis, os anunciantes buscam veicular anúncios relevantes relacionados aos interesses do usuário. Por exemplo, para um usuário interessado por culinária, anúncios relacionados a esse assunto provavelmente vão ser mais relevantes do que anúncios de outros temas.

A publicidade contextual é baseada unicamente nos interesses derivados dos conteúdo atual que está sendo visualizado (e anunciado). Um dos benefícios da A API Topics é que ela permite apps que são úteis para o usuário, mas que talvez possam não podem ser monetizados facilmente por meio da publicidade contextual, para exibir anúncios mais relevantes ao usuário do que poderiam, o que ajuda a financiar os aplicativos que os pelo usuário.

A API Topics reconhece indicadores de interesse gerais no dispositivo com base no uso de apps do usuário. Esses indicadores, chamados de temas, são compartilhados com os anunciantes, oferecer suporte a indicadores contínuos e outros indicadores próprios sem exigir o rastreamento de usuários individuais em vários apps.

A API Topics foi projetada para oferecer suporte a SDKs de publicidade de terceiros que geralmente operam em vários aplicativos. Esse suporte é oferecido na forma de mostrar alguns dos interesses entre apps que esses SDKs normalmente fariam observar. Desenvolvedores de apps individuais não devem esperar aprender mais informações sobre os usuários.

Principais conceitos

Um tema é um conjunto de interesses legível por humanos que faz parte da taxonomia da API Topics.
O tema vai ser observado por um autor de chamada (um app ou um SDK de terceiros usado no app) se o autor tiver feito uma solicitação para a API Topics em um app associado a esse tema durante as últimas três épocas.
Uma época é um período de contabilização de um tema, como uma semana.

Como funciona

Com essa proposta, a API Topics tenta fornecer aos autores de chamada temas de publicidade de interesse gerais de acordo com a forma com que o usuário interage com os apps. Esses temas podem ser usados para complementar qualquer informação contextual relacionada ao app que pretende mostrar um anúncio e podem ser combinados para ajudar a encontrar um anúncio adequado ao usuário.

Consulte o Guia da API Topics para desenvolvedores e veja exemplos de código que demonstram como configurar a capacidade de buscar temas para publicidade com base em interesses. Observação: as APIs ainda não foram concluídas.

Os temas são selecionados em uma taxonomia predefinida de código aberto.

A plataforma usa um modelo de classificador para reconhecer os temas. A implementação da API Topics e o uso do classificador vão ser parte do Android Open Source Project e aprimorados com o tempo.

Para fins ilustrativos, o exemplo de código abaixo mostra o uso de temas para buscar um anúncio com base em interesses. As APIs usadas aqui não são finais.

// Initialize the Topics API.
…
topicsFuture = AdvertisingTopicsClient.getTopics();

// Retrieve Topics and use them in Ad request.
Futures.addCallback(
    topicsFuture,
    new FutureCallback<AdvertisingTopicsInfo>() {
        @Override
        public void onSuccess(@Nullable AdvertisingTopicsInfo topicsInfo) {
            // Sanitize Topics result.
            ...
            // Initialize ad request with Topics obtained.
            AdRequest adRequest = AdRequest.initialize(topicsInfo);
        }

        @Override
        public void onFailure(Throwable t) {
            // Handle error.
            ...
        }
});

Para entender melhor o funcionamento do modelo de classificador, você pode fazer testes para descobrir como diferentes dados do app reagem no sistema usando o Colab classificador de temas do Android (link em inglês).

Receber acesso às APIs Topics

As plataformas de adtech precisam se registrar para acessar a API Topics. Para saber mais, consulte Registrar uma conta do Sandbox de privacidade.

Detalhes

Uma vez por época (por exemplo, uma vez por semana), os cinco principais temas do usuário vão ser calculados usando informações no dispositivo.
- Quando a API Topics for chamada, a plataforma vai verificar se há um tema atribuído ao app que invocou a API. Caso não haja nenhum tema atribuído, um tema vai ser escolhido da maneira apresentada abaixo, permanecendo atribuído ao app pelo período restante da época em questão.
  - Há 95% de chances de um tema ser escolhido aleatoriamente da lista dos cinco temas principais calculados para cada época.
  - Há 5% de chances de um tema ser escolhido aleatoriamente da taxonomia.
  - Um autor de chamada pode chamar getTopics, usando o parâmetro shouldRecordObservation = false, para especificar que ele quer recuperar temas sem modificar o estado. Ou seja, os temas podem ser retornados, mas a chamada não vai ser incluída no cálculo semanal da época nem vai atualizar a lista de temas observados para esse autor.
- Cada app recebe um dos vários temas para garantir que apps diferentes recebam temas diferentes, diminuindo as chances de correlação cruzada entre os temas de um mesmo usuário.
  - Por exemplo, o app A pode ver o tema T1 do usuário, enquanto o app B pode ver o tema T2. Dessa maneira, fica mais difícil para os apps identificarem que essas informações estão associadas ao mesmo usuário.
A API Topics retorna uma lista de até três temas, sendo um para cada uma das três últimas épocas.
- Ao fornecer até três temas, os apps pouco usados vão ter temas suficientes para encontrar anúncios relevantes, enquanto os apps usados com mais frequência vão ter no máximo um novo tema por semana.
- As informações do tema retornadas incluem um ID (int) correspondente a uma entrada na taxonomia, uma versão da taxonomia e uma versão do modelo do classificador.
- Somente os autores de chamada que observaram o comportamento do usuário com um app associado ao tema em questão nas últimas três épocas vão poder receber o tema.
- Todos os temas retornados representam os interesses do usuário, e é possível selecionar qualquer um ou todos eles para personalização na sua solicitação de anúncio.

Depois que um tema é atribuído ao app que invocou a API Topics, a plataforma determina se o autor da chamada pode receber esse tema.

Somente os autores da chamada que observaram o engajamento do usuário com um app associado ao tema em questão nas últimas três épocas vão poder receber o tema.
Caso o autor da chamada não tenha chamado a API anteriormente para consultar o uso do tema em questão para um usuário de um app, o tema não vai ser incluído na lista retornada pela API.
Se o autor da chamada não recebeu nenhum tema nas últimas três épocas, a API Topics vai retornar uma lista vazia.

Por exemplo, digamos que o usuário tenha sete apps instalados no dispositivo: A, B, C, D, E, F e G. Suponha que a classificação de temas para o app e o anúncio os SDKs de tecnologia nesses apps são os seguintes:

App	Classificação dos temas	SDK de tecnologias de publicidade
A	T1, T5	ad-sdk1, ad-sdk2
B	T2	ad-sdk2
C	T3, T6	ad-sdk3, ad-sdk4
D	T1, T4	ad-sdk1
E	T5	ad-sdk4, ad-sdk5
F	T6	ad-sdk2, ad-sdk3, ad-sdk4
G	T7	ad-sdk2

Fim da semana 1: a API Topics gera os cinco temas principais do usuário para essa época.

Temas principais	Autores de chamadas que podem receber o tema
T1	ad-sdk1, ad-sdk2
T2	ad-sdk2
T3	ad-sdk3, ad-sdk4
T4	ad-sdk1
T5	ad-sdk1, ad-sdk2, ad-sdk4, ad-sdk5

Na segunda semana, se um autor de chamada de qualquer app chamar a API, a lista de temas retornados vai abranger apenas os temas em que o autor da chamada está incluído na coluna "Autores de chamadas que podem receber o tema" do app em questão naquela época.
A janela de histórico incluída no cálculo dos temas disponíveis para cada autor de chamada é de três períodos (ou três semanas).
Somente temas associados a apps que invocam a API Topics por anúncios Os SDKs são usados. Isso significa que, se um app não incluir SDKs de anúncios, que chamam a API Topics, os temas associados a esse app não contribuem para o conjunto de temas que podem ser acessados pelos SDKs de anúncios.
Um app também pode desativar de maneira declarativa a API Topics, usando novos elementos de manifesto e XML para impedir que os SDKs de anúncios usem a API nele. Os temas associados a apps desativados não vão contribuir com o cálculo de temas semanal. Este documento vai ser atualizado para incluir detalhes de implementação relacionados.

Se não houver uso suficiente do app para que a plataforma reconheça cinco temas, a plataforma pode considerar o uso de outras opções, como gerar os temas restantes de maneira aleatória.

Taxonomia

Na proposta atual, a taxonomia inicial vai incluir entre centenas e alguns milhares de temas. A proposta de taxonomia inicial vai ser compartilhada em uma atualização futura deste documento.
Essa taxonomia vai ser selecionada por análise humana para que temas sensíveis não façam parte dela.
A taxonomia vai ser personalizada para as categorias de anúncios que podem ser exibidas em apps para dispositivos móveis no Android.
A taxonomia está disponível publicamente e está sujeita a mudanças. Você pode enviar sugestões usando o botão de feedback na parte de cima desta página.

Classificador de temas

Os temas de interesse são derivados de um modelo de classificador treinado com informações de apps disponíveis publicamente, como nome e descrição de apps e nome de pacotes.

Quando o modelo de classificador é usado para inferência ao calcular os temas de uma determinada época, o conjunto de indicadores usados permanece no dispositivo. Esse conjunto de indicadores pode incluir apps instalados ou usados recentemente, e pode ser expandido para incluir outros indicadores.
Os modelos iniciais vão ser treinados pelo Google, e os dados de treinamento vão incluir marcadores selecionados por análise humana sobre as informações públicas de apps. O modelo vai estar disponível sem custo financeiro para que os apps possam fazer testes e descubram em quais temas eles se encaixam.
Os modelos iniciais vão ser treinados com base em informações disponíveis publicamente de apps de um conjunto limitado de app stores, como a Google Play Store.
É possível que um app seja associado a mais de um tema ou a nenhum ou mesmo que ele não seja adicionado ao histórico de temas do usuário. Caso um app seja associado a mais de um tema na taxonomia, o número de temas escolhidos desse app vai ser limitado aos três principais.

Controles de usuário

O modelo tem como objetivo proporcionar aos usuários a possibilidade de ver e remover os temas associados ao uso do app. O processo de implementação desse recurso de controle do usuário está em andamento e vai ser incluído em uma atualização futura.
Se o usuário desinstalar um app que contribuiu para a seleção de um tema inferido nas últimas três épocas, esse tema não vai ser removido da lista de temas retornados nessas épocas, a fim de evitar a divulgação de informações sobre desinstalação.

Para facilitar os testes relacionados à experiência do usuário, você também pode iniciar uma intent no app para ver a interface de configurações de temas da mesma forma que um usuário final veria. Confira abaixo um exemplo dessa chamada:

//Button that launches settings UI
private Button mSettingsAppButton;
private static final String RB_SETTING_APP_INTENT = "android.adservices.ui.SETTINGS";


//Does setup for button on screen that will launch settings UI to observe Topics
private void registerLaunchSettingsAppButton() {
    mSettingsAppButton.setOnClickListener(
        new View.OnClickListener() {

            @Override
            public void onClick(View view) {
                Context context = getApplicationContext();
                Intent activity2Intent = new Intent(RB_SETTING_APP_INTENT);
                activity2Intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
                context.startActivity(activity2Intent);
            }
        });
}

Registrar uma plataforma de tecnologias de publicidade

Para acessar a API Topics, todas as plataformas de adtech (incluindo a do Google) precisam: conclua o processo de inscrição.

Os desenvolvedores de apps podem gerenciar quais desenvolvedores de adtech podem acessar as APIs Topics. incluindo o ID de registro do desenvolvedor de adtechs no manifesto do app.

Criptografia dos tópicos retornados

As plataformas de adtech registradas que chamam a API Topics também precisam fornecer chaves de criptografia para garantir que os tópicos retornados possam ser lidos apenas pelo autor da chamada.

O Sandbox de privacidade vai buscar essas chaves no endpoint fornecido pela adtech. Qa a prática recomendada é atualizar as chaves com frequência, mas não do que a cada seis meses.

O Sandbox de privacidade vai pedir que as adtechs confirmem a disponibilidade do endpoint fornecidos pela adtech durante o processo de registro. Para mais detalhes sobre as ações exigidas pelas adtechs atuais e recém-registradas, consulte a seção "Inscrição". Guia do desenvolvedor.

Detalhes de criptografia

Com a introdução da criptografia, as chamadas para "GetTopics()" agora vai gerar uma resposta com uma lista de "EncryptedTopic" objetos. Descriptografar esses resultados resultará em um objeto com o mesmo formato JSON do objeto Topic anterior.

A API Topics oferece suporte à implementação one-shot da chave pública híbrida (HPKE, na sigla em inglês) Criptografia). Esperamos que o autor da chamada registrado hospede uma chave pública de 32 bits no endpoint de URL de criptografia pública fornecido durante a inscrição. Essas chaves são precisa ser codificado em Base64.

O objeto EncryptedTopic tem três campos. A lista de temas retornados pode ser obtido usando a chave privada correspondente para a chave pública.

Para fins de desenvolvimento, teste a criptografia da API Topics desativando na verificação de registro. Isso forçaria a API a usar a chave pública de teste para criptografar suas respostas. É possível descriptografar os temas criptografados usando o a chave privada correspondente.