Ads Manager Scripts

A classe AdsManagerApp nos scripts do Google Ads permite gerenciar contas vinculadas à sua conta de administrador. Você pode gerenciar todas as suas contas de anunciante com um único script, em vez de criar um script separado para cada conta.

Recuperar lista de contas

É possível recuperar contas em uma conta de administrador usando o método accounts, por exemplo:

const accountSelector = AdsManagerApp.accounts()
    .withCondition('customer_client.descriptive_name = "My Account"');

const accountIterator = accountSelector.get();

Há algumas restrições para as contas que podem ser recuperadas:

• Não é possível recuperar contas de administrador se você tiver uma hierarquia multinível. Somente as contas de clientes podem ser selecionadas.
• Por padrão, contas encerradas, canceladas e suspensas não são retornadas. É possível substituir esse comportamento chamando withCondition e especificando um filtro diferente para customer_client.status.

Por padrão, a chamada accounts recupera a lista de todas as contas de cliente na hierarquia da conta de administrador. Use o método withLimit da classe ManagedAccountSelector para restringir o número de contas que seu script recupera. Outra opção é selecionar as contas pelos IDs de cliente usando o método withIds:

// Hyphens in the account ID are optional.
const accountSelector = AdsManagerApp.accounts()
    .withIds(['123-456-7890', '234-567-8901', '345-678-9012']);

Trabalhar em contas de cliente

Depois de recuperar as contas de cliente, você pode iterar por elas usando os métodos hasNext e next do iterador. Use o método select para mudar o contexto de execução para uma conta de cliente. Depois de selecionar uma conta de cliente, todas as chamadas de API subsequentes se aplicam a ela até que você selecione outra conta explicitamente:

// Keep track of the manager account for future reference.
const managerAccount = AdsApp.currentAccount();

// Select your accounts
const accountIterator = AdsManagerApp.accounts()
// ... Write some logic here to select the accounts you want using
// withCondition or withIds

// Iterate through the list of accounts
for (const account of accountIterator) {
  // Select the client account.
  AdsManagerApp.select(account);

  // Select Search and Display campaigns under the client account
  const campaignIterator = AdsApp.campaigns().get();

  // Operate on client account
  ...
}

Trabalhar em contas em paralelo

Os scripts do Google Ads permitem operar em várias contas de cliente em paralelo usando o método executeInParallel da classe ManagedAccountSelector. O método executeInParallel tem a seguinte assinatura:

function executeInParallel(functionName, optionalCallbackFunctionName, optionalInput);

O método executeInParallel executa uma função especificada por functionName em cada ManagedAccount que o ManagedAccountSelector corresponde. Depois que todas as contas forem processadas, a função de callback, se especificada por optionalCallbackFunctionName, será executada uma vez, transmitindo uma lista de objetos ExecutionResult como argumento para qualquer outro processamento. O uso típico é mostrado aqui:

function main() {
  const accountSelector = AdsManagerApp.accounts()
      .withLimit(50)
      .withCondition('customer_client.currency_code = "USD"');

  accountSelector.executeInParallel("processClientAccount", "afterProcessAllClientAccounts");
}

function processClientAccount() {
  const clientAccount = AdsApp.currentAccount();

  // Process your client account here.
  ...

  // optionally, return a result, as text.
  return "";
}

function afterProcessAllClientAccounts(results) {
  for (const result of results) {
    // Process the result further
    ...
  }
}

A função especificada por functionName pode aceitar opcionalmente um argumento de string (optionalInput). Esse parâmetro pode ser usado para transmitir um parâmetro adicional a todos os métodos paralelos chamados por executeInParallel:

function main() {
  const accountSelector = AdsManagerApp.accounts().withIds([1234567890, 3456787890]);
  const sharedParameter = "INSERT_SHARED_PARAMETER_HERE";
  accountSelector.executeInParallel("processClientAccount", null, sharedParameter);
}

function processClientAccount(sharedParameter) {
  // Process your client account here.
  ...
}

Se você quiser transmitir um objeto de configuração JavaScript que contenha configurações específicas da conta, primeiro converta-o em uma string usando o método JSON.stringify:

function main() {
  ...
  const accountFlags = {
    '1234567890': {
       'label': 'Brand 1 campaigns',
     },
    '3456787890': {
       'label': 'Brand 2 campaigns',
     }
  };
  accountSelector.executeInParallel("processClientAccount", null,
      JSON.stringify(accountFlags));
  ...
}

function processClientAccount(sharedParameter) {
  const accountFlags = JSON.parse(sharedParameter);
  // Process your client account here.
  ...
}

A função especificada por functionName também pode retornar uma string em vez de um objeto usando JSON.stringify:

function processClientAccount() {
  ...
  const jsonObj = {value: 10, list: [1,2,3,4,5,6], name: "Joe Smith"};
  return JSON.stringify(jsonObj);
}

Os valores retornados são transmitidos para a função de callback em uma lista de objetos ExecutionResult. Se você retornou uma string JSON da função, é possível convertê-la de volta em um objeto JavaScript usando o método JSON.parse:

function callbackFunctionName(results) {
  for (var i = 0; i < results.length; i++) {
    var resultObj = JSON.parse(results[i].getReturnValue());
  }
}

O método executeInParallel opera em um máximo de 50 accounts. Portanto, você terá que implementar suas próprias restrições para limitar o número de contas que seu script recupera. Você pode usar o método withLimit ou withIds da classe ManagedAccountSelector para restringir o número de contas que seu script recupera.

Limites de tempo de execução

Consulte a documentação de limites para mais detalhes sobre os limites de tempo de execução dos scripts do Gerenciador de anúncios.