API Topics para dispositivos móveis: visão geral

Saiba mais sobre a API Topics no Android e as etapas envolvidas na implementação. Você também pode implementar temas.

How the Topics API works

The Topics API can be used to observe and provide access to topics that appear to be of interest to the user, based on their activity. The Topics API can then give API callers (such as ad tech platforms) access to a user's topics of interest, but without revealing additional information about the user's activity.

Key concepts

• A topic is a human-readable topic of interest for the current user and is part of the Topics taxonomy.
• A caller is an entity, such as an app, a third-party SDK, a website, or service, that makes a request to the Topics API to observe or access a user's interests.
• A topic is observed by a caller, if the caller made a Topics API request from a web page or app associated with this topic during the past three epochs.
• An epoch is a period of topic computation, which defaults to one week.
• A taxonomy is a hierarchical list of categories, which includes, for example, such categories as /Arts & Entertainment/Music & Audio/Soul & R&B and /Business & Industrial/Business Services/Corporate Events.
• Topics are derived using a classifier model that maps user activity to zero or more topics.

Topics API flow core steps

The Topics API lifecycle has three main steps:

• Observe user activity, such as when they visit the web page https://cats.example/tabby/index.html or download the app cats.
• Derive topics from user activity, for example /Pets & Animals/Pets/Cats.
• Access topics previously observed for the user, for example as a signal to select relevant advertising (such as a cat food promotion).

Observe topics

Callers can only access topics of interest that they've observed. A caller observes a topic when they make a Topics API request from a context associated with this topic. To illustrate this concept, consider the following simplified example.

• Suppose there are two Topics API callers: A and B.
• There are two contexts:
  • Greenhouse, for example an app named Greenhouse or a website greenhouse.example, associated with the topic Home & Garden.
  • Tennis exercises, for example an app named Tennis Exercises or a website tennis.example, associated with the topic Sports/Tennis.
• Both caller A and B are present in the context of Greenhouse.
• Only the caller B is present in the context of Tennis exercises.
• Assume that no topics were observed for the user before epoch 1, for the sake of simplification.
• The user visits the Greenhouse app, and callers A and B make a Topics API call to record the user visit to the page or app (see the implementation guide suggested in Next steps to find out how to call the Topics API). This record (a hostname or app data) is later used to derive topics of interest. The Topics API will later mark the topic Home & Garden as observed by both callers A and B.
• The user visits the Tennis exercises app. Only the caller B sends a Topics API request. The Topics API will later mark the topic Sports/Tennis as observed by the caller B.
• By the end of the epoch, the Topics API refreshes the user's top topics and determines the callers that observed these topics based on user activity.
• Later, when the caller B makes another Topics API call, it can get either Home & Garden or Sports/Tennis topic (or, with a 5% chance, a random topic) for this user in the response array.
• Caller A can only access the topic Home & Garden, as it has never observed the topic Sports/Tennis. This means that a third-party will only learn about a user's topic of interest within the specific context (app or website) where it is present.

Derive topics

Topics derives topics of interest from user activity. The topics are selected from a predefined open-source taxonomy. Once per epoch, Topics refreshes the user's top five topics and the callers that observed them during the epoch. The Topics classifier model derives topics from user activity: hostname for a web page visit, app information on Android.

Caller accesses user's topics of interest

The API returns only topics that have been observed by the caller within the most recent three epochs. A maximum of three topics may be returned to a caller,one topic for each of the three recent epochs (if the caller observed topics for that epoch). The returned topics can be used by the caller to supplement any contextual information and can be combined to help find a more relevant ad for the user.

Epochs

The Topics API must ensure that the topics of interest it provides are kept up to date. The topics are inferred for a user based on their activity during a period of time known as an epoch, one week by default. Each user has their own epochs (epochs are "per user") and the initial start time is randomized.

Once each epoch, the Topics API computes the user's top five topics and determines which callers observed those topics using on-device information. The topic selected for each epoch is randomly selected from the user's top five topics for that time period. To further enhance privacy and ensure that all topics may be represented, there is a 5% chance the topic is randomly selected from all possible topics in the taxonomy of interests.

Tópicos no Android na prática

A API Topics no Android foi projetada para oferecer suporte a SDKs de publicidade de terceiros que geralmente operam em vários apps. A API Topics fornece aos autores de chamada temas de publicidade de interesse gerais com base no uso do app do usuário, sem depender de identificadores entre apps. Esses temas podem ser usados para complementar qualquer informação contextual relacionada ao app que quer mostrar um anúncio e podem ser combinados para ajudar a selecionar um anúncio adequado ao usuário.

No contexto da API Topics, os compradores e os anunciantes dependem do lado do vendedor. É o lado do vendedor que tem uma ampla presença nos apps do editor, observa os temas dos usuários e compartilha os temas com os compradores para ajudar a selecionar anúncios mais relevantes. Para receber temas, os apps e SDKs do lado do vendedor precisam estabelecer uma presença como observadores da API Topics por pelo menos uma época.

Consulte o guia de implementação da API Topics para conferir exemplos de código que demonstram como configurar a capacidade de buscar temas para publicidade com base em interesses.

