Pular para o conteúdo principal

​
Configuração da Conversion API

​
Pré-requisitos 

​
Acesso à Ads API - Novas solicitações

Etapa 1: Conta de desenvolvedor
  • Ao solicitar uma conta de desenvolvedor, assine um de nossos planos para aprovação instantânea.
  • Observação: Como prática recomendada, recomendamos fortemente usar o handle oficial da sua empresa no X para criar a conta de desenvolvedor e solicitar acesso à Ads API. Se a conta de desenvolvedor estiver associada a um handle de desenvolvedor, não há como transferir essas credenciais, caso necessário. É preferível mantê-la sob uma conta da empresa para gestão contínua e utilizar o login multiusuário, conforme necessário. Caso contrário, no mínimo, a conta deve ser configurada com definições não padrão (imagem de cabeçalho, avatar, descrição da bio e URL da bio) e usar autenticação de dois fatores.
Etapa 2: Solicitação à Ads API
  • Certifique-se de ter o App ID correto em mãos para sua solicitação à Ads API. O App ID pode ser encontrado no portal do desenvolvedor, em Projects & Apps. Exemplo: 16489123
  • Solicite acesso à Ads API entrando em contato com seu representante da X.

​
Acesso à X Ads API - Aplicativos existentes

  • Se você já tem um App da X Ads API em uso ativo, tanto o App quanto os access tokens existentes podem ser utilizados na Conversion API.

​
Access Tokens

  • Os User Access Tokens para o handle do usuário proprietário da aplicação X Ads API podem ser gerados e obtidos diretamente no portal do desenvolvedor. Isso é chamado de “personal access token” porque se destina ao uso com o seu próprio handle no X. Informações gerais sobre autenticação e o portal do desenvolvedor podem ser encontradas aqui.
  • Os User Access Tokens para handles de usuário diferentes do handle proprietário da aplicação X Ads API devem ser gerados com um fluxo OAuth de 3 etapas. As opções para gerar o Access Token com OAuth de 3 etapas incluem:
  • Quaisquer tokens de usuário usados com a Conversion API devem ser de usuários com nível de acesso AD_MANAGER ou ACCOUNT_ADMIN, o que pode ser verificado por meio do endpoint authenticated_user_access.
  • Observação: os próprios tokens (após a criação conforme acima) podem ser compartilhados com usuários sem o nível de acesso AD_MANAGER ou ACCOUNT_ADMIN para uso.

​
Passos

​
Criando o evento da Conversion API

Para usar a Conversion API, você precisa criar um novo evento de conversão no Ads Manager ou usar um evento existente que já esteja criado e sendo utilizado com o X Pixel. Se você pretende fazer a deduplicação entre eventos do Pixel e da Conversion API, é necessário usar o evento existente que você criou para o Pixel. 
Opção 1: Usando um Evento de Conversão Existente no Ads Manager
Se você quiser usar um evento já em uso com o pixel da X, isso é possível — basta obter o Event ID desse evento. Se você utilizar tanto o Pixel quanto a Conversion API para o mesmo evento, certifique-se de usar a chave de desduplicação tanto no trecho de código do Pixel quanto na solicitação da Conversion API (como conversion_id) para desduplicar eventos entre o Pixel e a Conversion API para esse mesmo evento. Consulte a seção d. Teste de eventos e desduplicação para mais informações. 
Opção 2: Criar um novo evento de conversão no Ads Manager:
É importante ter uma Fonte de Evento criada no Events Manager antes de criar um evento. Para verificar se você tem uma Fonte de Evento (X Pixel) adicionada à sua conta, acesse o Events Manager e veja se o X Pixel aparece no menu à esquerda. Se você ainda não tiver uma Fonte de Evento adicionada, siga as etapas abaixo para criar uma:
  1. Acesse ads.x.com
  2. Navegue até a seção Tools no canto superior esquerdo e clique em Events Manager
  3. Selecione Add event source no canto superior direito para Add an event source se você ainda não tiver uma fonte de evento X Pixel adicionada na barra lateral esquerda
    1. O id da fonte de evento do X Pixel é o seu Pixel ID
