AdsApp.​Experiment

AI-generated Key Takeaways

• Google Ads Experiments allow you to test changes in a draft campaign alongside your original (base) campaign.

• Experiments run according to a defined schedule and traffic split, letting you compare performance.

• You can manage experiments, including starting, finishing, applying changes back to the base campaign, or graduating the experiment campaign.

• Experiments have different states like CREATING, ACTIVE, APPLYING, APPLIED, REMOVED, UNABLE_TO_CREATE, UNABLE_TO_APPLY, GRADUATED, and FINISHED reflecting their progress.

• Through various methods, you can access and control experiment details such as name, ID, associated campaigns, goals, status, traffic split, and schedule.

Represents a Google Ads experiment. Experiments are used to run the changes made in a draft campaign side by side with the base campaign.

Methods:

Member	Type	Description
finish()	void	Finishes the experiment.
getBaseCampaign()	AdsApp.Campaign	Returns the base campaign to which this experiment belongs.
getDraft()	AdsApp.Draft	Returns the draft from which this experiment is running.
getEndDate()	AdsApp.GoogleAdsDate	Returns the experiment's end date, or null if there is no end date.
getEntityType()	String	Returns the type of this entity as a String, in this case, "Experiment".
getExperimentCampaign()	AdsApp.Campaign	Returns the experiment campaign associated with this experiment.
getGoals()	AdsApp.ExperimentGoal[]	Returns the goals associated with this experiment.
getId()	String	Returns the ID of the experiment.
getName()	String	Returns the name of the experiment.
getResourceName()	String	Returns the resource name of the experiment.
getStartDate()	AdsApp.GoogleAdsDate	Returns the experiment's start date.
getStatus()	String	Returns the status of the experiment.
getSuffix()	String	Returns the suffix attached to experiment campaigns names created in the experiment.
getTrafficSplitPercent()	int	Returns the traffic split percent (percent of traffic directed to ads from the experiment campaign) of this experiment.
getType()	String	Returns the type of the experiment.
graduate(budget)	void	Graduates the experiment, establishing the experiment campaign as an active, full-fledged campaign immediately.
remove()	void	Removes the experiment, thereby removing its associated experiment campaign, but not removing the associated base campaign.
setEndDate(date)	void	Sets the experiment's end date from either an object containing year, month, and day fields, or an 8-digit string in YYYYMMDD format.
setName(name)	void	Sets the name of the experiment.
setStartDate(date)	void	Sets the experiment's start date from either an object containing year, month, and day fields, or an 8-digit string in YYYYMMDD format.
startApplying()	void	Starts applying the experiment's changes back to the base campaign.
startScheduling()	void	Schedules the experiment according to the start date set.

finish()

Finishes the experiment. A finished experiment cannot be restarted, but it can be applied, graduated, or removed.

Note: Experiments scheduled in the future cannot be finished.

Returns nothing.

getBaseCampaign()

Returns the base campaign to which this experiment belongs.

Return values:

Type	Description
AdsApp.Campaign	The base campaign to which this experiment belongs.

getDraft()

Returns the draft from which this experiment is running.

Return values:

Type	Description
AdsApp.Draft	The draft from which this experiment is running.

getEndDate()

Returns the experiment's end date, or null if there is no end date.

For instance, if an experiment ended on May 3, 2013, this would return the following object: {year: 2013, month: 5, day: 3}.

Return values:

Type	Description
AdsApp.GoogleAdsDate	The experiment's end date, or null if there's no end date.

getEntityType()

Returns the type of this entity as a String, in this case, "Experiment".

Return values:

Type	Description
String	Type of this entity: "Experiment".

getExperimentCampaign()

Returns the experiment campaign associated with this experiment.

Return values:

Type	Description
AdsApp.Campaign	The experiment campaign associated with this experiment.

getGoals()

Returns the goals associated with this experiment.

Return values:

Type	Description
AdsApp.ExperimentGoal[]	A list of goals associated with this experiment.

getId()

Returns the ID of the experiment.

Return values:

Type	Description
String	The ID of the experiment.

getName()

Returns the name of the experiment.

Return values:

Type	Description
String	Name of the experiment.

getResourceName()

Returns the resource name of the experiment.

Return values:

Type	Description
String	The resource name of the experiment.

getStartDate()

Returns the experiment's start date.

For instance, if an experiment started on May 3, 2013, this would return the following object: {year: 2013, month: 5, day: 3}.

Return values:

Type	Description
AdsApp.GoogleAdsDate	The experiment's start date.

getStatus()

Returns the status of the experiment. Possible values: CREATING, ACTIVE, APPLYING, APPLIED, REMOVED, UNABLE_TO_CREATE, UNABLE_TO_APPLY, GRADUATED, FINISHED.

Return values:

Type	Description
String	The status of the experiment.

getSuffix()

Returns the suffix attached to experiment campaigns names created in the experiment.

Return values:

Type	Description
String	The suffix attached to experiment campaign names.

getTrafficSplitPercent()

Returns the traffic split percent (percent of traffic directed to ads from the experiment campaign) of this experiment.

Return values:

Type	Description
int	The traffic split percent (percent of traffic directed to ads from the experiment campaign) of this experiment.

getType()

Returns the type of the experiment.

Return values:

Type	Description
String	The type of the experiment.

graduate(budget)

Graduates the experiment, establishing the experiment campaign as an active, full-fledged campaign immediately. Requires a new Budget to be set.

Returns nothing.

Arguments:

Name	Type	Description
budget	AdsApp.Budget	The budget for the new full-fledged campaign.

remove()

Removes the experiment, thereby removing its associated experiment campaign, but not removing the associated base campaign.

Returns nothing.

setEndDate(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.

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

The change will fail and report an error if:

• the given date is invalid (for example: {year: 2013, 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.

Returns nothing.

Arguments:

Name	Type	Description
date	Object	The new experiment end date.

setName(name)

Sets the name of the experiment.

Returns nothing.

Arguments:

Name	Type	Description
name	String	The new name for the experiment.

setStartDate(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.

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

The change will fail and report an error if:

• the experiment has already started,
• the given date is invalid (for example: {year: 2013, 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 1 year into the future from the current date.
• it's a date after the latest allowed end date of December 30, 2037.

Returns nothing.

Arguments:

Name	Type	Description
date	Object	The new experiment end date.

startApplying()

Starts applying the experiment's changes back to the base campaign. Does not wait for completion. View this experiment in the All experiments tab of the UI to see if its changes are finished being applied.

Note: Only system-managed experiments can be applied.

Returns nothing.

startScheduling()

Schedules the experiment according to the start date set. Materializes the virtual in_design campaigns to experiment campaigns. There should be some changes made to the in_design campaigns before the experiment can be scheduled. Does not wait for completion. View this experiment in the All experiments tab of the UI to see if the experiment is successfully scheduled.

Note: Only system-managed experiments can be scheduled.

Returns nothing.