Skip to main content
Para ter sucesso na Ads API, é importante entender como as entidades no X Ads se relacionam entre si. Este tutorial aborda os fundamentos da hierarquia de objetos do X Ads. Hierarquia da X Ads API

​
Ad Group (line items)

Ad groups, conhecidos como line items na Ads API, existem sob as campanhas e são usados para segmentação e lances contra um conjunto de usuários do X. Anunciantes promovem posts ou mídia (por exemplo, vídeos promovidos como In-stream ads) associando-os a um line item. Veja também Ad Group.

​
Account Media

Uma coleção de criativos que foram enviados para uma conta Ads como account media que pode incluir assets pre-roll de vídeo promovido, também chamados de in-stream ads, e imagens que podem ser promovidas na X Audience Platform.

​
Ads Accounts

No topo da hierarquia do X Ads estão as contas ads. Uma conta ads pode ser gerenciada por vários usuários do X. @Furni, nossa loja de móveis de demonstração, seria um exemplo de um usuário que gerencia uma conta ads. Identificamos as contas ads por um account_id, que é uma string alfanumérica em base36. Sob cada conta, armazenamos vários tipos de entidades que podem ser reutilizadas em campanhas, como tailored audiences que podem ser usadas para segmentação, account media, que são vídeos ou imagens, e cards, que são criativos expandidos que você pode adicionar a um post.

​
Amplify Video

Ao fazer upload de um asset de vídeo, a entidade que faz o upload pode definir uma categoria para o vídeo (por exemplo, Tweet Video, Tweet Gif, Tweet Image e Amplify Video). A categoria amplify video é obrigatória ao tentar fazer upload de um vídeo que será exibido como propaganda in-stream. Esses vídeos exigem processamento especial para garantir que sejam veiculáveis e, portanto, a media category de Amplify Video é obrigatória.

​
Analytics

As métricas de analytics ajudam parceiros e anunciantes a entender o desempenho do conteúdo que promovem no X. Isso inclui informações como impressões, cliques, visualizações de vídeo e gasto. Além disso, parceiros e anunciantes podem obter métricas detalhadas para vários segmentos das audiências que alcançam. A Ads API suporta duas formas de recuperar métricas detalhadas de desempenho de campanha: síncrona e assíncrona. Com as requisições de analytics síncronas, as métricas solicitadas são retornadas na resposta. O endpoint síncrono suporta intervalos de tempo curtos e é ideal para consultar o desempenho de campanha em tempo real. Com os endpoints de analytics assíncronos, as métricas solicitadas ficam disponíveis em um arquivo de resultados baixável depois que o “job” associado terminou de processar. Os endpoints assíncronos suportam solicitar métricas em um intervalo de tempo muito maior, permitem retornar dados segmentados e destinam-se a buscar muito mais dados — ideal para geração de relatórios ou preenchimentos históricos.

​
Campanhas

Cada campanha que o anunciante executa deve ser criada sob um funding instrument existente. Uma campanha permite definir coisas como o nome, cronograma e orçamento de uma campanha publicitária. Continuando com o exemplo da Furni, poderíamos criar uma campanha chamada “Furni home decor”. Vale notar que uma conta ads é limitada a no máximo 200 campanhas ativas; esse limite pode ser elevado pelo account manager do anunciante. Uma Campanha é considerada ativa até que seu horário de término seja alcançado ou seu orçamento se esgote. Uma campanha pausada ainda é considerada uma campanha ativa para fins de limites de campanha.

​
Cards

Cards oferecem uma forma de estender visualmente um Tweet para incluir uma imagem, vídeo ou elementos de UI. A Ads API suporta vários tipos de card que podem ser usados em Tweets, os quais podem então ser promovidos em campanhas.

​
Creatives

Anunciantes podem promover Tweets em campanhas que incluem criativos, como imagens, GIFs e vídeo. Esses criativos podem ser associados a X cards que permitem anexar fotos, vídeos e experiências de mídia ricas aos Tweets. Criativos também podem ser anexados diretamente aos Tweets. Por exemplo, você pode incluir texto e um vídeo (ou até 3 imagens) e criar um Tweet promovido. Cada line item precisa ter pelo menos um criativo associado para ser executado. Várias opções de criativos estão disponíveis, incluindo Promoted Accounts para conquistar novos seguidores, Media Creatives como uma imagem ou vídeo para line items na TX Audience Platform, ou Promoted Posts.

​
Funding Instruments

Também sob a conta ads estão os funding instruments, que são as diferentes fontes de financiamento que o anunciante configurou para usar com o X Ads. Estas vão desde insertion orders que assinaram com o X até um cartão de crédito anexado à conta.

​
Line Items

Dentro de uma campanha, você pode ter um ou mais ad groups, também conhecidos como line items na Ads API. Line items podem ser pensados como diferentes segmentos de uma campanha, cada um com seu próprio conjunto de segmentação e seu próprio criativo. Campanhas que contêm múltiplos line items são frequentemente chamadas de “ad group campaigns”. Um dos benefícios de múltiplos line items dentro de uma única campanha é que você pode criar uma variedade maior de combinações de segmentação e criativo. Sob nossa campanha “Furni home decor”, podemos querer criar dois line items: um poderia ser “Home buyers in San Francisco” e o outro poderia ser “Home buyers in London”. Até 100 line items são permitidos por campanha, e uma conta ads é limitada a 4.000 line items ativos no total em todas as campanhas.

