AdsApp.​Experiment

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:

MemberTypeDescription
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 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 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 void Sets the name of the experiment.
setStartDate 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.

Returns nothing.

getBaseCampaign()

Returns the base campaign to which this experiment belongs.

Return values:

TypeDescription
AdsApp.Campaign The base campaign to which this experiment belongs.

getDraft()

Returns the draft from which this experiment is running.

Return values:

TypeDescription
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:

TypeDescription
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:

TypeDescription
String Type of this entity: "Experiment".

getExperimentCampaign()

Returns the experiment campaign associated with this experiment.

Return values:

TypeDescription
AdsApp.Campaign The experiment campaign associated with this experiment.

getGoals()

Returns the goals associated with this experiment.

Return values:

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

getId()

Returns the ID of the experiment.

Return values:

TypeDescription
String The ID of the experiment.

getName()

Returns the name of the experiment.

Return values:

TypeDescription
String Name of the experiment.

getResourceName()

Returns the resource name of the experiment.

Return values:

TypeDescription
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:

TypeDescription
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:

TypeDescription
String The status of the experiment.

getSuffix()

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

Return values:

TypeDescription
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:

TypeDescription
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:

TypeDescription
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:

NameTypeDescription
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:

NameTypeDescription
date Object The new experiment end date.

setName(name)

Sets the name of the experiment.

Returns nothing.

Arguments:

NameTypeDescription
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:

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

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.

Returns nothing.