AdsApp.​AdCustomizerItemBuilder

Builder for AdCustomizerItem objects. Example usage:
adCustomizerSource.adCustomizerItemBuilder()
  .withAttributeValues(                // at least one value is required
    {numLeft: 5, lowCost: "$0.99"})
  .withTargetCampaign("Campaign name")
  .withTargetKeyword("[keyword]")      // optional
  .withMobilePreferred(true)           // optional
  .build();                            // create the ad customizer item

Methods:

MemberTypeDescription
build AdsApp.AdCustomizerItemOperation Builds the ad customizer data item.
withAttributeValue AdsApp.AdCustomizerItemBuilder Sets the value of the named attribute of the ad customizer item.
withAttributeValues AdsApp.AdCustomizerItemBuilder Sets the values of the ad customizer item's attributes.
withEndDate AdsApp.AdCustomizerItemBuilder Sets the ad customizer item's end date from either an object containing year, month, and day fields, or an 8-digit string in YYYYMMDD format.
withMobilePreferred AdsApp.AdCustomizerItemBuilder Sets the ad customizer item's device preference to mobile or clears it.
withSchedules AdsApp.AdCustomizerItemBuilder Sets the ad customizer item scheduling.
withStartDate AdsApp.AdCustomizerItemBuilder Sets the ad customizer item's start date from either an object containing year, month, and day fields, or an 8-digit string in YYYYMMDD format.
withTargetAdGroup AdsApp.AdCustomizerItemBuilder Sets the target ad group and campaign of the new ad customizer item.
withTargetCampaign AdsApp.AdCustomizerItemBuilder Sets the target campaign of the new ad customizer item.
withTargetKeyword AdsApp.AdCustomizerItemBuilder Sets the target keyword of the new ad customizer item.

build()

Builds the ad customizer data item. Returns an AdCustomizerItemOperation that corresponds to the creation of the AdCustomizerItem.

Return values:

TypeDescription
AdsApp.AdCustomizerItemOperation The AdCustomizerItemOperation.

withAttributeValue(name, value)

Sets the value of the named attribute of the ad customizer item. The value must be consistent with the type of the attribute. See AdCustomizerItem.setAttributeValue for more information on the expected values for all attribute types. As an example, an attribute of type text expects a string as the value, while an attribute of type date expects a string in YYYYMMDD HHMMSS format.

An error will be thrown if the item's source has no attribute of the given name.

At least one attribute is required to have a value in order to create the ad customizer item. For instance,

var adCustomizerItemOperation = adCustomizerItemBuilder
  .withAttributeValue("lowCost", "$0.99")
  .withTargetCampaign("Campaign")
  .build();
will create an item with lowCost = "$0.99" and target the campaign named Campaign, while
var adCustomizerItemOperation = adCustomizerItemBuilder
  .withTargetCampaign("Campaign")
  .build();
or
var adCustomizerItemOperation = adCustomizerItemBuilder
  .withAttributeValue("lowCost", null)
  .withTargetCampaign("Campaign")
  .build();
will result in an error. The value must be consistent with the type of the attribute:
Type Expected Value Format Example
text String "leather shoes"
number Number (Integer) 42
price String "$4.20"
date String in YYYYMMDD HHMMSS format "20130505 110000". Invalid dates such as "20130005 110000" will result in an error (there is no month 0).

Arguments:

NameTypeDescription
name String The name of the attribute to set a value for.
value Object The new value of the named attribute.

Return values:

TypeDescription
AdsApp.AdCustomizerItemBuilder An AdCustomizerItemBuilder with the new attribute value.

withAttributeValues(attributeValues)

Sets the values of the ad customizer item's attributes. Expects an object containing the name-value pairs of the attribute values to set. For instance, adCustomizerItemBuilder.withAttributeValues({numLeft: 5, lowCost: "$0.99"}) sets the attribute numLeft to have the value 5, and lowCost to have value "$0.99".

At least one attribute is required to have a value in order to create the ad customizer item. For instance,

var adCustomizerItemOperation = adCustomizerItemBuilder
  .withAttributeValues({lowCost: "$0.99", numLeft: 5})
  .withTargetCampaign("Campaign")
  .build();
will create an item with lowCost "$0.99", numLeft 5, and target campaign "Campaign", while
var adCustomizerItemOperation = adCustomizerItemBuilder
  .withTargetCampaign("Campaign")
  .build();
or
var adCustomizerItemOperation = adCustomizerItemBuilder
  .withAttributeValues({lowCost: null, numLeft: null})
  .withTargetCampaign("Campaign")
  .build();
will result in an error.

Arguments:

NameTypeDescription
attributeValues Object An object of the attribute values' names and values.

Return values:

TypeDescription
AdsApp.AdCustomizerItemBuilder An AdCustomizerItemBuilder with the new attribute values.

withEndDate(date)

Sets the ad customizer item's end date from either an object containing year, month, and day fields, or an 8-digit string in YYYYMMDD format. This field is optional.