Agora você tem uma Fonte de Evento e um Pixel ID. Você precisa criar um evento dentro da Fonte de Evento para os eventos de conversão que deseja acompanhar:
  1. Dentro da fonte de evento do X Pixel, selecione Add events no lado direito
  2. Selecione Install with Conversion API
  3. Você verá o Pixel ID e o Event ID deste evento que serão usados na API
    1. O id do evento é o seu Event ID
  4. Clique em Save e seu evento de conversão estará criado e pronto para uso

​
Preparando identificadores para eventos de conversão 

Atualmente, é necessário enviar pelo menos um identificador, como Click ID (twclid), endereço de e-mail ou número de telefone. Se usar endereço IP ou user agent, um segundo identificador deve ser enviado para permitir a correspondência correta da conversão. Fornecer mais identificadores resultará em uma taxa mais alta de correspondência de conversão.
Campo de correspondência do clienteFormatoHashing obrigatório?
X Click IDGerado por X (saiba mais)Não
Endereço de e-mailRemover espaços iniciais e finaisObrigatório (SHA256)
Número de telefonePadrão E.164Obrigatório (SHA256)
Endereço IPRemover espaços iniciais e finaisNão
User agentRemover espaços iniciais e finaisNão

​
1. Preparar o identificador X Click ID 

Recomenda-se sempre incluir o Click ID na solicitação de conversão. O Click ID deve ser extraído do parâmetro twclid da query string quando estiver disponível após o usuário navegar para o site de destino.  Exemplo básico de código JavaScript: 
var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // Próximos passos recomendados: Log, inserir no armazenamento local
}
Recomenda-se: 
  1. Sempre extrair o valor de twclid quando ele estiver presente nos parâmetros de query da URL.
  2. Armazenar os data junto com os campos de formulário relevantes ou as informações do evento de conversão.
Vincular o Click ID a eventos de conversão e informações de fluxo de trabalho possibilita cenários como processamento em lote, uso de algoritmos para analisar e criar eventos de conversão com base em múltiplos fluxos de navegação no site e carregamentos em massa. A Event Source URL deve estar URL encoded e destina-se a representar a página da web que acionou o evento.

​
2. Preparar identificador de email 

Os fields compatíveis para correspondência de clientes podem ser enviados, mas devem ser normalizados e, quando necessário, aplicados a hash para proteger a privacidade. As informações devem ser submetidas a hash usando SHA256, sem sal.  Por exemplo, para o endereço de email test@x.com, ele deve ser enviado para nós em formato com hash: d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62.

​
3. Preparar identificador de telefone 

O número de telefone deve ser fornecido no padrão E.164 e os dados devem ser hashed com SHA‑256, sem sal.  Por exemplo, para um número de telefone dos EUA: +11234567890, ele deve ser enviado para nós no formato hashed: 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231.

​
4. Preparar o identificador de endereço IP

É necessário enviar o endereço IP em conjunto com outro identificador (twclid, endereço de e-mail, número de telefone ou user agent). Não é necessário aplicar hash a esse identificador. Esse valor é escrito em notação decimal pontuada, com quatro números separados por pontos. Por exemplo, o endereço IP de um usuário pode ser 8.25.197.25.

​
5. Preparar o identificador de User Agent

O User Agent deve ser enviado em conjunto com outro identificador (twclid, endereço de e-mail, número de telefone ou endereço IP). Não é necessário aplicar hash a esse identificador. Esse identificador permite que o servidor identifique o aplicativo, o sistema operacional, o fornecedor e/ou a versão do user agent que fez a solicitação. Por exemplo, esse valor pode ser enviado como Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.

​
Construindo a solicitação de evento de conversão

POST: version/measurement/conversions/:pixel_id Envie eventos de conversão para uma conta de anúncios específica. Verifique o código de resposta para confirmar o sucesso (HTTP 200 OK). Recomenda-se implementar um mecanismo de repetição (retry) e um registro básico (logging) caso códigos de erro sejam retornados. Para obter informações detalhadas sobre a URL do endpoint e os parâmetros do corpo da requisição POST, consulte a seção API Reference. 

​
Exemplo de solicitação (formatada para facilitar a leitura)


    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"Compras de produtos para animais de estimação",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Mantas",
                  "content_type":"Produtos para animais de estimação"
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'

