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 will be an existing campaign, and is
the basis against which you will compare the other arm. The other arm is called
a treatment arm, and in these arms you will be able to make some changes to
the campaign before beginning the experiment.
The ExperimentArm also contains the traffic_split setting. This lets you
specify what percentage of traffic will be 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 restriction to traffic split, 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="campaignId">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 campaignId, 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, campaignId)
},
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, campaign_id, experiment):
operations = []
campaign_service = client.get_service("CampaignService")
# The "control" arm references an already-existing campaign.
exa = client.get_type("ExperimentArm")
exa.control = True
exa.campaigns = campaign_service.campaign_path(customer_id, campaign_id)
exa.trial = experiment
exa.name = "control arm"
exa.traffic_split = 40
operations.append(exa)
# The non-"control" arm, also called a "treatment" arm, will automatically
# generate draft campaigns that you can modify before starting the
# experiment.
exa = client.get_type("ExperimentArm")
exa.control = False
exa.trial = experiment
exa.name = "experiment arm"
exa.traffic_split = 60
operations.append(exa)
try:
experiment_arm_service = client.get_service("ExperimentArmService")
response = experiment_arm_service.mutate_experiment_arms(
customer_id, operations
)
except GoogleAdsException as ex:
print(
f'Request with ID "{ex.request_id}" failed with status '
f'"{ex.error.code().name}" and includes the following errors:'
)
for error in ex.failure.errors:
print(f'\tError with message "{error.message}".')
if error.location:
for field_path_element in error.location.field_path_elements:
print(f"\t\tOn field: {field_path_element.field_name}")
sys.exit(1)
# 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, 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, 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 may be specified.
Treatment arms
Once you've created the experiment arms, the treatment arm (that is, the arm
where control is set to false) will automatically populate 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):
# 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
results = 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 = 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 will not be affected. Once you schedule the experiment, these changes will be 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, you will need to include the
include_drafts=true parameter in the
query.
At least one change must be made to the in design campaign before you will be able to schedule the experiment.