AdWords scripts support campaign drafts and experiments, which are used to prepare and test changes to Search and Display Network campaigns. A draft is a clone of an existing campaign that does not serve its own ads but can be used to stage changes without modifying the original campaign. The staged changes can then be applied to the base campaign.
If you want to take it a step further, you can turn the draft into an experiment (also known as "trials" in the AdWords API). The experiment campaign runs parallel to the original campaign, showing its ads to a specified percentage of traffic.
Based on the results of the experiment, you can apply the changes to the original campaign, branch the experiment to an independent campaign, or abandon the experiment campaign.
This guide explains the basic workflow for working with drafts and experiments in a script.
Creating a draft
A draft is made from an existing base campaign by using a
and providing a unique name. The base campaign must be a Search, Search with Display
Select, or Display campaign (excluding Mobile App campaign for the Display
Network), and it must not have a shared budget.
var campaign = AdWordsApp.campaigns() .withCondition("Name = 'INSERT_CAMPAIGN_NAME_HERE'") .get() .next(); var draftBuilder = campaign.newDraftBuilder() .withName("INSERT_DRAFT_NAME_HERE") .build(); var draft = draftBuilder.getResult();
draft is uniquely identified by the combination of its base campaign ID
and draft ID. See
for more information.
Provisioning the draft campaign
draft object relates a base campaign and a draft campaign. To stage updates
to the base campaign, you propagate changes through the draft campaign.
A draft campaign, like any other campaign, has methods to get and set its various attributes such as criteria, ad groups, bids, and ads.
var draftCampaign = draft.getDraftCampaign(); draftCampaign.setAdRotationType("CONVERSION_OPTIMIZE"); draftCampaign.createNegativeKeyword("shoes");
Keep in mind that policy checks for ads are done for a draft campaign just as they are for the base campaign. You will not be able to run an experiment from a draft campaign that has policy-violating ads.
Executing the draft
After provisioning the draft campaign, you can do one of the following:
If you don't want to use the changes, you can simply remove the draft. Removing the draft is irreversible, but it can still be viewed under All drafts in the drafts tab of the AdWords UI.
If you decide to keep the changes you made in the draft, you can go ahead and apply them:
This method starts the process of applying the updates to the base campaign, so the draft will appear to have status "Applying..." in the AdWords UI. However, the method will NOT notify you when the process completes.
Although there is little you can do with an applied draft, if you do have a use for it later, we suggest scheduling the script for a future run and checking that its status has become
APPLIED. See our best practices guide for more details.
If you would like to test out your changes first, you can use the draft to create an experiment.
Creating an experiment
experiment is built from a
draft, and is the manager of an experiment
campaign. You create an
experiment with an
and by providing a traffic split percentage and unique name.
The traffic split percentage determines what portion of traffic will be shown ads from the experiment campaign instead of the base campaign. For this reason, each base campaign can have only one running experiment at a time.
var experimentBuilder = draft.newExperimentBuilder(); experimentBuilder.withName("INSERT_EXPERIMENT_NAME_HERE") .withTrafficSplitPercent(50) .startBuilding();
does not return an operation like other
Builder.build() calls. However,
you can see the status of your new experiment's creation by navigating to the
experiments tab of the AdWords UI. The experiment will appear to have status
"Creating...". To interact with the experiment in a script, schedule a run in
the future or wait until the experiment's status becomes "Active" or "Scheduled"
in the AdWords UI. See the best practices
guide for more details.
// Some time in a future run, either manual or scheduled. var experiment = AdWordsApp.experiments() .withCondition("Name = 'INSERT_EXPERIMENT_NAME_HERE'") .get() .next();
Unlike drafts, experiments are uniquely identified by a single ID. See
for more information.
Provisioning the experiment campaign
Similar to a
experiment itself is not a campaign. Rather, it
relates the base campaign, the draft, and the experiment campaign. Fields
of an experiment campaign are modifiable, with the following exceptions:
- start date
- end date
var experimentCampaign = experiment.getExperimentCampaign(); // Will succeed. experimentCampaign.setAdRotationType("ROTATE_FOREVER"); experimentCampaign.createNegativeKeyword("sneakers"); // Will fail. experimentCampaign.setName("INSERT_EXPERIMENT_NAME_HERE");
Changes to the name, start date, and end date can be made to the experiment (referred to as 'Trials' in AdWords API), after which they will propagate to the experiment campaign. Unless specified at creation time, the start date and end date of an experiment will default to those of its base campaign. When updated, the new start or end date must be within the base campaign's.
// Will succeed. experiment.setName("INSERT_EXPERIMENT_NAME_HERE"); // Will succeed if date is acceptable. var date = "20180101"; experiment.setStartDate(date);
After the experiment ends
At your experiment's completion, you have a few options. We recommend letting the experiment completely finish so that it will stop serving ads but you can still interact with it. A "Finished" experiment can still be removed, applied, or graduated, and its campaign's performance stats are still accessible.
experiment.finish(); var stats = experimentCampaign.getStatsFor("INSERT_TIME_PERIOD_HERE");
If you're dissatisfied with the experiment based on the stats, you can remove the experiment, which also removes the experiment campaign. Removing the experiment is irreversible, but it can still be viewed under All experiments in the experiments tab of the AdWords UI.
If you're satisfied with the experiment's results, you have two options:
You can start applying the changes and just as with drafts, you won't be notified when the process completes.
You can establish the experiment campaign as an independent, fully-operating campaign, without affecting the base campaign. This process, known as graduation, completes immediately and requires a new budget to be set.
var budget = AdWordsApp.budgets() .withCondition("BudgetId = 'INSERT_BUDGET_ID_HERE'") .get() .next(); experiment.graduate(budget);
The new campaign can no longer share a budget with the base campaign, which necessitates the new budget. Graduated campaigns are just like normal campaigns in that all their fields are modifiable and that they can serve as a base campaign for more drafts and experiments.
The notion of base entities
The introduction of drafts and experiments to AdWords scripts also introduces
the notion of base entities. Draft and experiment campaigns and the ad groups in
them are distinct from their original base campaigns, which is why
now have methods to access their base campaign and ad group:
getBaseAdGroup(). The methods simply
return the calling entity if called by a base campaign or an ad group in one.
Entities within campaigns and ad groups, such as keywords and ads, also have
been given such methods.
methods allow you to access all the draft campaigns and experiment campaigns,
respectively, that have the calling campaign as their base campaign. In a
CampaignSelector.withCondition() can now
filter on the
CampaignExperimentType column, using one of
EXPERIMENT as the possible values:
// Get all draft campaigns in the account. var allDraftCampaigns = AdWordsApp.campaigns() .withCondition("CampaignExperimentType = DRAFT") .get();
Some actions involving drafts and experiments will succeed when the script is run,
but might fail after the asynchronous call is executed. These methods are
You should wait to check whether these operations succeed. The AdWords UI will
show the statuses "Applied" or "Active" after successful completions of
startBuilding(), respectively. It will show "Unable to apply"
or "Unable to create" upon failure, and let you click to see what errors occurred.
Also, some errors that occur when working with drafts and experiments may not appear when a script is previewed, but only when it is actually run. This would occur, for example, when attempting to make an experiment from a draft that already has one:
Logger.log(draft.hasRunningExperiment()); // Logs true. draft.newExperimentBuilder() .withName("FAULTY_EXPERIMENT") .withTrafficSplitPercent(50) // Succeed in preview mode, .startBuilding(); // but will fail when run.
It's also possible that some methods fail in the preview stage, but succeed after they run; for instance, after creating a draft:
var draftCampaign = draft.getDraftCampaign(); draftCampaign.createNegativeKeyword("shoes"); // Will fail in preview.
This will fail in preview mode as it cannot access the campaign immediately.
For this reason, we remind you to check the logs below your list of scripts after running them, and try running the script if you believe there is no flaw in your script but preview mode has failed.
Be sure to check out the relevant code snippets page for more examples using this feature.