Gerenciamento de contas

Este guia explica como gerenciar contas do Google AdWords (incluindo as de administrador, cliente e teste) usando a AdWords API.

Ele parte do princípio de que você já esteja familiarizado com as contas de cliente e administrador do Google AdWords. Se você precisar revisar os conceitos básicos das contas e dos níveis de acesso do Google AdWords, consulte as páginas conta de administrador e níveis de acesso da Central de Ajuda do Google AdWords.

Como criar e organizar contas

Os serviços de API CustomerService e ManagedCustomerService são usados para criar contas, acessar suas respectivas informações e gerenciar as vinculações entre elas. Para gerenciar os rótulos da conta, use AccountLabelService.

CustomerService

O serviço CustomerService fornece informações sobre suas contas. Ele tem um método getCustomers() que não usa argumentos e retorna uma lista de objetos Customer que contêm campos como customerId, currencyCode e dateTimeZone. O serviço CustomerService também tem um método mutate() que pode ser usado para atualizar vários atributos de um cliente, incluindo os campos autoTaggingEnabled e conversionTrackingSetting.

Nas versões v201605 e anteriores, se nenhum clientCustomerId for especificado, a resposta conterá uma única entrada para a conta autenticada. Ao autenticar usando uma conta de administrador para acessar as informações de uma conta específica, você precisa especificar o clientCustomerId. Para ver mais detalhes, consulte a seção Autenticação abaixo.

A partir da versão v201607, se nenhum clientCustomerId for especificado, a resposta conterá várias entradas caso mais de uma conta seja diretamente acessível pela conta autenticada. Se você quiser os resultados de apenas uma conta, será necessário especificar o clientCustomerId na sua solicitação.

Exemplo de resposta:

<rval>
   <customerId>123456789</customerId>
   <currencyCode>USD</currencyCode>
   <dateTimeZone>America/New_York</dateTimeZone>
   <descriptiveName>myaccount</descriptiveName>
   <canManageClients>false</canManageClients>
</rval>

The Reference documentation contains a list of values for currencies and timezones.

ManagedCustomerService

O serviço ManagedCustomerService também tem um método get() e um seletor genérico. Há mais opções de campo do que no CustomerService. Consulte a documentação de referência para ver mais detalhes.

Além de uma lista de contas que atendem aos critérios no seu seletor, você também recebe uma lista de objetos ManagedCustomerLink que descrevem a relação entre as contas.

<rval>
 <totalNumEntries>3</totalNumEntries>
 <Page.Type>ManagedCustomerPage</Page.Type>
 <entries>
    <name>Account Created with MCS</name>
    <login/>
    <companyName/>
    <customerId>789</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>ZAR</currencyCode>
    <dateTimeZone>Pacific/Pago_Pago</dateTimeZone>
 </entries>
 <entries>
    <name>Adwords Test Manager Account</name>
    <login>my-manager-account@example.com</login>
    <companyName/>
    <customerId>123</customerId>
    <canManageClients>true</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <entries>
    <name>myaccount</name>
    <login>myaccount@example.com</login>
    <companyName/>
    <customerId>456</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>456</clientCustomerId>
 </links>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>789</clientCustomerId>
 </links>
</rval>

O serviço "ManagedCustomerService" é usado para criar novas contas. Essas contas novas pertencerão ao usuário em vigor, que também precisa usar uma conta de administrador. Veja um exemplo de solicitação:

<operations>
  <operator>ADD</operator>
  <operand>
    <name>Foo</name>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </operand>
</operations>

Exemplo de resposta:

<rval>
  <value>
    <name>Foo</name>
    <customerId>9876543210</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </value>
</rval>

Campos como companyName, login e canManageClients são somente leitura e ignorados quando você cria uma nova conta de cliente. Não é possível usar o ManagedCustomerService para atualizar uma conta de cliente depois que ela foi criada.

Como vincular contas

Depois de ser vinculada a uma conta de cliente, a conta de administrador pode fazer solicitações em nome dessa conta de cliente.

O serviço ManagedCustomerService é usado para gerenciar vinculações entre contas, viabilizando o gerenciamento automático da sua hierarquia de contas.

Para vincular uma conta de administrador a uma conta de cliente:

  1. A conta de administrador deve estender um convite para a conta de cliente.
  2. O cliente precisa aceitar o convite.

Como estender convites

Uma conta de administrador pode convidar uma conta de cliente ou outra conta de administrador a ser gerenciada.

