Page Summary
-
The
AdsManagerAppclass in Google Ads scripts allows you to manage accounts linked under your Manager Account through a single script. -
You can retrieve a list of accounts under a manager account using the
accountsmethod, with options to filter or limit the results. -
To work on client accounts, you iterate through the retrieved accounts and use the
selectmethod to switch the script's execution context to a specific client account. -
Google Ads scripts supports parallel processing of multiple client accounts using the
executeInParallelmethod.
The AdsManagerApp
class in Google Ads scripts let you 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
withConditionspecifying 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 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
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
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
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 the limits documentation for details on Ads Manager scripts execution time limits.
