Builders
Stay organized with collections
Save and categorize content based on your preferences.
Builders are the standard way to create entities in Google Ads scripts. Builders allow
you to build a Google Ads entity either synchronously or asynchronously. You
can also check whether the operation was successful or not, and take
appropriate actions depending on the operation's outcome. The following code
snippet shows how to create a keyword using a builder.
// Retrieve your ad group.
let
adGroup
=
AdsApp
.
adGroups
().
get
().
next
();
// Create a keyword operation.
let
keywordOperation
=
adGroup
.
newKeywordBuilder
()
.
withCpc
(
1.2
)
.
withText
(
"shoes"
)
.
withFinalUrl
(
"http://www.example.com/shoes"
)
.
build
();
// Optional: examine the outcome. The call to isSuccessful()
// will block until the operation completes.
if
(
keywordOperation
.
isSuccessful
())
{
// Get the result.
let
keyword
=
keywordOperation
.
getResult
();
}
else
{
// Handle the errors.
let
errors
=
keywordOperation
.
getErrors
();
}
Any entity that can be created using Google Ads scripts does so using this builder
pattern.
By default, Google Ads scripts executes its operations asynchronously. This
allows scripts to group your operations as batches, and achieve high
performance. However, calling the Operation
methods like isSuccessful()
and getResult()
forces Google Ads scripts to flush its pending operations list, and thus may lead to
poor performance. Instead, create an array to hold the operations, then iterate
through that array to retrieve the results.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License
, and code samples are licensed under the Apache 2.0 License
. For details, see the Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-09-03 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-03 UTC."],[[["\u003cp\u003eBuilders are the standard way to create entities in Google Ads Scripts, offering synchronous and asynchronous options with success checks.\u003c/p\u003e\n"],["\u003cp\u003eThe builder pattern is utilized for creating any entity within Google Ads scripts.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Ads scripts default to asynchronous operations for performance, but retrieving results immediately can hinder this; it's recommended to batch operations for efficiency.\u003c/p\u003e\n"],["\u003cp\u003eInstead of retrieving results directly after each operation, store operations in an array and process them separately to enhance script performance by allowing for batching.\u003c/p\u003e\n"]]],[],null,["# Builders are the standard way to create entities in Google Ads scripts. Builders allow\nyou to build a Google Ads entity either synchronously or asynchronously. You\ncan also check whether the operation was successful or not, and take\nappropriate actions depending on the operation's outcome. The following code\nsnippet shows how to create a keyword using a builder. \n\n // Retrieve your ad group.\n let adGroup = AdsApp.adGroups().get().next();\n\n // Create a keyword operation.\n let keywordOperation = adGroup.newKeywordBuilder()\n .withCpc(1.2)\n .withText(\"shoes\")\n .withFinalUrl(\"http://www.example.com/shoes\")\n .build();\n\n // Optional: examine the outcome. The call to isSuccessful()\n // will block until the operation completes.\n if (keywordOperation.isSuccessful()) {\n // Get the result.\n let keyword = keywordOperation.getResult();\n } else {\n // Handle the errors.\n let errors = keywordOperation.getErrors();\n }\n\nAny entity that can be created using Google Ads scripts does so using this builder\npattern.\n\nPerformance considerations\n--------------------------\n\nBy default, Google Ads scripts executes its operations asynchronously. This\nallows scripts to group your operations as batches, and achieve high\nperformance. However, calling the\n[Operation](/google-ads/scripts/docs/reference/adsapp/adsapp_sitelinkoperation)\nmethods like\n[`isSuccessful()`](/google-ads/scripts/docs/reference/adsapp/adsapp_sitelinkoperation#isSuccessful)\nand\n[`getResult()`](/google-ads/scripts/docs/reference/adsapp/adsapp_sitelinkoperation#getResult)\nforces Google Ads scripts to flush its pending operations list, and thus may lead to\npoor performance. Instead, create an array to hold the operations, then iterate\nthrough that array to retrieve the results.\n\n| Poor performance | Good performance |\n|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ```transact-sql for (let i = 0; i \u003c keywords.length; i++) let keywordOperation = adGroup .newKeywordBuilder() .withText(keywords[i]) .build(); // Bad: retrieving the result in the same // loop that creates the operation // leads to poor performance. let newKeyword = keywordOperation.getResult(); newKeyword.applyLabel(\"New keywords\"); } ``` | ```transact-sql // Create an array to hold the operations let operations = []; for (let i = 0; i \u003c keywords.length; i++) { let keywordOperation = adGroup .newKeywordBuilder() .withText(keywords[i]) .build(); operations.push(keywordOperation); } // Process the operations separately. Allows // Google Ads scripts to group operations into // batches. for (let i = 0; i \u003c operations.length; i++) { let newKeyword = operations[i].getResult(); newKeyword.applyLabel(\"New keywords\"); } ``` |"]]