Nesse caso, o MANAGER_ID pode ser a conta de administrador com a qual você realizou a autenticação ou outra conta de administrador filha na sua hierarquia. O CLIENT_CID deve ser uma conta de cliente ou administrador que não esteja sendo gerenciada por uma conta de administrador na sua hierarquia.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.PENDING);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.ADD);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Os convites são estendidos por meio do envio de uma operação ADD com um status de vinculação PENDING.

Recuperar convites pendentes

Por meio da conta de cliente ou administrador, é possível usar o parâmetro ManagedCustomerService.getPendingInvitations para recuperar os convites sobre os quais nenhuma ação foi realizada. Depois de ser aceito ou recusado pelo cliente (ou rescindido pela conta de administrador), o convite deixa de estar pendente.

Somente as vinculações ACTIVE são exibidas em uma chamada ManagedCustomerService.get(): as vinculações CANCELLED, REFUSED e INACTIVE nunca são retornadas.

A chamada a seguir retorna todos os convites pendentes da conta de administrador.

PendingInvitationSelector selector = new PendingInvitationSelector();
PendingInvitation[] invitations = managedCustomerService.getPendingInvitations(selector);

Você também pode definir os campos managerCustomerIds e clientCustomerIds com os IDs de cliente das contas de administrador e cliente (respectivamente) para retornar os convites pendentes dessas contas. Para que as vinculações apareçam, lembre-se de que os campos clientCustomerIds precisam ser gerenciados por meio da hierarquia da conta em vigor. Quando o usuário em vigor está usando uma conta de cliente, apenas os convites pendentes dessa conta são exibidos.

Essa solicitação retorna PendingInvitations com registros ManagedCustomer. Os campos Name, login, companyName, customerId, canManageClients são preenchidos tanto na conta de administrador quanto na de cliente.

Como rescindir convites

Se você mudar de ideia depois de ter enviado um convite para gerenciar uma conta de cliente, poderá rescindir esse convite definindo o status da vinculação como CANCELLED em uma operação SET usando a conta de administrador em vigor que pode gerenciar essa vinculação.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.CANCELLED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

O cliente recusa

O cliente também pode recusar o convite ao definir o status da vinculação como REFUSED em uma operação SET. Nessa solicitação, o usuário em vigor precisa ser compatível com o CLIENT_CID ou gerenciá-lo como um proprietário administrativo.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.REFUSED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

O cliente aceita

O cliente aceita o convite usando a operação SET para definir o status da vinculação como ACTIVE. Assim como no ato de recusar, o usuário em vigor precisa ser compatível com o CLIENT_CID ou gerenciá-lo como proprietário administrativo nessa solicitação.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Quando um cliente ou o administrador decide desvincular as contas, é possível encerrar essa vinculação. Use a operação SET para definir o LinkStatus como INACTIVE.

ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.INACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Você pode fazer isso usando tanto uma conta de administrador quanto uma de cliente.

Como transferir contas de cliente

Você pode transferir facilmente uma conta de administrador do Google AdWords para outra usando o ManagedCustomerService.mutateManager(). É possível transferir as contas de cliente e administrador usando o método mutateManager().

MoveOperation op = new MoveOperation();
op.setOldManagerCustomerId(MANAGER_CID);
op.setOperator(Operator.SET);
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(NEW_MANAGER_CID);
op.setOperand(link);
managedCustomerService.mutateManager(new MoveOperation[]{op});

Tanto o administrador novo quanto o antigo precisam ser gerenciados pela conta em vigor. O status da vinculação deve ser ACTIVE. Use o parâmetro NEW_MANAGER_CID como o managerCustomerId da vinculação e especifique o parâmetro antigo MANAGER_CID no oldManagerCustomerId do MoveOperation.

AccountLabelService

Os rótulos da conta são usados para ajudar a organizar e gerenciar as contas. Com o serviço AccountLabelService, é possível adicionar, atualizar ou remover rótulos no nível da conta. Com a API, você também pode gerenciar os rótulos da conta do seu subadministrador.

Limites da conta de administrador

Há algumas limitações que você precisa considerar ao trabalhar com contas de administrador. Você pode encontrá-las na página de referência Limites do sistema, além de uma lista completa de outras limitações do sistema.

As contas do Google AdWords raramente se aproximam dessas limitações. Se uma conta do Google AdWords que você precisa gerenciar já tiver atingido algum limite, corrija os problemas antes de vincular a conta.

Além disso, tenha cuidado para não exceder os limites de taxa operacional.

Autenticação

As chamadas realizadas com base na Google AdWords API exigem um token de desenvolvedor aprovado e credenciais geradas no OAuth2 para a conta segmentada.

A abordagem mais simples consiste em realizar a autenticação usando uma conta de administrador. Depois de realizar a autenticação, você recebe acesso a todas as contas existentes nessa conta de administrador. A autenticação é realizada por meio do OAuth2.

