AdsApp.​ExperimentBuilder

Builder for Experiment objects.

Example usage:

// Create an experiment builder.
var experimentBuilder = AdsApp.newExperimentBuilder();

// Create the experiment. Note that startBuilding() returns nothing.
var experiment = experimentBuilder
  .withName("Sample Experiment")                            // required
  .withCampaign(campaign)                                   // required
  .withType('SEARCH_CUSTOM')                                // required
  .withTrafficSplitPercent(50)                              // required
  .withSuffix('- test')                                     // required
  .withStartDate('202304015')                               // required
  .withEndDate('202309018')                                 // required
  .withGoals([{metric: 'CLICKS', direction: 'INCREASE'}])   // required
  .build();
 

Methods:

Member	Type	Description
startBuilding	void
build	AdsApp.Experiment	Creates the experiment according to the configuration provided to the builder.
withCampaign	AdsApp.ExperimentBuilder	Sets the base campaign for the experiment.
withEndDate	AdsApp.ExperimentBuilder	Sets the experiment's end date from either an object containing year, month, and day fields, or an 8-digit string in YYYYMMDD format.
withGoals	AdsApp.ExperimentBuilder	Sets the goals for the experiment.
withName	AdsApp.ExperimentBuilder	Sets the name of the new experiment to the specified value.
withStartDate	AdsApp.ExperimentBuilder	Sets the experiment's start date from either an object containing year, month, and day fields, or an 8-digit string in YYYYMMDD format.
withSuffix	AdsApp.ExperimentBuilder	Sets the suffix for the experiment campaign name in the experiment
withTrafficSplitPercent	AdsApp.ExperimentBuilder	Sets the traffic split percent (percent of traffic directed to ads from the experiment campaign) of the new experiment to the specified value.
withTrafficSplitType	AdsApp.ExperimentBuilder
withType	AdsApp.ExperimentBuilder	Sets the type of the experiment.

startBuilding()

Starts creating an Experiment. Returns nothing, unlike calls to Builder.build(). Navigate to the All experiments tab of the UI to track the new experiment's creation.

Returns nothing.

build()

Creates the experiment according to the configuration provided to the builder.

Return values:

Type	Description
AdsApp.Experiment

withCampaign(campaign)

Sets the base campaign for the experiment.

Arguments:

Name	Type	Description
campaign	AdsApp.Campaign	Base campaign for the experiment.

Return values:

Type	Description
AdsApp.ExperimentBuilder	Experiment builder with the specified campaign as base campaign.

withEndDate(date)

Sets the experiment'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 and will default to the end date of the base campaign if not specified.

For instance, experimentBuilder.withEndDate("20180503"); is equivalent to experimentBuilder.withEndDate({year: 2018, month: 5, day: 3});.

The change will fail and report an error if:

• the given date is invalid (for example: {year: 2018, month: 5, day: 55}),
• the given date is after the base campaign's end date,
• it's a date in the past, or
• it's a date after the latest allowed end date of December 30, 2037.

Arguments:

Name	Type	Description
date	Object	The new experiment end date.

Return values:

Type	Description
AdsApp.ExperimentBuilder	Experiment builder with the specified end date.

withGoals(goals)

Sets the goals for the experiment.

Arguments:

Name	Type	Description
goals	AdsApp.ExperimentGoal[]	List of goals for the experiment.

Return values:

Type	Description
AdsApp.ExperimentBuilder	Experiment builder with the specified goals.

withName(name)

Sets the name of the new experiment to the specified value. Required before building.

Arguments:

Name	Type	Description
name	String	Experiment name.

Return values:

Type	Description
AdsApp.ExperimentBuilder	Experiment builder with the specified name.

withStartDate(date)

Sets the experiment'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 and will default to the start date of the base campaign if not specified.

For instance, experimentBuilder.withStartDate("20180503"); is equivalent to experimentBuilder.withStartDate({year: 2018, month: 5, day: 3});.

The change will fail and report an error if:

• the given date is invalid (for example: {year: 2018, month: 5, day: 55}),
• the given date is after the experiment's end date,
• the given date is after the base campaign's end date,
• it's a date in the past, or
• it's a date after the latest allowed end date of December 30, 2037.

Arguments:

Name	Type	Description
date	Object	Experiment start date.

Return values:

Type	Description
AdsApp.ExperimentBuilder	Experiment builder with the specified start date.

withSuffix(suffix)

Sets the suffix for the experiment campaign name in the experiment

Arguments:

Name	Type	Description
suffix	String	string to be set as the suffix in the experiment campaign name.

Return values:

Type	Description
AdsApp.ExperimentBuilder	Experiment builder with the specified suffix to be used for experiment campaign name.

withTrafficSplitPercent(trafficSplitPercent)

Sets the traffic split percent (percent of traffic directed to ads from the experiment campaign) of the new experiment to the specified value. Must be an integer between 0 and 100, not inclusive. Required before building.

Arguments:

Name	Type	Description
trafficSplitPercent	int	Experiment traffic split percent.

Return values:

Type	Description
AdsApp.ExperimentBuilder	Experiment builder with the specified traffic split percent.

withTrafficSplitType(trafficSplitType)

Sets the traffic split type (cookie-based or search-based) of the new experiment. Only supported on Search campaign experiments, but also required for Search campaign experiments.

Arguments:

Name	Type	Description
trafficSplitType	String	Search campaign experiment traffic split type.

Return values:

Type	Description
AdsApp.ExperimentBuilder	Experiment builder with the specified traffic split type.

withType(type)

Sets the type of the experiment. Should be one of SEARCH_CUSTOM or DISPLAY_CUSTOM depending on the type of campaign added.

Arguments:

Name	Type	Description
type	String	String representing the type of the experiment.

Return values:

Type	Description
AdsApp.ExperimentBuilder	Experiment builder with the specified type.