​
Mobile App Promotion (MAP)

Mobile App Promotion, ou MAP, é um conjunto de produtos que permitem aos anunciantes promover apps móveis via X. Estes incluem instalações de app, conversões e re-engajamento.

​
Mobile App Conversion Tracking (MACT)

A medição de promoção de app móvel do X permite que os anunciantes acompanhem o sucesso das campanhas publicitárias no X projetadas para gerar instalações ou outras conversões dentro do app. Um parceiro de medição móvel do X oferece a capacidade de um anunciante gerenciar quais conversões deseja acompanhar dos apps que está promovendo no X. MACT Overview

​
Media Library

Os endpoints da Media Library oferecem a capacidade de gerenciar imagens, GIFs e vídeos para contas do X Ads. Assets de mídia na biblioteca podem ser usados em posts e para criar cards. Eles também podem ser reutilizados em múltiplos criativos, eliminando a necessidade de fazer upload do mesmo asset várias vezes. Promoted Accounts (campanhas de seguidores) fazem parte do Who to Follow, que sugere contas que as pessoas não seguem atualmente e podem achar interessantes. Promoted Accounts ajudam a apresentar uma variedade ainda maior de contas que as pessoas podem gostar. Promoted Accounts permitem que os anunciantes promovam sua conta e cresçam sua audiência no X. Campanhas de seguidores são exibidas em vários locais da plataforma X — incluindo Home Timelines, Who to Follow e resultados de busca — e essa sugestão é rotulada como Promoted para distingui-la de outras contas recomendadas.

​
Promotable Users

Cada conta X Ads pode ter um ou mais promotable users, que são usuários que podemos promover através da conta ads. O handle @Furni da Furni seria um exemplo de um FULL promotable user na conta ads da Furni, o que significa que podemos executar todos os tipos de campanhas para @Furni e seus tweets. Só pode haver um FULL promotable user por conta ads. Note que também pode haver outros promotable users sob uma conta ads. Por exemplo, se quiséssemos promover os Tweets de @Jack sobre produtos Furni, ele se tornaria um retweet-only promotable user na conta, o que é indicado por RETWEETS_ONLY. Anunciantes devem entrar em contato com seu account manager do X para informações sobre como adicionar retweet users à sua conta ads. Promoted videos são vídeos dentro de Promoted Tweets pagos por anunciantes. Eles aparecem na Home timeline, no topo dos resultados de busca no X e em outros lugares da plataforma, e são claramente marcados como “Promoted”.

​
Publisher Network

Consulte X Audience Platform.

​
Scheduled Tweets

Scheduled Tweets permitem que um anunciante ou usuário crie um Tweet que pode ser agendado para publicação em uma data posterior. Além de poder criar e gerenciar esses Tweets, a API permite a capacidade de associar esses Tweets a um line item, para serem promovidos assim que o Tweet for publicado. Isso permite que os anunciantes preparem a criação de Tweets nativos e planejem seus criativos de campanha com antecedência de quaisquer iniciativas-chave. Por exemplo, preparando um criativo de Tweet para ir ao ar imediatamente ao lançar um novo produto.

​
Segmentation

A segmentação permite que parceiros e anunciantes recuperem métricas divididas por valores específicos de segmentação — como idade, dispositivos ou idiomas — e está disponível apenas através de nossos endpoints assíncronos de analytics. Para solicitar métricas segmentadas, use o parâmetro de requisição segmentation_type. Para mais detalhes sobre opções de segmentação, consulte Metrics and Segmentation.

​
Tailored Audience - List

Tailored audiences from lists são um dos três tipos de Tailored Audiences, criadas ao enviar um arquivo contendo seus próprios dados de usuário e cliente. Suas listas são combinadas com usuários no X para que você possa direcioná-los diretamente em suas campanhas. Revise estas restrições.

​
Tailored Audience - Web

Tailored Audience from web, um dos três tipos de Tailored Audiences, é uma coleção de usuários do X que visitaram seu site. Para usar Tailored Audiences from web, você deve ter nosso pixel do X instalado em seu site, ou usar um dos nossos parceiros de tag manager aceitos. Revise estas restrições.

​
Targeting Criteria

Como mencionamos anteriormente, os targeting criteria são associados a um line item. Temos uma variedade de segmentações diferentes que você pode usar, desde localização, keywords e gênero até atributos mais granulares, como comportamentos e interesses do usuário. Para o line item “Home Buyers in San Francisco”, podemos segmentar o comportamento “home buying” junto com a localização “San Francisco”. Para informações sobre os diferentes tipos de segmentação disponíveis, visite a página Targeting Overview em nosso developer site.

​
Twitter Object Nest (TON)

O Twitter Object Nest (TON) armazena mídia e vários assets enviados via os endpoints de Media Upload para serem usados como Criativos.

​
Creatives

Cada line item precisa ter pelo menos um criativo associado para ser executado. Várias opções de criativos estão disponíveis, incluindo Promoted Accounts para conquistar novos seguidores, Media Creatives como uma imagem ou vídeo para line items na X Audience Platform, ou Promoted Posts. Aqui está um exemplo de post que @Furni poderia promover e usar como criativo.