Integração de tópicos por tipo de empresa

Ative a publicidade com base em interesses (IBA) com a API Topics. Siga as etapas com base no tipo de empresa de adtech para integrar a API Topics e se preparar para o lançamento.

Para todas as adtechs

• Analise a taxonomia de temas e dê feedback.
• Teste os apps de exemplo da API Topics para saber quais dados de temas são retornados do classificador no dispositivo.
• Atualize os fluxos do app e do SDK para começar a chamar a API Topics.
• Atualize os protocolos para começar a enviar temas em solicitações de anúncios.
• Registre sua adtech com o Sandbox de privacidade.

Para adtechs de venda

• Torne-se um observador para estabelecer uma presença na API Topics. A API Topics oferece um novo indicador. Atualize o SDK para começar a chamar a API Topics. Para extrair temas de forma consistente, o SDK precisa chamar a API dos apps do editor pelo menos uma vez por época. A entrega do número máximo de temas (três) com suas solicitações de anúncios pode levar até quatro épocas.
• Incluir informações da API Topics nas solicitações de anúncio. Para cada solicitação de anúncio, comece a compartilhar os dados da API Topics com parceiros de compra. A API Topics planeja complementar outros indicadores (como indicadores de contexto) para ajudar a encontrar um anúncio adequado para um determinado visitante.
• Colabore em um protocolo para compartilhar temas com seus parceiros de compra. A API Topics precisa que cada SDK funcione com parceiros downstream para chegar a um acordo sobre como os dados da API Topics são compartilhados.

Para adtechs de compra

• Conecte-se com parceiros do lado do vendedor para confirmar os planos deles de observar temas e estabelecer presença. Para receber temas, os provedores do lado do vendedor precisam chamar a API Topics pelo menos uma vez por época.
• Colabore em um protocolo para receber temas de parceiros do lado do vendedor. Os temas são um novo indicador que será compartilhado pelos parceiros do lado do vendedor como parte da solicitação de anúncio. Os consumidores de compras precisam garantir que trabalham com parceiros upstream para saber como os temas serão compartilhados.
• Incorporar temas em modelos de lances e otimização A API Topics precisa complementar outros indicadores, como contextuais, para encontrar um anúncio adequado para o visitante.

Como a API infere temas para um app

No Android, a API Topics infere temas para um app com base nas informações dele, usando um modelo de classificador. Na implementação atual, o Topics usa nomes de apps e pacotes para atribuir temas de interesse a um app, mas isso pode ser estendido para incluir outras informações, como a descrição do app.

Classificador de temas

Os temas de interesse são derivados de um modelo de classificador treinado com informações de apps disponíveis publicamente.

• 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.
• O modelo V5 foi treinado pelo Google com 540.000 rótulos definidos por humanos e 17 milhões de rótulos definidos por ML em informações de apps disponíveis publicamente em app stores,como a Google Play Store. O modelo usa nomes de apps e pacotes como indicadores de entrada e está disponível sem custo financeiro para que os desenvolvedores de apps testem e descubram em quais temas o app se encaixa.
• É 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.

Para entender melhor como o modelo de classificador funciona, teste como diferentes dados do app afetam a classificação usando o Colabificador de temas do Android.

Taxonomia

Os temas são selecionados em uma taxonomia de código aberto predefinida. A taxonomia está disponível publicamente e está sujeita a mudanças. As sugestões podem ser enviadas usando o botão de feedback na parte de cima desta página. Essa taxonomia é selecionada por análise humana para que temas sensíveis não façam parte dela. Ela será personalizada para as categorias de anúncios que podem ser exibidas em apps para dispositivos móveis no Android.

Tópicos no Android na prática

Suponha que um usuário tenha sete apps instalados no dispositivo: A, B, C, D, E, F e G. Vamos supor que a classificação de temas do app e dos SDKs de adtechs nesses apps seja esta:

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 primeira semana: 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 SDKs de anúncios são usados. Isso significa que, se um app não inclui SDKs de anúncios que chamam a API Topics, os temas associados a ele não contribuem para o conjunto de temas acessíveis pelos SDKs de anúncios.
• Um app também pode desativar a API Topics de maneira declarativa. Os temas associados a apps desativados não contribuem para o cálculo semanal de temas. 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.

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 temas retornados sejam legíveis apenas para o autor da chamada.

O Sandbox de privacidade vai buscar essas chaves no endpoint fornecido pela adtech . Como prática recomendada, sugerimos que as chaves sejam atualizadas regularmente, mas não a cada seis meses.

O Sandbox de privacidade vai pedir que as adtechs confirmem a disponibilidade do endpoint fornecido durante o processo de registro. Para mais detalhes sobre as ações exigidas pelas adtechs atuais e recém-registradas, consulte o guia de registro.

Next steps

Consulte também

Confira nossos recursos para entender melhor a API Topics no Android.

• Confira apps de exemplo, vídeos de collab e tutoriais da API Topics.
• Veja como usuários e desenvolvedores podem controlar a API.
• Confira os recursos de suporte para fazer perguntas, interagir e compartilhar feedback.