Ads Manager Scripts

The AdsManagerApp class in Google Ads scripts enables you to manage accounts linked under your Manager Account. You can manage all your advertiser accounts through a single script instead of creating a separate script for each account.

Retrieve list of accounts

You can retrieve accounts under a manager account using the accounts method, for example:

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

const accountIterator = accountSelector.get();

There are some restrictions to the accounts that can be retrieved:

• Manager accounts cannot be retrieved if you have a multi-level hierarchy. Only the client accounts can be selected.
• By default, closed, canceled, and suspended accounts are not returned. You can override this behavior by calling withCondition specifying a different filter for customer_client.status.

The accounts call retrieves the list of all client accounts under the manager account hierarchy by default. You can use the withLimit method of the ManagedAccountSelector class to restrict the number of accounts that your script retrieves. Another option is to select the accounts by their customer IDs using the withIds method:

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

Work on client accounts

Once you've retrieved the client accounts, you can iterate through them using the iterator's hasNext and next methods. You need to use the select method to switch the execution context to a client account. After you select a client account, any further API calls apply to the client account until you explicitly select another account:

// 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
  ...
}

Work on accounts in parallel

Google Ads scripts lets you operate on multiple client accounts in parallel, using the executeInParallel method of the ManagedAccountSelector class. The executeInParallel method has the following signature:

function executeInParallel(functionName, optionalCallbackFunctionName, optionalInput);

The executeInParallel method executes a function specified by functionName on each ManagedAccount that the ManagedAccountSelector matches. Once all accounts have been processed, the callback function, if specified by optionalCallbackFunctionName, is executed once, passing a list of ExecutionResult objects as its argument for any further processing. The typical usage is shown below:

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
    ...
  }
}

The function specified by functionName can optionally accept a string argument (optionalInput). This parameter can be used to pass an additional parameter to all parallel methods called by 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.
  ...
}

If you want to pass a JavaScript configuration object that contains account-specific settings, you could first convert it into a string using the JSON.stringify method:

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.
  ...
}

The function specified by functionName can also return a string instead of an object through JSON.stringify:

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

The returned values are passed into the callback function in a list of ExecutionResult objects. If you returned a JSON string from the function, you could convert it back into a JavaScript object using JSON.parse method:

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

The executeInParallel method operates on a maximum of 50 accounts, so you'll have to implement your own restrictions to limit the number of accounts that your script retrieves. You can use the withLimit or withIds method of ManagedAccountSelector class to restrict the number of accounts that your script retrieves.

Execution time limits

See this page for details on Ads Manager scripts execution time limits.