Once you've created an experiment, you need to create multiple experiment arms in order to give the experiment more information about what exactly you're testing.
The ExperimentArm represents one part of the
comparison you're performing for the experiment. All experiments must always
have exactly one control arm. This arm is an existing campaign that forms
the basis against which you compare the other arm.
The other arms are called treatment arms, and in these arms you make changes to the campaign before beginning the experiment.
The ExperimentArm also contains the traffic_split setting. This lets you
specify the percentage of traffic that is directed to each arm of the
experiment. Each arm must specify a traffic split, and the sum of traffic split
values in all arms must add up to 100.
Because of this traffic split restriction, all experiment arms must be created in the same request:
Java
private String createExperimentArms(
GoogleAdsClient googleAdsClient, long customerId, long campaignId, String experiment) {
List<ExperimentArmOperation> operations = new ArrayList<>();
operations.add(
ExperimentArmOperation.newBuilder()
.setCreate(
// The "control" arm references an already-existing campaign.
ExperimentArm.newBuilder()
.setControl(true)
.addCampaigns(ResourceNames.campaign(customerId, campaignId))
.setTrial(experiment)
.setName("control arm")
.setTrafficSplit(40)
.build())
.build());
operations.add(
ExperimentArmOperation.newBuilder()
.setCreate(
// The non-"control" arm, also called a "treatment" arm, will automatically
// generate draft campaigns that you can modify before starting the experiment.
ExperimentArm.newBuilder()
.setControl(false)
.setTrial(experiment)
.setName("experiment arm")
.setTrafficSplit(60)
.build())
.build());
try (ExperimentArmServiceClient experimentArmServiceClient =
googleAdsClient.getLatestVersion().createExperimentArmServiceClient()) {
MutateExperimentArmsResponse response =
experimentArmServiceClient.mutateExperimentArms(Long.toString(customerId), operations);
// Results always return in the order that you specify them in the request. Since we created
// the treatment arm last, it will be the last result. If you don't remember which arm is the
// treatment arm, you can always filter the query in the next section with
// `experiment_arm.control = false`.
String controlArm = response.getResults(0).getResourceName();
String treatmentArm = response.getResults(response.getResultsCount() - 1).getResourceName();
System.out.printf("Created control arm with resource name '%s'%n", controlArm);
System.out.printf("Created treatment arm with resource name '%s'%n", treatmentArm);
return treatmentArm;
}
}
C#
/// <summary>
/// Creates the experiment arms.
/// </summary>
/// <param name="client">The Google Ads client.</param>
/// <param name="customerId">The customer ID for which the call is made.</param>
/// <param name="baseCampaignId">ID of the campaign for which the control arm is
/// created.</param>
/// <param name="experimentResourceName">Resource name of the experiment.</param>
/// <returns>The resource names of the control and treatment arms.</returns>
private static (string, string) CreateExperimentArms(GoogleAdsClient client,
long customerId, long baseCampaignId, string experimentResourceName)
{
// Get the ExperimentArmService.
ExperimentArmServiceClient experimentService = client.GetService(
Services.V11.ExperimentArmService);
// Create the control arm. The control arm references an already-existing campaign.
ExperimentArmOperation controlArmOperation = new ExperimentArmOperation()
{
Create = new ExperimentArm()
{
Control = true,
Campaigns = {
ResourceNames.Campaign(customerId, baseCampaignId)
},
Trial = experimentResourceName,
Name = "Control Arm",
TrafficSplit = 40
}
};
// Create the non-control arm. The non-"control" arm, also called a "treatment" arm,
// will automatically generate draft campaigns that you can modify before starting the
// experiment.
ExperimentArmOperation treatmentArmOperation = new ExperimentArmOperation()
{
Create = new ExperimentArm()
{
Control = false,
Trial = experimentResourceName,
Name = "Experiment Arm",
TrafficSplit = 60
}
};
// Makes the API call.
MutateExperimentArmsResponse response = experimentService.MutateExperimentArms(
customerId.ToString(), new[] { controlArmOperation, treatmentArmOperation });
// Results always return in the order that you specify them in the request.
// Since we created the treatment arm last, it will be the last result. If
// you don't remember which arm is the treatment arm, you can always filter
// the query in the FetchDraftCampaign method with `experiment_arm.control = false`.
string controlArmResourceName = response.Results.First().ResourceName;
string treatmentArmResourceName = response.Results.Last().ResourceName;
Console.WriteLine($"Created control arm with resource name " +
$"'{controlArmResourceName}.");
Console.WriteLine($"Created treatment arm with resource name" +
$" '{treatmentArmResourceName}'.");
return (controlArmResourceName, treatmentArmResourceName);
}
PHP
private static function createExperimentArms(
GoogleAdsClient $googleAdsClient,
int $customerId,
int $campaignId,
string $experimentResourceName
): string {
$operations = [];
$experimentArm1 = new ExperimentArm([
// The "control" arm references an already-existing campaign.
'control' => true,
'campaigns' => [ResourceNames::forCampaign($customerId, $campaignId)],
'trial' => $experimentResourceName,
'name' => 'control arm',
'traffic_split' => 40
]);
$operations[] = new ExperimentArmOperation(['create' => $experimentArm1]);
$experimentArm2 = new ExperimentArm([
// The non-"control" arm, also called a "treatment" arm, will automatically
// generate draft campaigns that you can modify before starting the
// experiment.
'control' => false,
'trial' => $experimentResourceName,
'name' => 'experiment arm',
'traffic_split' => 60
]);
$operations[] = new ExperimentArmOperation(['create' => $experimentArm2]);
// Issues a request to create the experiment arms.
$experimentArmServiceClient = $googleAdsClient->getExperimentArmServiceClient();
$response = $experimentArmServiceClient->mutateExperimentArms($customerId, $operations);
// Results always return in the order that you specify them in the request.
// Since we created the treatment arm last, it will be the last result. If
// you don't remember which arm is the treatment arm, you can always filter
// the query in the next section with `experiment_arm.control = false`.
$controlArmResourceName = $response->getResults()[0]->getResourceName();
$treatmentArmResourceName =
$response->getResults()[count($operations) - 1]->getResourceName();
print "Created control arm with resource name '$controlArmResourceName'" . PHP_EOL;
print "Created treatment arm with resource name '$treatmentArmResourceName'" . PHP_EOL;
return $treatmentArmResourceName;
}
Python
def create_experiment_arms(client, customer_id, base_campaign_id, experiment):
"""Creates a control and treatment experiment arms.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
base_campaign_id: the campaign ID to associate with the control arm of
the experiment.
experiment: the resource name for an experiment.
Returns:
the resource name for the new treatment experiment arm.
"""
operations = []
campaign_service = client.get_service("CampaignService")
# The "control" arm references an already-existing campaign.
operation_1 = client.get_type("ExperimentArmOperation")
exa_1 = operation_1.create
exa_1.control = True
exa_1.campaigns.append(
campaign_service.campaign_path(customer_id, base_campaign_id)
)
exa_1.trial = experiment
exa_1.name = "control arm"
exa_1.traffic_split = 40
operations.append(operation_1)
# The non-"control" arm, also called a "treatment" arm, will automatically
# generate draft campaigns that you can modify before starting the
# experiment.
operation_2 = client.get_type("ExperimentArmOperation")
exa_2 = operation_2.create
exa_2.control = False
exa_2.trial = experiment
exa_2.name = "experiment arm"
exa_2.traffic_split = 60
operations.append(operation_2)
experiment_arm_service = client.get_service("ExperimentArmService")
response = experiment_arm_service.mutate_experiment_arms(
customer_id=customer_id, operations=operations
)
# Results always return in the order that you specify them in the request.
# Since we created the treatment arm last, it will be the last result. If
# you don't remember which arm is the treatment arm, you can always filter
# the query in the next section with `experiment_arm.control = false`.
control_arm = response.results[0].resource_name
treatment_arm = response.results[1].resource_name
print(f"Created control arm with resource name {control_arm}")
print(f"Created treatment arm with resource name {treatment_arm}")
return treatment_arm
Ruby
def create_experiment_arms(client, customer_id, base_campaign_id, experiment)
operations = []
operations << client.operation.create_resource.experiment_arm do |ea|
# The "control" arm references an already-existing campaign.
ea.control = true
ea.campaigns << client.path.campaign(customer_id, base_campaign_id)
ea.trial = experiment
ea.name = 'control arm'
ea.traffic_split = 40
end
operations << client.operation.create_resource.experiment_arm do |ea|
# The non-"control" arm, also called a "treatment" arm, will automatically
# generate draft campaigns that you can modify before starting the
# experiment.
ea.control = false
ea.trial = experiment
ea.name = 'experiment arm'
ea.traffic_split = 60
end
response = client.service.experiment_arm.mutate_experiment_arms(
customer_id: customer_id,
operations: operations,
)
# Results always return in the order that you specify them in the request.
# Since we created the treatment arm last, it will be the last result. If
# you don't remember which arm is the treatment arm, you can always filter
# the query in the next section with `experiment_arm.control = false`.
control_arm = response.results.first.resource_name
treatment_arm = response.results.last.resource_name
puts "Created control arm with resource name #{control_arm}."
puts "Created treatment arm with resource name #{treatment_arm}."
treatment_arm
end
Perl
sub create_experiment_arms {
my ($api_client, $customer_id, $campaign_id, $experiment) = @_;
my $operations = [];
push @$operations,
Google::Ads::GoogleAds::V11::Services::ExperimentArmService::ExperimentArmOperation
->new({
create => Google::Ads::GoogleAds::V11::Resources::ExperimentArm->new({
# The "control" arm references an already-existing campaign.
control => "true",
campaigns => [
Google::Ads::GoogleAds::V11::Utils::ResourceNames::campaign(
$customer_id, $campaign_id
)
],
trial => $experiment,
name => "control arm",
trafficSplit => 40
})});
push @$operations,
Google::Ads::GoogleAds::V11::Services::ExperimentArmService::ExperimentArmOperation
->new({
create => Google::Ads::GoogleAds::V11::Resources::ExperimentArm->new({
# The non-"control" arm, also called a "treatment" arm, will automatically
# generate draft campaigns that you can modify before starting the
# experiment.
control => "false",
trial => $experiment,
name => "experiment arm",
trafficSplit => 60
})});
my $response = $api_client->ExperimentArmService()->mutate({
customerId => $customer_id,
operations => $operations
});
# Results always return in the order that you specify them in the request.
# Since we created the treatment arm last, it will be the last result. If
# you don't remember which arm is the treatment arm, you can always filter
# the query in the next section with `experiment_arm.control = false`.
my $control_arm = $response->{results}[0]{resourceName};
my $treatment_arm = $response->{results}[1]{resourceName};
printf "Created control arm with resource name '%s'.\n", $control_arm;
printf "Created treatment arm with resource name '%s'.\n", $treatment_arm;
return $treatment_arm;
}
A few key points about the example above:
- The
nameof each arm must be unique within theExperiment. - Exactly one arm must have
controlset to true. All other arms must have it set to false. - The
traffic_splitmust add up to 100 across all arms. - Only the control arm specifies
campaigns. Only one campaign can be specified. - The campaigns in the control arm must use non-shared budgets (that is,
budgets where
is_explicitly_sharedis set to false). The budget is then shared with the experiment campaigns in the other arms.
Treatment arms
Once you've created the experiment arms, the treatment arm (that is, the arm
where control is set to false) automatically populates its
in_design_campaigns. You need to fetch that info from
GoogleAdsService to make changes to the
campaign for the treatment arm.
Java
private String fetchDraftCampaign(
GoogleAdsClient googleAdsClient, long customerId, String treatmentArm) {
// The `in_design_campaigns` represent campaign drafts, which you can modify before starting the
// experiment.
String query =
String.format(
"SELECT experiment_arm.in_design_campaigns "
+ "FROM experiment_arm "
+ "WHERE experiment_arm.resource_name = '%s'",
treatmentArm);
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
SearchPagedResponse response =
googleAdsServiceClient.search(Long.toString(customerId), query);
// In design campaigns returns as an array, but for now it can only ever contain a single ID,
// so we just grab the first one.
String draftCampaign =
response.iterateAll().iterator().next().getExperimentArm().getInDesignCampaigns(0);
System.out.printf("Found draft campaign with resource name '%s'%n", draftCampaign);
return draftCampaign;
}
}
C#
/// <summary>
/// Fetches the draft campaign.
/// </summary>
/// <param name="client">The Google Ads client.</param>
/// <param name="customerId">The customer ID for which the call is made.</param>
/// <param name="treatmentArmResourceName">Name of the treatment arm resource.</param>
/// <returns>Resource name of the draft campaign</returns>
private static string FetchDraftCampaign(GoogleAdsClient client, long customerId,
string treatmentArmResourceName)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
Services.V11.GoogleAdsService);
// Creates the query.
// The `in_design_campaigns` represent campaign drafts, which you can modify
// before starting the experiment.
string query = $"SELECT experiment_arm.in_design_campaigns FROM experiment_arm " +
$"WHERE experiment_arm.resource_name = '{treatmentArmResourceName}'";
// Makes the API call.
// In design campaigns returns as an array, but for now it can only ever
// contain a single ID, so we just grab the first one.
string draftCampaignResourceName = googleAdsService.Search(
customerId.ToString(), query).First().ExperimentArm.InDesignCampaigns.First();
Console.WriteLine($"Found draft campaign with resource name " +
$"'{draftCampaignResourceName}'.");
return draftCampaignResourceName;
}
PHP
private static function fetchDraftCampaign(
GoogleAdsClient $googleAdsClient,
int $customerId,
string $treatmentArmResourceName
): string {
// Fetches information about the in design campaigns and prints out its resource
// name. The `in_design_campaigns` represent campaign drafts, which you can modify
// before starting the experiment.
$query = "SELECT experiment_arm.in_design_campaigns FROM experiment_arm"
. " WHERE experiment_arm.resource_name = '$treatmentArmResourceName'";
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search($customerId, $query);
// In design campaigns returns as an array, but for now it can only ever contain a single
// ID, so we just grab the first one.
/** @var GoogleAdsRow $googleAdsRow */
$googleAdsRow = $response->getIterator()->current();
$draftCampaignResourceName = $googleAdsRow->getExperimentArm()->getInDesignCampaigns()[0];
print "Found draft campaign with resource name '$draftCampaignResourceName'" . PHP_EOL;
return $draftCampaignResourceName;
}
Python
def fetch_draft_campaign(client, customer_id, treatment_arm):
"""Retrieves the in-design campaigns for an experiment.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
treatment_arm: the resource name for the treatment arm of an experiment.
Returns:
the resource name for the in-design campaign.
"""
# The `in_design_campaigns` represent campaign drafts, which you can modify
# before starting the experiment.
ga_service = client.get_service("GoogleAdsService")
query = f"""
SELECT
experiment_arm.in_design_campaigns
FROM experiment_arm
WHERE experiment_arm.resource_name = '{treatment_arm}'"""
request = client.get_type("SearchGoogleAdsRequest")
request.customer_id = customer_id
request.query = query
response = ga_service.search(request=request)
# In design campaigns returns as a list, but for now it can only ever
# contain a single ID, so we just grab the first one.
draft_campaign = response.results[0].experiment_arm.in_design_campaigns[0]
print(f"Found draft campaign with resource name {draft_campaign}")
return draft_campaign
Ruby
def fetch_draft_campaign(client, customer_id, treatment_arm)
# The `in_design_campaigns` represent campaign drafts, which you can modify
# before starting the experiment.
query = <<~QUERY
SELECT experiment_arm.in_design_campaigns
FROM experiment_arm
WHERE experiment_arm.resource_name = "#{treatment_arm}"
QUERY
response = client.service.google_ads.search(
customer_id: customer_id,
query: query
)
# In design campaigns returns as an array, but for now it can only ever
# contain a single ID, so we just grab the first one.
draft_campaign = response.first.experiment_arm.in_design_campaigns.first
puts "Found draft campaign with resource name #{draft_campaign}."
draft_campaign
end
Perl
sub fetch_draft_campaign {
my ($api_client, $customer_id, $treatment_arm) = @_;
# The 'in_design_campaigns' represent campaign drafts, which you can modify
# before starting the experiment.
my $query =
"SELECT experiment_arm.in_design_campaigns FROM experiment_arm " .
"WHERE experiment_arm.resource_name = '$treatment_arm'";
my $response = $api_client->GoogleAdsService()->search({
customerId => $customer_id,
query => $query
});
# In design campaigns returns as an array, but for now it can only ever
# contain a single ID, so we just grab the first one.
my $draft_campaign =
$response->{results}[0]->{experimentArm}{inDesignCampaigns}[0];
printf "Found draft campaign with resource name '%s'.\n", $draft_campaign;
return $draft_campaign;
}
You can treat these in-design campaigns as regular campaigns. Make whatever changes you want to test in your experiment to these campaigns; the control campaign won't be affected. Once you schedule the experiment, these changes are materialized into a real campaign that can serve ads.
These in-design campaigns are technically draft campaigns. If you want to
find them in GoogleAdsService, add the include_drafts=true
parameter to the query.
At least one change must be made to the in-design campaign before you can schedule the experiment.