​
Exemplo de resposta

{"request": {
 "params": {
     "account_id":"18ce552mlaq"}
 },
 "data": {
     "conversions_processed":1,
     "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"}
}

​
Limite de taxa

O limite de taxa será de 60.000 eventos por conta, por intervalo de 15 minutos. Observe que o código do seu servidor pode precisar implementar lógica fora desta chamada, incluindo:
  1. Instrumentação das ações dos usuários (logs) para enviar os dados de conversão corretos por evento
  2. Qualquer lógica necessária para filtrar eventos de conversão de usuários que exerceram escolhas relevantes de privacidade — por exemplo, se optaram por não ser rastreados ou pela não venda de suas informações pessoais no site do anunciante
  3. Integração com gatilhos de eventos e páginas para capturar eventos e enviar conversões

​
Teste de eventos e deduplicação

​
Testando eventos

Quando seu evento tiver começado a receber conversões com sucesso, em 12 a 24 horas o status de ‘Single event web tag’ deverá exibir TRACKING na página Conversion Tracking do Ads Manager. Isso não afetará campanhas em andamento ao enviar conversões por meio da Conversion API. Você também pode verificar os resultados de análise do seu evento de conversão por id de tag por:

​
Duplicação entre Pixel e Conversion API

Se você pretende desduplicar conversões entre solicitações do Pixel e da Conversion API, use conversion_id como chave de desduplicação. A desduplicação ocorre apenas no nível do evento. Em outras palavras, para desduplicar entre solicitações do Pixel e do CAPI, o anunciante deve usar o mesmo evento em ambas as solicitações (Pixel e CAPI), além de usar o mesmo conversion_id. A desduplicação só pode ocorrer para eventos recebidos dentro de uma janela de 48 horas.

​
Rastreamento de conversões (visão geral)

​
Resumo

O rastreamento de conversões permite medir quantos usuários do X executam uma ação desejada após ver e interagir com seus anúncios no X. Ele possibilita identificar quais das suas campanhas impulsionam ações como visitas ao site, inscrições e compras. Isso fornece aos anunciantes recursos de mensuração fora do X para entender o desempenho de seus anúncios de resposta direta, permitindo a aquisição de clientes de forma economicamente eficiente. Com uma tag de conversão, os anunciantes podem rastrear conversões de usuários e vinculá-las às campanhas de anúncios no X. Isso oferece visibilidade para otimizar suas campanhas a fim de atingir suas metas de custo por aquisição (CPA). Há uma variedade de ações em sites que um anunciante pode mensurar com o rastreamento de conversões. É possível selecionar uma ou mais, de acordo com as ações que se deseja impulsionar com a campanha de anúncios:
  • Visita ao site: o usuário acessa uma landing page no site do anunciante
  • Compra: o usuário conclui a compra de um produto ou serviço no site do anunciante
  • Download: o usuário faz o download de um arquivo, como um white paper ou pacote de software, no site do anunciante
  • Inscrição: o usuário se inscreve no serviço, newsletter ou comunicação por e-mail do anunciante
  • Personalizado: categoria abrangente para uma ação personalizada que não se enquadra em nenhuma das categorias acima
O rastreamento de conversões do X oferece aos anunciantes uma visão completa da atribuição de conversões. Em comparação com sistemas de mensuração de terceiros que os clientes possam ter usado em vez do recurso próprio de rastreamento de conversões do X, como URLs de clique únicos combinadas com tags de rastreamento de terceiros, a tag de conversão do X permite ao anunciante rastrear conversões atribuídas a interações de meio e topo de funil, como expansões de Tweet, Retweets, favoritos, respostas e follows, além de impressões.

​
Perguntas frequentes

