Ads Manager Scripts

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

Extrair uma 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 de vários níveis. Somente as contas de cliente podem ser selecionadas.
• Por padrão, as contas fechadas, canceladas e suspensas não são retornadas. É possível modificar esse comportamento chamando withCondition e especificando um filtro diferente para customer_client.status.

A chamada accounts recupera a lista de todas as contas de cliente na hierarquia da conta de administrador por padrão. Você pode usar o método withLimit da classe ManagedAccountSelector para restringir o número de contas que o 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 usando os métodos hasNext e next do iterador. É necessário usar 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 outras chamadas de API serão aplicadas a ela até que você selecione explicitamente outra conta:

// 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 campaigns under the client account
  const campaignIterator = AdsApp.campaigns().get();

  // Operate on client account
  ...
}

Trabalhar em contas paralelas

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 concorda. 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 processamento adicional. O uso típico é mostrado abaixo:

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 um argumento de string (optionalInput) como opcional. 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, então você terá que implementar suas próprias restrições para limitar o número de contas que o script recupera. Você pode usar o método withLimit ou withIds da classe ManagedAccountSelector para restringir o número de contas que o script recupera.

Limites de tempo de execução

Consulte esta página para saber mais sobre os limites de tempo de execução dos scripts do Gerenciador de anúncios.