# Ads Manager Scripts

The
[`AdsManagerApp`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp)
class in Google Ads scripts let you manage accounts linked under your
[Manager Account](https://ads.google.com/home/tools/manager-accounts/). 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`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp#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`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_managedaccountselector#withLimit_limit)
method of the
[`ManagedAccountSelector`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_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`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_managedaccountselector#withIds_ids)
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`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_managedaccountiterator#hasNext)
and
[`next`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_managedaccountiterator#next)
methods. You need to use the
[`select`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp#select_account)
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 Search and Display 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`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_managedaccountselector#executeInParallel_functionName-optionalCallbackFunctionName)
method of the
[`ManagedAccountSelector`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_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`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_managedaccount)
that the
[`ManagedAccountSelector`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_managedaccountselector)
matches. Once all accounts have been processed, the callback function, if
specified by `optionalCallbackFunctionName`, is executed once, passing a list
of
[`ExecutionResult`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_executionresult)
objects as its argument for any further processing. The typical usage is shown
here:  

    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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_executionresult)
objects. If you returned a JSON string from the function, you could convert it
back into a JavaScript object using
[`JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse)
method:  

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

The
[`executeInParallel`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_managedaccountselector#executeInParallel_functionName-optionalCallbackFunctionName)
method operates on a maximum of 50
[`accounts`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp#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`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_managedaccountselector#withLimit_limit)
or
[`withIds`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_managedaccountselector#withIds_ids)
method of
[`ManagedAccountSelector`](https://developers.google.com/google-ads/scripts/docs/reference/adsmanagerapp/adsmanagerapp_managedaccountselector)
class to restrict the number of accounts that your script retrieves.

## Execution time limits

See [the limits documentation](https://developers.google.com/google-ads/scripts/docs/limits#ads_manager_scripts)
for details on Ads Manager scripts execution time limits.