Primeiro, o anunciante cria uma tag de conversão — um trecho de código fornecido pela X — e a insere em seu site. A tag fica pronta para medir a conversão quando um usuário conclui a ação definida.Em seguida, os usuários veem o anúncio do anunciante no cliente da X, que os direciona ao site do anunciante e à ação marcada. Se o usuário concluir essa ação dentro da(s) janela(s) de atribuição especificada(s) pelos anunciantes durante a configuração da tag, a tag reconhece que o usuário já interagiu com um anúncio da X. A tag então “dispara”, ou seja, envia uma notificação aos servidores da X para que a conversão seja atribuída ao anúncio que a gerou.
Não. Nosso produto não permite vincular tags de conversão específicas a campanhas específicas. Em vez disso, depois que uma tag é configurada, o sistema acompanha automaticamente qual anúncio gerou conversões em determinada tag.
Janela padrão de atribuição pós-visualização: 1 diaAtribuição padrão pós-engajamento: 14 diasEsses padrões podem ser alterados durante a configuração da tag de conversão ou a qualquer momento após a criação da tag. As opções de janelas de atribuição pós-engajamento são 1, 7, 14, 30, 60 e 90 dias. As opções de janelas de atribuição pós-visualização são nenhuma, 1, 7, 14, 30, 60 e 90 dias.
Embora os objetivos, contextos e estratégias de cada cliente sejam diferentes, seguem algumas ideias que funcionaram para clientes que participaram dos programas alfa ou beta de acompanhamento de conversões:Criativo:
  • Ofertas: Combine um desconto, promoção ou frete grátis com o Promoted Tweet para gerar mais interesse na ação
  • Sorteios e concursos: Especialmente para marcas conhecidas, sorteios e concursos impulsionaram conversões
  • Experimentação de texto do Tweet: Teste caixa alta vs. minúsculas (FREE vs free ou NOW vs now)
  • Prazos: Ofereça um prazo para incentivar as pessoas a agir imediatamente (Oferta expira em 12 de dezembro!)
  • Adicionar fotos atraentes: Vale a pena testar se fotos visualmente atraentes no criativo do Tweet são eficazes para impulsionar conversões; os resultados podem variar ou depender da oferta do cliente.
Segmentação:
  • Segmentação por @handle e por categoria de interesse: O alinhamento estreito entre o texto do Tweet e @handles com o público-alvo do Tweet impulsionou conversões
  • Uso de palavras-chave de nicho, mas com alto volume: No segmento de shows, usar palavras-chave relacionadas ao artista/músico (por exemplo, o nome) mostrou-se eficaz
  • Audiências personalizadas: Clientes usando TA web e acompanhamento de conversões em conjunto alcançaram CPAs menores do que grupos de controle usando outras segmentações
Quanto mais granular for a segmentação da sua campanha, mais acionáveis serão os resultados de conversão relatados. Por exemplo, é muito mais fácil otimizar uma campanha com 4 palavras-chave do que otimizar uma campanha com 50.

​
Solução de problemas e suporte para a Conversion API

Para dúvidas sobre códigos de erro após a chamada à API, consulte a seção abaixo. Para quaisquer outras questões, não hesite em entrar em contato com seu representante da X; trabalharemos para resolvê-las o mais rápido possível. 

​
Tratamento e explicação de erros

Uma solicitação só será bem-sucedida se não houver erros em nenhuma das conversões contidas nela. Caso ocorra algum erro em uma conversão individual, o endpoint retornará uma lista de todos os erros aplicáveis.

​
Visão geral dos códigos de erro da X Ads API

Aqui está uma lista abrangente dos códigos de erro na X Ads API: https://developer.x.com/en/docs/twitter-ads-api/response-codes Respostas bem-sucedidas da Conversion API são indicadas por um código HTTP da série 200 e um payload em JSON contendo o objeto solicitado.

​
Quando houver um código HTTP da série 500, isso indica um problema no servidor, e não na sua solicitação ou na configuração da sua conta. Verifique a página de status da X API ou o fórum da comunidade de desenvolvedores para ver se outras pessoas estão enfrentando problemas semelhantes.

​
Quando houver um código HTTP da série 400, os casos comuns são

  • 400 Bad Request (a solicitação não está em conformidade com os padrões)
  • 401 Unauthorized (problemas de autenticação)
  • 403 Forbidden (problemas de acesso à API associados àquela conta de desenvolvedor)
  • 404 Not Found (a URL ou os parâmetros podem não estar corretos para o endpoint)

​
Códigos de erro da API de Conversão

​
400 Cenários de Solicitação Inválida

