Acessando contas de anúncios

​

Contas de usuário vs Contas de anúncios

Há dois tipos diferentes de contas envolvidas no uso da X Ads API: contas de anúncios e contas de usuário do X. Ao longo da documentação da X Ads API, o termo “conta” geralmente se refere à conta de anúncios.

• As contas de anúncios são registradas em business.x.com e identificadas na API por account_id. Elas se vinculam 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 anúncios pode conceder permissões a uma ou mais contas de usuário do X. A conta de anúncios, ou “conta atual”, é representada em quase todas as URLs executadas como um parâmetro in-line :account_id.
• As contas de usuário do X (como @AdsAPI) são identificadas por user_id na X Ads API. Uma ou mais dessas contas podem ser associadas a uma conta de anúncios. A conta de usuário do X autenticada que faz solicitações na API é chamada de ‘usuário atual’. Uma listagem das contas de anúncios às quais o usuário atual tem acesso pode ser encontrada em GET accounts. ‘Promotable users’ são @handles do X que podem ser promovidos por uma conta de anúncios específica. Para mais detalhes, consulte Obtaining Ads Account Access.

​

Métodos para acesso à conta de anúncios

Há dois métodos que você pode usar para fazer solicitações à X Ads API para a conta de um anunciante:

1. Fazer solicitações em nome de um anunciante (recomendado)
2. Fazer solicitações usando sua conta que recebeu acesso à conta de um anunciante, por exemplo, uma agência que dá suporte a várias contas.

Este documento é uma breve visão geral das diferenças entre essas opções e deve ser usado em conjunto com outros recursos, como as perguntas frequentes sobre login multiusuário.

Conforme descrito em Autorizar uma solicitação, todas as solicitações à X Ads API exigem cabeçalhos de autorização usando OAuth 1.0a com um access token obtido via fluxo OAuth de 3 etapasOAuth. Seu aplicativo precisará implementar um fluxo OAuth baseado na web para obter access tokens. Desenvolvedores da X Ads API nunca devem solicitar que os anunciantes da X compartilhem suas credenciais de login.

Por padrão, cada X developer application contém um access token estático que pode ser usado para fazer solicitações à X Ads API para a conta proprietária do aplicativo. Essas credenciais são ideais para casos de uso de conta única, sem exigir um fluxo OAuth de 3 etapas ou PIN-based OAuth. Se você não estiver acessando outra conta de anúncios da X, use essas credenciais de usuário único em vez das etapas a seguir.

​

Níveis de acesso

​

Permissões no nível da App

Cada usuário terá um nível de acesso conforme solicitado na solicitação de acesso à X Ads API:

• Somente conversão: o usuário tem acesso aos endpoints de Mobile e Web Conversion, com leitura e gravação.
• Acesso padrão: o usuário tem acesso aos endpoints de Analytics, Campaign Management, Creatives, Custom Audiences e Conversion, com leitura e gravação.

Observação: Desenvolvedores da X Ads API que solicitaram acesso antes de julho de 2023 podem ter níveis de acesso e permissões diferentes e podem estar limitados a cinco tokens OAuth. Consulte nosso guia sobre ampliar o acesso para obter acesso a endpoints adicionais ou remover limites de tokens para Apps existentes.

​

Permissões no nível da Conta de Anúncios

Cada usuário com acesso a uma Conta de Anúncios terá uma permissão específica no nível da conta: Administrador da conta, Gerente de anúncios, Analista de campanhas, Analista orgânico e Gerente criativo; consulte business.x.com para a documentação mais recente sobre permissões no nível da conta. Os apps devem obter as permissões do usuário atualmente autenticado por meio do endpoint da API Authenticated User Access para determinar quais endpoints da API e quais recursos de Anúncios podem ser acessados.

Observação: Quaisquer tokens de usuário usados com a Conversion API devem pertencer a usuários com permissões no nível da conta de Administrador da conta ou Gerente de anúncios.                                                                                                                                              

​

Métodos de obtenção de access tokens

​

1. Obter o access token de um anunciante (Usuário)

Há dois métodos para obter o access token de um anunciante. O método mais comum é por meio de um fluxo OAuth de 3 etapas diretamente na sua interface web. Aplicações que não têm uma interface pública exposta a anunciantes podem implementar um processo OAuth baseado em PIN. Após o usuário concluir o fluxo de 3 etapas, sua aplicação terá credenciais para fazer solicitações à conta de Ads desse usuário via API.

Obter credenciais de usuário via fluxo OAuth é o método que recomendamos fortemente para a maioria dos desenvolvedores da X Ads API para obter acesso a uma conta de anunciante. Isso permite chamar a API em nome de um usuário e executar ações como esse usuário. Esses tokens não expiram, mas podem ser revogados pelo usuário a qualquer momento.

​

2. Obtenha seu access token (de desenvolvedor)

Essa opção exige que o anunciante conceda acesso ao seu @username (ou @usernames) à conta do X Ads dele por meio da interface do X em business.x.com. Access tokens obtidos por meio do fluxo OAuth de 3 etapas para a sua conta poderão acessar a conta do 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 principal distinção nessa opção é que você só poderá criar Posts somente promovidos se a permissão de delegação/compositor de Post tiver sido concedida ao seu @username.

Para obter acesso para criar Posts somente promovidos em nome do usuário promovível FULL na conta, você também deve receber acesso para criar Posts nesse fluxo. Isso habilitará o acesso por meio da permissão TWEET_COMPOSER no endpoint GET accounts/:account_id/authenticated_user_access.

​

Diferenças entre esses métodos

	OAuth Token do Anunciante (Usuário)	OAuth Token (Desenvolvedor)  (@username adicionado para separar a conta)
Acessar conta de anúncios	✔	✔
Criar Posts em nome do usuário	✔	✔*
Gerenciar campanhas	✔	✔
Acessar Analytics	✔	✔
Criar Cards em nome do usuário	✔	✔
Capacidade do desenvolvedor de acessar via X Ads UI		✔
Limites de requisições	Distintos por anunciante	Distintos por conta de anunciante

Nota: Consulte a seção Obtenha seu access token (Desenvolvedor) acima para mais detalhes.

​

Exemplo de caso de uso

​

Access Token do anunciante via fluxo web OAuth de 3 etapas

O fluxo padrão é baseado na web e usa o fluxo OAuth de autorização em 3 etapas. As capturas de tela apresentadas aqui fazem parte de um exemplo cujo código-fonte você pode conferir em https://github.com/xdevplatform/twauth-web.

Em algum momento do seu aplicativo, você vai querer redirecionar para o X para autorizar seu aplicativo

Quando você redirecionar para o X com o token de solicitação, o usuário verá um prompt para autorizar seu aplicativo

Ao autorizar seu aplicativo, o usuário será redirecionado para a URL de callback fornecida quando você gerou o token de solicitação. Você usará isso para obter o Access Token permanente desse usuário e armazená-lo localmente!