For instance, adCustomizerItemBuilder.withEndDate("20130503"); is equivalent to adCustomizerItemBuilder.withEndDate({year: 2013, month: 5, day: 3});.

The change will fail and report an error if:

  • the given date is invalid (e.g., {year: 2013, month: 5, day: 55}),
  • the start date now comes after the end date, or
  • it's a date in the past

Arguments:

NameTypeDescription
date Object The new ad customizer item end date.

Return values:

TypeDescription
AdsApp.AdCustomizerItemBuilder A ad customizer item builder with the specified end date.

withMobilePreferred(isMobilePreferred)

Sets the ad customizer item's device preference to mobile or clears it. This field is optional and defaults to false.

Arguments:

NameTypeDescription
isMobilePreferred boolean Whether or not this ad customizer item should be mobile preferred. If true is passed in, device preference will be set to mobile. If false is passed in, device preference will be set to none.

Return values:

TypeDescription
AdsApp.AdCustomizerItemBuilder A ad customizer item builder with the specified mobile preference.

withSchedules(schedules)

Sets the ad customizer item scheduling. Scheduling of a ad customizer item allows you to control the days of week and times of day during which the ad customizer item will show alongside your ads.

Passing in an empty array clears the scheduling field, causing the ad customizer item to run at all times.

The following example sets the ad customizer item to run on Mondays and Tuesday from 8:00 to 11:00.

 var mondayMorning = {
   dayOfWeek: "MONDAY",
   startHour: 8,
   startMinute: 0,
   endHour: 11,
   endMinute: 0
 };
 var tuesdayMorning = {
   dayOfWeek: "TUESDAY",
   startHour: 8,
   startMinute: 0,
   endHour: 11,
   endMinute: 0
 };

adCustomizerItemBuilder.withSchedules([mondayMorning, tuesdayMorning]);

Arguments:

NameTypeDescription
schedules AdsApp.ExtensionSchedule[] The new ad customizer item schedules.

Return values:

TypeDescription
AdsApp.AdCustomizerItemBuilder A ad customizer item builder with the specified schedules.

withStartDate(date)

Sets the ad customizer item's start date from either an object containing year, month, and day fields, or an 8-digit string in YYYYMMDD format. This field is optional.

For instance, adCustomizerItemBuilder.withStartDate("20130503"); is equivalent to adCustomizerItemBuilder.withStartDate({year: 2013, month: 5, day: 3});.

The change will fail and report an error if:

  • the given date is invalid (e.g., {year: 2013, month: 5, day: 55}),
  • the given date is after the ad customizer item's end date,

Arguments:

NameTypeDescription
date Object The new ad customizer item start date.

Return values:

TypeDescription
AdsApp.AdCustomizerItemBuilder A ad customizer item builder with the specified start date.

withTargetAdGroup(campaignName, adGroupName)

Sets the target ad group and campaign of the new ad customizer item. This will fail if there were any previous calls to withTargetCampaign("previous campaign"). For instance,
adCustomizerItemBuilder
  .withTargetCampaign("Other campaign")
  .withTargetAdGroup("Campaign", "Ad group");
will fail, while
adCustomizerItemBuilder
  .withTargetAdGroup("Campaign", "Old ad group")
  .withTargetAdGroup("Campaign", "Ad group");
will result in an ad customizer item builder with target campaign "Campaign" and target ad group "Ad group".

Arguments:

NameTypeDescription
campaignName String The name of the campaign that the target ad group belongs to.
adGroupName String The name of the ad group to target.

Return values:

TypeDescription
AdsApp.AdCustomizerItemBuilder An AdCustomizerItemBuilder with the target keyword.

withTargetCampaign(campaignName)

Sets the target campaign of the new ad customizer item. This will fail if there were any previous calls to withTargetAdGroup("previous ad group", "campaign"). For instance,
adCustomizerItemBuilder
  .withTargetAdGroup("Campaign", "Ad group")
  .withTargetCampaign("Other campaign");
will fail, while
adCustomizerItemBuilder
  .withTargetCampaign("Old campaign");
  .withTargetCampaign("Campaign");
will result in an ad customizer item builder with target campaign "Campaign" and no target ad group.

Arguments:

NameTypeDescription
campaignName String The name of the campaign to target.

Return values:

TypeDescription
AdsApp.AdCustomizerItemBuilder An AdCustomizerItemBuilder with the target campaign.

withTargetKeyword(keyword)

Sets the target keyword of the new ad customizer item. The keyword includes its match type. For instance, adCustomizerItemBuilder.withTargetKeyword("[shoes]"); will target exact matches to "shoes". Setting the target keyword to one that does not yet exist in your account will not cause an error, but will prevent the ad customizer item from being used to populate ads (until you create the keyword in your account).

Arguments:

NameTypeDescription
keyword String The keyword for the ad customizer item to target.

Return values:

TypeDescription
AdsApp.AdCustomizerItemBuilder An AdCustomizerItemBuilder with the target keyword.