MotivoTipoMensagem de erro
Erro de identificador ausente (atualmente e-mail com hash ou X click ID - twclid)400 Solicitação InválidaPelo menos um identificador de usuário deve ser fornecido
E-mail com hash inválido400 Solicitação InválidaHashed_email não é um hash SHA-256 válido
O type de event_id não é uma tag de evento único (SET)400 Solicitação InválidaEvent_id (<event_id>) não é uma tag de evento único (SET)
Os eventos de conversão solicitados excedem o limite (atualmente 500 eventos por solicitação)400 Solicitação InválidaO limite de contagem de conversões é 500
Event ID ausente400 Solicitação InválidaEvent ID não foi encontrado

​
Exemplo de código de erro em JSON

Solicitação:
POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dkt", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json

​
Mensagem de erro:

{"errors":[{"code":"INVALID_PARAMETER","message":"event_id (o6dkt) não é uma única tag de evento (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
Requisição:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"twclid": ""}]}]}' --header 'Content-Type: application/json'

​
Mensagem de erro:

{"errors":[{"code":"INVALID_PARAMETER","message":"É necessário fornecer pelo menos um identificador de usuário","parameter":""}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
Solicitação:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"hashed_email": "abc"}]}]}' --header 'Content-Type: application/json'

​
Mensagem de erro:

{"errors":[{"code":"INVALID_PARAMETER","message":"hashed_email (abc) is not a valid SHA-256 hash","parameter":"hashed_email"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
Solicitação:

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603", "event_id":"o6dl3", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

​
Mensagem de erro:

{"errors":[{"code":"INVALID_PARAMETER","message":"Era esperado um horário no formato yyyy-MM-ddTHH:mm:ss.SSSZ, mas foi recebido \"2022-06-16T01:14:00.603\" para conversion_time","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
401 Não autorizado

Motivo: Credenciais de autenticação ausentes ou incorretas Solução: Siga as etapas de autenticação na documentação de configuração usando um dos 3 métodos de autenticação: Access Tokens de usuário para handles de usuários diferentes do handle que é proprietário da App da X Ads API devem ser gerados com um fluxo OAuth de 3 etapas. As opções para gerar o Access Token com OAuth de 3 etapas incluem: Quaisquer tokens de usuário usados com a Conversion API devem pertencer a usuários com nível de acesso AD_MANAGER ou ACCOUNT_ADMIN*, o que pode ser verificado por meio do endpoint authenticated_user_access.

​
403 Acesso proibido 

MotivoTipoMensagem de erro
A conta de desenvolvedor que você está usando não tem acesso à X Ads API. Solicite acesso aqui.403 Cliente não autorizadoO aplicativo cliente com id <> que está fazendo esta solicitação não tem acesso à X Ads API. Verifique se o seu aplicativo tem acesso a advertiser-api. Use ‘twurl accounts’ e ‘twurl set default <username> <key>’ para alterar o aplicativo que você está usando.

​
404 Não encontrado 

MotivoTipoMensagem de erro
A URL da solicitação ou os parâmetros não estão corretos para o endpoint404 Route Not FoundO recurso solicitado não foi encontrado
Você não tem acesso à conta proprietária do pixel_id/Universal website tag404 Not FoundUser <user_id> does not have access to account <account_id>. Type ‘sn <user_id>’ to get the handle of the user. Use ‘twurl accounts’ and ‘twurl set default \u003Cusername\u003E’ to change the user you’re using.
O id do evento não pertence à conta fornecida associada ao pixel ID (UWT ID)404 Not Foundevent_id <event_id> does not belong to provided account

​
Exemplo de código de erro JSON

​
Solicitação:

twurl_ads -X POST '/11/measurement/conversions/o8z6j' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"abc", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json' Mensagem de erro: {"errors":[{"code":"NOT_FOUND","message":"event_id (abc) does not belong to provided account","parameter":"event_id"},{"code":"INVALID_PARAMETER","message":"event_id (abc) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce55gze09"}}}

​
Índice de referência da API

Para acessar a referência completa da API, selecione um endpoint na lista:

​
Conversões na Web

API de Conversõesmeasurement/conversions/:pixel_id
Tag de Evento da Webaccounts/:account_id/web_event_tags

​
Conversões na Web

POST version/measurement/conversions/:pixel_id Envie eventos de conversão do site para um único Event Tag ID. O código de resposta deve ser verificado para confirmar o sucesso (HTTP 200 OK). Recomenda-se implementar um mecanismo de repetição e um registro básico caso códigos de erro sejam retornados. O limite de taxa será de 100.000 solicitações por intervalo de 15 minutos por conta (cada solicitação permite 500 eventos).
URL do recurso
https://ads-api.x.com/12/measurement/conversions/:pixel_id
Parâmetros de URL da solicitação
NomeDescrição
pixel_id
obrigatório		O Base Tag ID de uma conta de anúncios. Representa o valor codificado em base36 do Base Tag ID dessa conta.

Tipo: string

Exemplo: o8z6j
conversions
obrigatório		Objeto no corpo da solicitação POST da API. Lista de eventos de conversão. É possível fornecer até 500 eventos de conversão. Consulte a tabela abaixo para os fields compatíveis.

Tipo: array

Exemplo: "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]
objeto conversions
NameDescription
conversion_time
required		O horário, expresso em ISO 8601.

Type: string

Example: 2017-10-05T00:00:00Z
event_id
required		O ID em base 36 de um evento específico. Ele corresponde a um evento pré-configurado nesta conta de anúncios. Isso é chamado de ID no evento correspondente no Events Manager.

Type: string

Example: o87ne ou tw-o8z6j-o87ne (tw-pixel_id-event-id), ambos aceitos
identifiers
required		Uma lista de objetos de identificador para fazer a correspondência com o evento de conversão. Os fields compatíveis estão listados em uma tabela abaixo. Pelo menos um dos objetos de identificador é obrigatório.

Se estiver usando endereço IP ou user agent, um segundo identificador deve ser enviado para a correspondência adequada da conversão.

Type: array

Example: "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items
optional		O número de itens comprados no evento. Deve ser um número positivo maior que zero.

Type: integer

Example: 4
price_currency
optional		A moeda dos itens comprados no evento, expressa em ISO-4217. Consulte Currency para informações detalhadas.

Type: string

Default: USD

Example: JPY
value
optional		O valor dos itens comprados no evento, representado na moeda de price_currency.

Type: double

Example: 100.00
conversion_id
optional		Para desduplicação entre conversões do pixel e da Conversion API. Um identificador para um evento de conversão que pode ser usado para desduplicação entre conversões do Web Pixel e da Conversion API na mesma tag de evento. Consulte a seção Testing Events and Deduplication do Conversions Guide para mais informações.

Type: string

Example: 23294827
description
optional		Descrição com informações adicionais sobre as conversões.

Type: string

Example: test conversion
contents
optional		Lista de detalhes referentes a um produto/conteúdo específico para fornecer informações granulares. Veja a tabela abaixo para os fields compatíveis.

Type: array

Example: contents": [{"content_id": "1", "content_name": "Blankets", "content_type": "home improvement", "content_price": 100.99, "num_items": 1, "content_group_id": "123"}, {"content_id": "2"}]
objeto identifiers
NameDescription
twclid
às vezes obrigatório		ID de clique conforme extraído da URL de redirecionamento. É obrigatório se nenhum outro identificador for fornecido.

Type: string

Example: 26l6412g5p4iyj65a2oic2ayg2
hashed_email
às vezes obrigatório		Um endereço de e-mail com hash usando SHA256. O texto deve estar em minúsculas; remova quaisquer espaços à esquerda ou à direita antes de aplicar o hash. É obrigatório se nenhum outro identificador for fornecido.

Type: string

Example: Para test-email@test.com = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8
hashed_phone_number
às vezes obrigatório		Um número de telefone no formato E164 e com hash usando SHA256. O número de telefone deve estar no formato E164 antes de aplicar o hash. É obrigatório se nenhum outro identificador for fornecido.

Type: string

Example: Para +11234567890 = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231 
ip_address
às vezes obrigatório		Esse valor é escrito em notação decimal pontuada, com quatro números separados por pontos.

O endereço IP deve ser enviado em conjunto com outro identificador (twclid, endereço de e-mail, número de telefone ou user agent).

Type: string

Example: 8.25.197.25
**user_agent **
às vezes obrigatório		Esse identificador permite ao servidor identificar o aplicativo, sistema operacional, fornecedor e/ou versão do user agent solicitante.

O user agent deve ser enviado em conjunto com outro identificador (twclid, endereço de e-mail, número de telefone ou endereço IP).

Type: string

Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.
objeto contents
NameDescription
content_id
opcional		SKU ou GTIN; identificador que representa o conteúdo.

Tipo: string

Exemplo: jhp
content_group_id
opcional		ID associado a um grupo de variantes de produto

Tipo: integer

Exemplo: group 1
content_name
opcional		Nome do produto ou serviço.

Tipo: string

Exemplo: radio flyer
content_price
opcional		Preço do produto ou serviço.

Tipo: double

Exemplo: 5.00
content_type
opcional		Categoria do produto adquirido.

Tipo: string

Exemplo: clothes
num_items
opcional		Número de produtos adquiridos

Tipo: integer

Exemplo: 1
Parâmetros de resposta
NomeDescrição
conversions_processedNúmero de conversões processadas com sucesso

Tipo: inteiro

Exemplo: 1
debug_idUm UUID de depuração que pode ser usado em investigações subsequentes

Tipo: string

Exemplo: ff02e052-36e4-47d6-bdf0-6d8986446562
Exemplo de requisição
    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"Compras de artigos para pets",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Cobertores",
                  "content_type":"Artigos para pets",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'
Exemplo de solicitação
    {
       "request":{
          "params":{
             "account_id":"18ce552mlaq"
          }
       },
       "data":{
          "conversions_processed":1,
          "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"
       }
    }

​
Tags de eventos da web

GET accounts/:account_id/web_event_tags Recupera detalhes de algumas ou todas as tags de eventos da web associadas à conta atual.

​
URL do recurso

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

​
Parâmetros

NomeDescrição
account_id
obrigatório		O identificador da conta em uso. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado.

Type: string

Example: 18ce54d4x5t
count
opcional		Especifica o número de registros a tentar recuperar por solicitação.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
opcional		Especifica um cursor para obter a próxima página de resultados. Consulte Paginação para mais informações.

Type: string

Example: 8x7v00oow
sort_by
opcional		Ordena por um atributo compatível, em ordem crescente ou decrescente. Consulte Ordenação para mais informações.

Type: string

Example: created_at-asc
web_event_tag_ids
opcional		Limita a resposta apenas às web event tags desejadas especificando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos.

Type: string

Example: o3bk1
with_deleted
opcional		Incluir resultados excluídos na solicitação.

Type: boolean

Default: false
Possible values: true, false
with_total_count
opcional		Incluir o atributo de resposta total_count.

Observação: Este parâmetro e cursor são mutuamente exclusivos.

Observação: Solicitações que incluem total_count terão limites de requisições menores, atualmente definidos em 200 por 15 minutos.

Type: boolean

Default: false
Possible values: true, false

​
Exemplo de requisição

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?web_event_tag_ids=o3bk1

​
Exemplo de resposta

    {
      "request": {
        "params": {
          "web_event_tag_ids": [
            "o3bk1"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "tag de evento da web",
          "view_through_window": 7,
          "click_window": 7,
          "embed_code": "<script src=\"//platform.x.com/oct.js\" type=\"text/javascript\"></script><script type=\"text/javascript\">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\"  src=\"https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0\" /><img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\"  src=\"//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0\" /></noscript>",
          "id": "o3bk1",
          "retargeting_enabled": false,
          "last_tracked_at": "2021-05-22T17:00:04Z",
          "status": "TRACKING",
          "type": "DOWNLOAD"
          "website_tag_id": "ny3od",
          "deleted": false
        }
      ]
    }

​
GET accounts/:account_id/web_event_tags/:web_event_tag_id

Recupera uma tag de evento da web específica associada à conta atual.
URL do recurso
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
Parâmetros
NomeDescrição
account_id
obrigatório		O identificador da conta usada na requisição. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado.

Type: string

Example: 18ce54d4x5t
web_event_tag_id
obrigatório		Uma referência à tag de evento da web utilizada na solicitação.

Type: string

Example: o3bk1
with_deleted
opcional		Inclui resultados excluídos na solicitação.

Type: boolean

Default: false
Possible values: true, false
Exemplo de requisição
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
Exemplo de resposta
    {
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "tag de evento web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src=\"//platform.x.com/oct.js\" type=\"text/javascript\"></script><script type=\"text/javascript\">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\"  src=\"https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0\" /><img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\"  src=\"//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0\" /></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "TRACKING",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": false
      }
    }

​
POST accounts/:account_id/web_event_tags

Cria uma nova tag de evento da web associada à conta atual.

​
URL do recurso

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

​
Parâmetros

NomeDescrição
account_id
obrigatório		O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado.

Type: string

Example: 18ce54d4x5t
click_window
obrigatório		A janela de clique para esta tag da web.

Observação: Somente os valores possíveis listados abaixo são aceitos.

Type: int

Possible values: 1, 7, 14, 30
name
obrigatório		O nome da tag da web.

Type: string

Example: Sample single conversion event
retargeting_enabled
obrigatório		Indica se o retargeting deve ser habilitado para esta tag da web.

Type: boolean

Possible values: true, false
type
obrigatório		O tipo de tag da web.

Type: enum

Possible values: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION,PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(Na interface, SITE_VISIT é exibido como “Page view” e SIGN_UP é exibido como “Lead”)
view_through_window
obrigatório		A janela de visualização para esta tag da web. Este valor deve ser sempre menor ou igual ao valor de click_window.

Observação: Somente os valores possíveis listados abaixo são aceitos.

Type: int

Possible values: 0, 1, 7, 14, 30
Exemplo de requisição
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?click_window=7&name=web event tag&retargeting_enabled=false&type=SITE_VISIT&view_through_window=7

​
Exemplo de resposta

    {
      "data": {
        "name": "tag de evento da web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": null,
        "status": "UNVERIFIED",
        "type": "SITE_VISIT",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "name": "tag de evento da web",
          "view_through_window": 7,
          "click_window": 7,
          "retargeting_enabled": false,
          "account_id": "18ce54d4x5t",
          "type": "SITE_VISIT"
        }
      }
    }

​
PUT accounts/:account_id/web_event_tags/:web_event_tag_id

Atualize uma tag de evento da web associada à conta atual.
URL do recurso
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

​
Parâmetros

NomeDescrição
account_id
obrigatório		O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado.

Type: string

Exemplo: 18ce54d4x5t
web_event_tag_id
obrigatório		O identificador de uma tag da web na conta atual.

Type: string

Exemplo: o3bk1
click_window
opcional		A janela de clique desta tag da web.

Observação: Apenas os valores possíveis listados abaixo são aceitos.

Type: int

Valores possíveis: 1, 7, 14, 30
name
opcional		O nome da tag da web.

Type: string

Exemplo: Sample single conversion event
retargeting_enabled
opcional		Indica se o retargeting deve ser ativado para esta tag da web.

Type: boolean

Valores possíveis: true, false
type
opcional		O tipo de tag da web.

Type: enum

Valores possíveis: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION,PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(Na interface, SITE_VISIT é exibido como “Page view” e SIGN_UP é exibido como “Lead”)
view_through_window
opcional		A janela de visualização desta tag da web. Esse valor deve ser sempre menor ou igual ao valor de click_window.

Observação: Apenas os valores possíveis listados abaixo são aceitos.

Type: int

Valores possíveis: 0, 1, 7, 14, 30

​
Exemplo de requisição

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1?type=DOWNLOAD

​
Exemplo de resposta

    {
      "data": {
        "name": "tag de evento na web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "type": "DOWNLOAD",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​
DELETE accounts/:account_id/web_event_tags/:web_event_tag_id

Exclui uma tag de evento da web específica associada à conta atual.

​
URL do recurso

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
Parâmetros
NomeDescrição
account_id
obrigatório		O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto em GET accounts. A conta especificada deve estar associada ao usuário autenticado.

Tipo: string

Exemplo: 18ce54d4x5t
web_event_tag_id
obrigatório		O identificador de uma tag da web na conta atual.

Tipo: string

Exemplo: o3bk1
Exemplo de requisição
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
Exemplo de resposta
    {
      "data": {
        "name": "tag de evento da web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "NÃO VERIFICADO",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": true
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      }
    }
⌘I