Token de desenvolvedor

Quando você se inscreve na Google AdWords API, um token de desenvolvedor é gerado automaticamente. Assim que você se inscreve, o token fica com aprovação pendente.

While waiting for token approval, you'll be able to make calls against test accounts. Após a aprovação do token, você pode segmentar contas de produção do Google AdWords.

Credenciais do OAuth2

Para fazer alterações ou recuperar os dados de uma conta do Google AdWords especificada, primeiro cada solicitação à Google AdWords API deve ser autorizada. As credenciais do OAuth2 usadas para uma chamada de API determinam quais contas podem ser segmentadas.

Chamadas realizadas com as credenciais de uma conta de administrador podem segmentar a conta de administrador ou qualquer conta para a qual você tenha credenciais do OAuth2. Por exemplo, veja uma hierarquia de contas do Google AdWords:

Seu token de desenvolvedor pode pertencer à Conta de administrador raiz 1 ou até mesmo a uma conta de administrador diferente em outra hierarquia. Isso não afeta as contas que podem ser segmentadas, contanto que você forneça o ID do cliente delas.

Para realizar chamadas de API com base na Conta de cliente A, você pode usar as credenciais do OAuth2 de um login associado a essa conta e definir o cabeçalho de solicitação clientCustomerId como o ID de cliente da Conta de cliente A, Conta de administrador 2 ou Conta de administrador raiz 1.

Nessa estrutura, a Conta de administrador 3 pode realizar chamadas somente com base na Conta de cliente C. Ela não pode realizar chamadas segmentando a Conta de cliente A ou B, pois não as gerencia. A Conta de administrador raiz 1 pode realizar chamadas com base em qualquer uma das contas na hierarquia.

Chamadas realizadas com as credenciais de uma conta de administrador podem segmentar somente a conta de administrador ou aquelas que estão abaixo dessa na hierarquia. Assim, nessa hierarquia, apenas a Conta de administrador raiz 1 pode realizar chamadas com base na Conta de cliente D.

Se você usar qualquer uma das contas de administrador, defina o clientCustomerId para essa conta ou uma das contas filha.

Contas de teste

As contas de administrador e cliente são úteis em termos de organização. Mas como realizar testes de alterações experimentais ou de chamadas de API sem afetar seu ambiente de produção enquanto você trabalha no desenvolvimento? É para isso que servem as contas de teste.

Com as contas de teste, você pode testar novas implementações de API ou configurações das contas antes de implementar as alterações no seu ambiente de produção.

É possível configurar as contas de teste em uma hierarquia e organizá-las assim como as contas de produção, a diferença é que há algumas vantagens durante o desenvolvimento ativo. Especificamente, as contas de teste:

  • não exigem um token de desenvolvedor aprovado, assim você pode começar a realizar experiências com a API imediatamente, até mesmo antes da revisão ou aprovação do seu aplicativo;
  • não podem veicular anúncios nem interagir de forma alguma com suas contas de produção;
  • podem ser visualizadas e manipuladas na interface da Web do Google AdWords, assim como as contas normais.

Como as contas de teste e produção não podem interagir de forma alguma, não é possível usar uma conta de teste na sua conta de administrador de produção existente. Para usar as contas de teste, você precisa de uma nova hierarquia de contas com uma conta de administrador de teste como raiz.

As contas de teste podem ser acessadas na interface da Web do Google AdWords e aparecem com um rótulo vermelho (veja abaixo).

As contas de teste têm as mesmas restrições (incluindo limites de taxa) que as contas de produção.

Primeiros passos com as contas de teste

Antes de fazer solicitações de API para uma conta de teste, você precisa ter uma conta de administrador de produção (que não seja de teste) e um token de desenvolvedor, mesmo que o token esteja com aprovação pendente.

Ao usar sua conta de administrador de produção, primeiro você precisa criar uma conta de administrador de teste antes de criar contas de cliente de teste. Todas as contas de cliente criadas na conta de administrador de teste são automaticamente marcadas como contas de teste.

Siga as etapas abaixo para criar e usar uma conta de teste:

  1. Caso você ainda não tenha uma conta de administrador de produção e/ou um token de desenvolvedor da conta de administrador de produção:
    1. Crie uma conta de administrador de produção (por exemplo, production-manager@mycompany.example.com).
    2. Solicite um token de desenvolvedor na conta de administrador de produção.
  2. Crie uma conta de administrador de teste (por exemplo, test-manager@mycompany.example.com). Para criar uma conta de teste, você precisa ter uma Conta do Google existente que ainda não esteja vinculada a uma conta do Google AdWords. Você pode criar uma nova Conta do Google em accounts.google.com.
  3. Use o token de desenvolvedor da conta de administrador de produção ao fazer solicitações com base na conta de administrador de teste.
  4. Ao solicitar um token de atualização do OAuth2, faça login como usuário da conta de administrador de teste (por exemplo, test-manager@mycompany.example.com).

