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