Create experiment arms

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 name of each arm must be unique within the Experiment
  • Exactly one arm must have control set to true. All other arms must have it set to false.
  • The traffic_split must 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.