A tabela abaixo explica as interações permitidas entre diferentes tipos de conta do Google AdWords e um token de desenvolvedor com base no respectivo status de aprovação:

Status do token de desenvolvedor da conta de produção Tipo de conta do Google AdWords Permitido
Aprovação pendente Teste Sim
Aprovação pendente Não teste Não
Aprovado Teste Sim
Aprovado Não teste Sim

Como usar o OAuth2 com as contas de teste

Para acessar uma conta de teste usando o OAuth2, o usuário da conta de administrador de teste precisa conceder permissão ao seu aplicativo cliente. Portanto, ao solicitar um token de atualização, faça login com a conta de administrador de teste em vez da conta de administrador de produção.

Se você deseja alternar entre a conta de administrador de teste e a conta de administrador de produção, basta reconfigurar a biblioteca cliente para usar o token de atualização da conta de administrador de produção.

Cabeçalhos de solicitação

Todas as solicitações para as contas de teste devem ser enviadas ao mesmo ponto de extremidade que as solicitações de produção:

https://www.googleapis.com/auth/adwords/

Os cabeçalhos SOAP de solicitação e resposta são idênticos àqueles retornados em contas de produção. Para acessar os cabeçalhos de autorização, use as credenciais da sua conta de teste.

Outras características das contas de teste

Ao trabalhar com as contas de teste, você precisa considerar alguns aspectos:

  • Os serviços TargetingIdeaService e TrafficEstimatorService retornam dados fictícios para as contas de teste.
  • Como as contas de teste não veiculam anúncios, elas também não têm métricas. Isso afeta os relatórios: todos os valores de impressões, custos etc. serão zero.
  • As contas de teste não têm cliques associados e, por isso, não podem ser usadas para testar uploads de conversões off-line.
  • O serviço DataService não retorna cenários do lance para contas de teste, pois esses cenários se baseiam em anúncios veiculados por meio da conta.
  • Você pode ter apenas 100 contas na hierarquia de uma conta de administrador de teste. O limite para as contas de produção é muito mais alto.

Como desenvolver com as contas de teste

Ao se inscrever para receber acesso à Google AdWords API, talvez você precise demonstrar alguns recursos do seu aplicativo. Um desses recursos seria a geração de relatórios, que pode ser difícil de emular ao usar somente contas de teste.

Como as contas de teste não veiculam impressões, elas não produzem métricas. Ainda é possível fazer o download de relatórios estruturais, mas aparecem apenas linhas sem impressões, o que significa que os segmentos não funcionam.

Uma alternativa seria exibir dados falsos. A equipe de revisão de token precisa ver que seu aplicativo pode exibir e interagir com os dados do relatório. Ao simular a chamada do relatório (ou veja, fingir que a chamada do relatório foi bem-sucedida e usar um arquivo armazenado localmente que contém falsos dados do relatório), você pode adicionar os dados de relatório sem precisar acessá-los por meio da API.

Confirme se os dados do relatório de teste estão no formato correto. Por exemplo, se você executar um relatório de desempenho da campanha com data, nome da campanha, código da campanha, impressões, cliques e custos, seu arquivo será assim:

"CAMPAIGN_PERFORMANCE_REPORT (Mar 20, 2013-Mar 23, 2013)"
Day,Campaign,Campaign ID,Impressions,Clicks,Cost
20130320,Widgets,123,1211,19,14.92
20130320,Sprockets,456,300,4,2.92
20130321,Widgets,123,901,12,9.86
20130321,Sprockets,456,340,5,3.86
20130322,Widgets,123,1065,16,11.23
20130322,Sprockets,456,509,6,5.23
20130323,Widgets,123,1005,15,10.12
20130323,Sprockets,456,287,3,1.12

Ao criar esse arquivo e armazená-lo localmente, seu aplicativo pode simular a chamada para a API. Quando o relatório for solicitado, em vez de realizar uma chamada de API de verdade, retorne o arquivo armazenado e o processe. Você pode criar um desses arquivos para cada relatório que deseja exibir.

Como realizar testes com os dados de produção

Se você utilizar o cabeçalho validateOnly nas suas solicitações e tiver um token de desenvolvedor aprovado, poderá realizar testes usando os dados de produção de modo somente leitura nas suas contas de produção.

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.