Builders

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.
var adGroup = AdsApp.adGroups().get().next();

// Create a keyword operation.
var 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.
  var keyword = keywordOperation.getResult();
} else {
  // Handle the errors.
  var errors = keywordOperation.getErrors();
}

The current release adds builder support for keywords, ad groups, and ad extensions: phone number, sitelinks and mobile apps. The addSitelink, addPhoneNumber, and addMobileApp methods of AdGroupand Campaign classes will now return the resulting operation.

Performance considerations

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

for (var i = 0; i < keywords.length; i++)
  var keywordOperation = adGroup
    .newKeywordBuilder()
    .withText(keywords[i])
    .build();

  // Bad: retrieving the result in the same
  // loop that creates the operation
  // leads to poor performance.
  var newKeyword =
      keywordOperation.getResult();
  newKeyword.applyLabel("New keywords”);
}

// Create an array to hold the operations
var operations = [];

for (var i = 0; i < keywords.length; i++) {
  var keywordOperation = adGroup
    .newKeywordBuilder()
    .withText(keywords[i])
    .build();
  operations.push(keywordOperation);
}

// Process the operations separately. Allows
// Google Ads scripts to group operations into
// batches.
for (var i = 0; i < operations.length; i++) {
  var newKeyword = operations[i].getResult();
  newKeyword.applyLabel("New keywords”);
}