Skip to main content

​
Contas de usuário vs contas de Ads

Existem dois tipos diferentes de contas envolvidas no uso da Ads API: contas de publicidade e contas de usuário do X. Ao longo da documentação da Ads API, o termo “conta” geralmente se refere à conta de publicidade.
  • Contas de publicidade são registradas em business.x.com e identificadas na API por account_id. Contas de publicidade se conectam diretamente a fontes de financiamento e utilizam conteúdo de uma ou mais contas de usuário do X como ‘promotable users’. Cada conta de publicidade pode conceder permissão a uma ou mais contas de usuário do X. A conta de publicidade, ou “current account”, é representada em quase todas as URLs executadas como um parâmetro in-line :account_id.
  • Contas de usuário do X (como @AdsAPI) são identificadas por user_id na Ads API. Uma ou mais dessas contas podem ser associadas a uma conta de publicidade. A conta de usuário do X autenticada fazendo requisições à API é referida como ‘current user’. Uma listagem de contas de publicidade às quais o current user tem acesso pode ser obtida com GET accounts. ‘Promotable users’ são handles do X que podem ser promovidos por uma conta de publicidade específica. Para mais detalhes sobre isso, consulte Obtaining Ads Account Access.

​
Métodos para acesso à conta Ads

Existem dois métodos que você pode usar para fazer requisições à Ads API em nome de uma conta de anunciante:
  1. Fazer requisições em nome de um Anunciante (recomendado)
  2. Fazer requisições usando sua conta que recebeu acesso à conta do Anunciante, por exemplo, uma Agência que suporta múltiplas contas.
Este documento é uma breve visão geral das diferenças entre essas opções e deve ser usado em conjunto com nossos outros recursos, como o multi-user login FAQ. Como descrito em Autorizando uma requisição, todas as requisições à Ads API requerem headers de Authorization usando OAuth 1.0a com um access token obtido via fluxo OAuth de 3 etapas. Sua aplicação precisará implementar um fluxo OAuth baseado na web para obter access tokens. Desenvolvedores da Ads API nunca devem solicitar que nossos anunciantes do X compartilhem suas credenciais de login. Por padrão, cada aplicação de desenvolvedor do X contém um access token estático que pode ser usado para fazer requisições à Ads API para a conta que possui a aplicação. Essas credenciais são ideais para casos de uso de conta única sem exigir um fluxo OAuth de 3 etapas ou baseado em PIN. Se você não está acessando outra conta do X Ads, use essas credenciais single-user em vez das etapas a seguir.

​
Níveis de acesso

​
Permissões em nível de aplicação

Cada usuário terá um nível de acesso conforme solicitado na aplicação para a Ads API: Nota: Desenvolvedores da Ads API que solicitaram acesso antes de julho de 2023 podem ter níveis diferentes de acesso e permissões, e podem estar limitados a cinco OAuth tokens. Consulte nosso guia sobre aumentar o acesso para acessar endpoints adicionais ou remover limites de token para aplicações existentes.

​
Permissões em nível de conta Ads

Cada usuário que tem acesso a uma conta Ads terá uma permissão específica em nível de conta: Account administrator, Ad manager, Campaign analyst, Organic analyst e Creative Manager; consulte business.x.com para a documentação mais recente sobre permissões em nível de conta. As aplicações devem recuperar as permissões do usuário autenticado atualmente via o endpoint Authenticated User Access para determinar quais endpoints e recursos de Ads podem acessar. Nota: Quaisquer user tokens usados com a Conversion API devem ser de usuários com permissões em nível de conta Account administrator ou Ad manager.

​
Métodos de obtenção de access tokens

​
1. Obter um access token de anunciante (User)

Existem dois métodos para obter o access token de um anunciante. O método mais comum é via um fluxo OAuth de 3 etapas diretamente da sua UI web. Aplicações que não têm uma UI publicamente acessível exposta aos anunciantes podem implementar um processo OAuth baseado em PIN. Depois que o usuário conclui o fluxo de 3 etapas, sua aplicação terá credenciais para fazer requisições à conta Ads via API. Obter credenciais de usuário via fluxo OAuth é o método que recomendamos fortemente para a maioria dos desenvolvedores da Ads API para obter acesso a uma conta de anunciante. Isso permite que você chame a API em nome de um usuário e execute ações como esse usuário. Esses tokens não expiram, mas podem ser revogados pelo usuário a qualquer momento.

​
2. Obter seu access token (Developer)

Esta opção requer que o anunciante conceda ao seu @username (ou @usernames) acesso à conta X Ads via UI do X em business.x.com. Access tokens obtidos através do fluxo OAuth de 3 etapas para sua conta poderão acessar a conta X Ads do anunciante. Isso permite que você chame a API usando os tokens OAuth do seu próprio @username em vez dos tokens OAuth do anunciante. A distinção chave nesta opção é que você só pode criar Posts Promoted-Only se a permissão de delegação/composer de Post tiver sido concedida ao seu @username. Para obter acesso para criar Posts Promoted-Only em nome do promotable user FULL na conta, você também deve receber acesso para criar Posts nesse fluxo. Isso habilitará o acesso via a permissão TWEET_COMPOSER no endpoint GET accounts/:account_id/authenticated_user_access.

​
Diferenças entre esses métodos

Nota: Consulte a seção Obter seu access token (Developer) acima para detalhes.

​
Caso de uso de exemplo

​
Access token do anunciante via fluxo web OAuth de 3 etapas

O fluxo padrão é baseado em web e utiliza o fluxo de autorização OAuth de 3 etapas. As capturas de tela apresentadas aqui fazem parte de um exemplo cujo código-fonte pode ser visto em https://github.com/xdevplatform/twauth-web. Em algum momento da sua aplicação, você desejará redirecionar para o X para autorizar sua aplicação
image0
Quando você redireciona para o X com o request token, o usuário será solicitado a autorizar sua aplicação
image1
Ao autorizar sua aplicação, o usuário será redirecionado para a URL de callback fornecida quando você gerou o request token. Você usará isto para obter o access token permanente para este usuário e armazená-lo localmente!
image