Experiments Code Example

This example demonstrates how to create experiment campaigns from a base campaign.

using System;
using System.Collections.Generic;
using System.Linq;
using System.ServiceModel;
using System.Threading.Tasks;
using Microsoft.BingAds.V13.CampaignManagement;
using Microsoft.BingAds;

namespace BingAdsExamplesLibrary.V13
{
    /// <summary>
    /// How to create experiment campaigns from a base campaign.
    /// </summary>
    public class Experiments : ExampleBase
    {
        public override string Description
        {
            get { return "Experiments | Campaign Management V13"; }
        }

        public async override Task RunAsync(AuthorizationData authorizationData)
        {
            try
            {
                ApiEnvironment environment = ((OAuthDesktopMobileAuthCodeGrant)authorizationData.Authentication).Environment;

                CampaignManagementExampleHelper CampaignManagementExampleHelper = new CampaignManagementExampleHelper(
                    OutputStatusMessageDefault: this.OutputStatusMessage);
                CampaignManagementExampleHelper.CampaignManagementService = new ServiceClient<ICampaignManagementService>(
                    authorizationData: authorizationData,
                    environment: environment);

                // Choose a base campaign for the experiment.

                OutputStatusMessage("-----\nGetCampaignsByAccountId:");
                GetCampaignsByAccountIdResponse getCampaignsByAccountIdResponse = await CampaignManagementExampleHelper.GetCampaignsByAccountIdAsync(
                    accountId: authorizationData.AccountId,
                    campaignType: CampaignType.Search,
                    returnAdditionalFields: CampaignAdditionalField.AdScheduleUseSearcherTimeZone);
                var campaigns = getCampaignsByAccountIdResponse.Campaigns;
                OutputStatusMessage("Campaigns:");
                CampaignManagementExampleHelper.OutputArrayOfCampaign(campaigns);

                // The base campaign cannot be an experiment of another base campaign
                // i.e., the campaign's ExperimentId must be nil. 
                // Likewise the base campaign cannot use a shared budget
                // i.e., the campaign's BudgetId must be nil. 

                var baseCampaign = campaigns.FirstOrDefault(
                    campaign => campaign.ExperimentId == null && campaign.BudgetId == null);

                if (baseCampaign == null)
                {
                    OutputStatusMessage("You do not have any campaigns that are eligible for experiments.");
                    return;
                }

                // Create the experiment

                var experiments = new [] {
                    new Experiment
                    {
                        BaseCampaignId = baseCampaign.Id,
                        EndDate = new Date
                        {
                            Month = 12,
                            Day = 31,
                            Year = DateTime.UtcNow.Year
                        },
                        ExperimentCampaignId = null,
                        ExperimentStatus = "Active",
                        ExperimentType = null,
                        Id = null,
                        Name = baseCampaign.Name + "-Experiment",
                        StartDate = new Date
                        {
                            Month = DateTime.UtcNow.Month,
                            Day = DateTime.UtcNow.Day,
                            Year = DateTime.UtcNow.Year
                        },
                        TrafficSplitPercent = 50
                    }
                };

                OutputStatusMessage("-----\nAddExperiments:");
                AddExperimentsResponse addExperimentsResponse = await CampaignManagementExampleHelper.AddExperimentsAsync(
                        experiments: experiments);
                long?[] experimentIds = addExperimentsResponse.ExperimentIds.ToArray();
                BatchError[] experimentErrors = addExperimentsResponse.PartialErrors.ToArray();
                OutputStatusMessage("ExperimentIds:");
                CampaignManagementExampleHelper.OutputArrayOfLong(experimentIds);
                OutputStatusMessage("PartialErrors:");
                CampaignManagementExampleHelper.OutputArrayOfBatchError(experimentErrors);

                OutputStatusMessage("-----\nGetExperimentsByIds:");
                GetExperimentsByIdsResponse getExperimentsByIdsResponse = await CampaignManagementExampleHelper.GetExperimentsByIdsAsync(
                        experimentIds: new[] { (long)experimentIds[0] },
                        pageInfo: null);
                OutputStatusMessage("Experiments:");
                CampaignManagementExampleHelper.OutputArrayOfExperiment(getExperimentsByIdsResponse.Experiments);

                var experiment = getExperimentsByIdsResponse.Experiments?.ToList()[0];

                // If the experiment is in a Graduated state, then the former experiment campaign 
                // is now an independent campaign that must be deleted separately. 
                // Otherwise if you delete the base campaign (not shown here), 
                // the experiment campaign and experiment itself are also deleted.

                OutputStatusMessage("-----\nDeleteCampaigns:");
                await CampaignManagementExampleHelper.DeleteCampaignsAsync(
                    accountId: authorizationData.AccountId,
                    campaignIds: new[] { (long)experiment.ExperimentCampaignId });
                OutputStatusMessage(string.Format("Deleted Experiment Campaign Id {0} with Status '{1}'",
                    experiment.ExperimentCampaignId,
                    experiment.ExperimentStatus));

                OutputStatusMessage("-----\nDeleteExperiments:");
                await CampaignManagementExampleHelper.DeleteExperimentsAsync(
                    experimentIds: new[] { (long)experiment.Id });
                OutputStatusMessage(string.Format("Deleted Experiment Id {0}", experiment.Id));        
            }
            // Catch authentication exceptions
            catch (OAuthTokenRequestException ex)
            {
                OutputStatusMessage(string.Format("Couldn't get OAuth tokens. Error: {0}. Description: {1}", ex.Details.Error, ex.Details.Description));
            }
            // Catch Campaign Management service exceptions
            catch (FaultException<Microsoft.BingAds.V13.CampaignManagement.AdApiFaultDetail> ex)
            {
                OutputStatusMessage(string.Join("; ", ex.Detail.Errors.Select(error => string.Format("{0}: {1}", error.Code, error.Message))));
            }
            catch (FaultException<Microsoft.BingAds.V13.CampaignManagement.ApiFaultDetail> ex)
            {
                OutputStatusMessage(string.Join("; ", ex.Detail.OperationErrors.Select(error => string.Format("{0}: {1}", error.Code, error.Message))));
                OutputStatusMessage(string.Join("; ", ex.Detail.BatchErrors.Select(error => string.Format("{0}: {1}", error.Code, error.Message))));
            }
            catch (FaultException<Microsoft.BingAds.V13.CampaignManagement.EditorialApiFaultDetail> ex)
            {
                OutputStatusMessage(string.Join("; ", ex.Detail.OperationErrors.Select(error => string.Format("{0}: {1}", error.Code, error.Message))));
                OutputStatusMessage(string.Join("; ", ex.Detail.BatchErrors.Select(error => string.Format("{0}: {1}", error.Code, error.Message))));
            }
            catch (Exception ex)
            {
                OutputStatusMessage(ex.Message);
            }
        }
    }
}

package com.microsoft.bingads.examples.v13;

import java.util.ArrayList;
import java.util.Calendar;

import com.microsoft.bingads.*;
import com.microsoft.bingads.v13.campaignmanagement.*;
import java.util.HashSet;
import java.util.List;
import java.util.stream.*;

public class Experiments extends ExampleBase {
    
    public static void main(java.lang.String[] args) {
     
        try
        {
            authorizationData = getAuthorizationData(); 
             
            CampaignManagementExampleHelper.CampaignManagementService = new ServiceClient<ICampaignManagementService>(
                        authorizationData, 
                        API_ENVIRONMENT,
                        ICampaignManagementService.class);
            
            ArrayList<CampaignType> campaignTypes = new ArrayList<CampaignType>();
            campaignTypes.add(CampaignType.SEARCH);   
            
            // Choose a base campaign for the experiment.
                        
            outputStatusMessage("-----\nGetCampaignsByAccountId:");
            GetCampaignsByAccountIdResponse getCampaignsByAccountIdResponse = CampaignManagementExampleHelper.getCampaignsByAccountId(
                authorizationData.getAccountId(),
                campaignTypes,
                null);
            ArrayOfCampaign campaigns = getCampaignsByAccountIdResponse.getCampaigns();
            outputStatusMessage("Campaigns:");
            CampaignManagementExampleHelper.outputArrayOfCampaign(campaigns);  
            
            // The base campaign cannot be an experiment of another base campaign
            // i.e., the campaign's ExperimentId must be nil. 
            // Likewise the base campaign cannot use a shared budget
            // i.e., the campaign's BudgetId must be nil. 

            Campaign baseCampaign = null;
            if (baseCampaign == null) baseCampaign = campaigns.getCampaigns().stream().filter(
                    campaign -> campaign.getExperimentId() == null && campaign.getBudgetId() == null).findFirst().orElse(null);
            
            if (baseCampaign == null)
            {
                outputStatusMessage("You do not have any campaigns that are eligible for experiments.");
                return;
            }

            // Create the experiment
            
            ArrayOfExperiment experiments = new ArrayOfExperiment();
            Experiment experiment = new Experiment();
            experiment.setBaseCampaignId(baseCampaign.getId());
            Calendar calendar = Calendar.getInstance();
            experiment.setEndDate(new com.microsoft.bingads.v13.campaignmanagement.Date());
            experiment.getEndDate().setDay(31);
            experiment.getEndDate().setMonth(12);
            experiment.getEndDate().setYear(calendar.get(Calendar.YEAR));
            experiment.setExperimentCampaignId(null);
            experiment.setExperimentStatus("Active");
            experiment.setExperimentType(null);
            experiment.setId(null);
            experiment.setName(baseCampaign.getName() + "-Experiment");
            experiment.setStartDate(new com.microsoft.bingads.v13.campaignmanagement.Date());
            experiment.getStartDate().setDay(calendar.get(Calendar.DAY_OF_MONTH));
            experiment.getStartDate().setMonth(calendar.get(Calendar.MONTH) + 1);
            experiment.getStartDate().setYear(calendar.get(Calendar.YEAR));
            experiment.setTrafficSplitPercent(50);
            experiments.getExperiments().add(experiment);

            outputStatusMessage("-----\nAddExperiments:");
            AddExperimentsResponse addExperimentsResponse = CampaignManagementExampleHelper.addExperiments(
                    experiments);
            ArrayOfNullableOflong nullableExperimentIds = addExperimentsResponse.getExperimentIds();
            ArrayOfBatchError experimentErrors = addExperimentsResponse.getPartialErrors();
            outputStatusMessage("ExperimentIds:");
            CampaignManagementExampleHelper.outputArrayOfNullableOflong(nullableExperimentIds);
            outputStatusMessage("PartialErrors:");
            CampaignManagementExampleHelper.outputArrayOfBatchError(experimentErrors);

            outputStatusMessage("-----\nGetExperimentsByIds:");
            ArrayOflong experimentIds = new ArrayOflong();
            experimentIds.getLongs().add(nullableExperimentIds.getLongs().get(0));
            GetExperimentsByIdsResponse getExperimentsByIdsResponse = CampaignManagementExampleHelper.getExperimentsByIds(experimentIds,
                    null);
            experiments = getExperimentsByIdsResponse.getExperiments();
            outputStatusMessage("Experiments:");
            CampaignManagementExampleHelper.outputArrayOfExperiment(experiments);

            experiment = experiments.getExperiments().get(0);

            // If the experiment is in a Graduated state, then the former experiment campaign 
            // is now an independent campaign that must be deleted separately. 
            // Otherwise if you delete the base campaign (not shown here), 
            // the experiment campaign and experiment itself are also deleted.

            outputStatusMessage("-----\nDeleteCampaigns:");
            ArrayOflong campaignIds = new ArrayOflong();
            campaignIds.getLongs().add(experiment.getExperimentCampaignId());
            CampaignManagementExampleHelper.deleteCampaigns(
                    authorizationData.getAccountId(), 
                    campaignIds);
            outputStatusMessage(String.format("Deleted Experiment Campaign Id %s with Status '%s'",
                experiment.getExperimentCampaignId(),
                experiment.getExperimentStatus()));

            outputStatusMessage("-----\nDeleteExperiments:");
            CampaignManagementExampleHelper.deleteExperiments(
                    experimentIds);
            outputStatusMessage(String.format("Deleted Experiment Id %s", experiment.getId()));   
        } 
        catch (Exception ex) {
            String faultXml = ExampleExceptionHelper.getBingAdsExceptionFaultXml(ex, System.out);
            outputStatusMessage(faultXml);
            String message = ExampleExceptionHelper.handleBingAdsSDKException(ex, System.out);
            outputStatusMessage(message);
        }
    }    
 }

<?php

namespace Microsoft\BingAds\Samples\V13;

// For more information about installing and using the Bing Ads PHP SDK, 
// see https://go.microsoft.com/fwlink/?linkid=838593.

require_once __DIR__ . "/../vendor/autoload.php";

include __DIR__ . "/AuthHelper.php";
include __DIR__ . "/AdInsightExampleHelper.php";
include __DIR__ . "/CampaignManagementExampleHelper.php";

use SoapVar;
use SoapFault;
use Exception;

// Specify the Microsoft\BingAds\Auth classes that will be used.
use Microsoft\BingAds\Auth\ServiceClient;
use Microsoft\BingAds\Auth\ServiceClientType;

// Specify the Microsoft\BingAds\Samples classes that will be used.
use Microsoft\BingAds\Samples\V13\AuthHelper;
use Microsoft\BingAds\Samples\V13\CampaignManagementExampleHelper;

// Specify the Microsoft\BingAds\V13\CampaignManagement classes that will be used.
use Microsoft\BingAds\V13\CampaignManagement\CampaignType;
use Microsoft\BingAds\V13\CampaignManagement\Date;
use Microsoft\BingAds\V13\CampaignManagement\Experiment;

try
{
    // Authenticate user credentials and set the account ID for the sample.  
    AuthHelper::Authenticate();

    // Choose a base campaign for the experiment.

    print("-----\r\nGetCampaignsByAccountId:\r\n");
    $getCampaignsByAccountIdResponse = CampaignManagementExampleHelper::GetCampaignsByAccountId(
        $GLOBALS['AuthorizationData']->AccountId,
        AuthHelper::CampaignTypes,
        AuthHelper::CampaignAdditionalFields
    );
    $campaigns = $getCampaignsByAccountIdResponse->Campaigns;
    print("Campaigns:\r\n");
    CampaignManagementExampleHelper::OutputArrayOfCampaign($campaigns);

    // The base campaign cannot be an experiment of another base campaign
    // i.e., the campaign's ExperimentId must be nil. 
    // Likewise the base campaign cannot use a shared budget
    // i.e., the campaign's BudgetId must be nil. 
    
    $baseCampaign = null;
    foreach ($campaigns->Campaign as $campaign) {
        if(((isset($campaign->ExperimentId) && $campaign->ExperimentId == null) || !isset($campaign->ExperimentId))
        && $campaign->BudgetId == null){
            $baseCampaign = $campaign;
            break;
        }
    }

    if($baseCampaign == null){
        print("You do not have any campaigns that are eligible for experiments.");
        return;
    }

    // Create the experiment

    $experiments = array();   
    $experiment = new Experiment();
    $experiment->BaseCampaignId = $baseCampaign->Id;
    date_default_timezone_set('UTC');
    $endDate = new Date();
    $endDate->Day = 31;
    $endDate->Month = 12;
    $endDate->Year = date("Y");
    $experiment->EndDate = $endDate;
    $experiment->ExperimentCampaignId = null;
    $experiment->ExperimentStatus = "Active";
    $experiment->ExperimentType = null;
    $experiment->Id = null;
    $experiment->Name = $baseCampaign->Name . "-Experiment";
    $startDate = new Date();
    $startDate->Day = date("d");
    $startDate->Month = date("m");
    $startDate->Year = date("Y");
    $experiment->StartDate = $startDate;
    $experiment->TrafficSplitPercent = 50;
    $experiments[] = $experiment;
    
    print("-----\r\nAddExperiments:\r\n");
    $addExperimentsResponse = CampaignManagementExampleHelper::AddExperiments(
        $experiments
    );
    $experimentIds = $addExperimentsResponse->ExperimentIds;
    print("ExperimentIds:\r\n");
    CampaignManagementExampleHelper::OutputArrayOfLong($experimentIds);
    print("PartialErrors:\r\n");
    CampaignManagementExampleHelper::OutputArrayOfBatchError($addExperimentsResponse->PartialErrors);

    print("-----\r\nGetExperimentsByIds:\r\n");
    $getExperimentsByIdsResponse = CampaignManagementExampleHelper::GetExperimentsByIds(
        $experimentIds,
        null
    );
    print("Experiments:");
    CampaignManagementExampleHelper::OutputArrayOfExperiment($getExperimentsByIdsResponse->Experiments);

    $experiment = $getExperimentsByIdsResponse->Experiments->Experiment[0];

    // If the experiment is in a Graduated state, then the former experiment campaign 
    // is now an independent campaign that must be deleted separately. 
    // Otherwise if you delete the base campaign (not shown here), 
    // the experiment campaign and experiment itself are also deleted.

    print("-----\r\nDeleteCampaigns:\r\n");
    CampaignManagementExampleHelper::DeleteCampaigns(
        $GLOBALS['AuthorizationData']->AccountId, 
        array($experiment->ExperimentCampaignId)
    );
    printf("Deleted Experiment Campaign Id %s with Status '%s'\r\n",
        $experiment->ExperimentCampaignId,
        $experiment->ExperimentStatus
    );

    print("-----\nDeleteExperiments:\r\n");
    CampaignManagementExampleHelper::DeleteExperiments(
        array($experiment->Id)
    );
    printf("Deleted Experiment Id %s\r\n", $experiment->Id);   
}
catch (SoapFault $e)
{
    printf("-----\r\nFault Code: %s\r\nFault String: %s\r\nFault Detail: \r\n", $e->faultcode, $e->faultstring);
    var_dump($e->detail);
    print "-----\r\nLast SOAP request/response:\r\n";
    print $GLOBALS['Proxy']->GetWsdl() . "\r\n";
    print $GLOBALS['Proxy']->GetService()->__getLastRequest()."\r\n";
    print $GLOBALS['Proxy']->GetService()->__getLastResponse()."\r\n";
}
catch (Exception $e)
{
    // Ignore fault exceptions that we already caught.
    if ($e->getPrevious())
    { ; }
    else
    {
        print $e->getCode()." ".$e->getMessage()."\n\n";
        print $e->getTraceAsString()."\n\n";
    }
}

import uuid
from auth_helper import *
from openapi_client.models.campaign import *


def main(authorization_data):
    try:
        # Get eligible campaigns for experiments
        # Eligible campaigns must not have an experiment ID and must not use a shared budget
        print("Getting eligible campaigns for experiments...")
        
        get_campaigns_request = GetCampaignsByAccountIdRequest(
            account_id=authorization_data.account_id,
            campaign_type=CampaignType.SEARCH
        )
        
        get_campaigns_response = campaign_service.get_campaigns_by_account_id(
            get_campaigns_by_account_id_request=get_campaigns_request
        )
        
        campaigns = get_campaigns_response.Campaigns
        
        # Filter for eligible campaigns (no experiment ID and no budget ID)
        eligible_campaigns = [
            campaign for campaign in campaigns
            if not hasattr(campaign, 'ExperimentId') or campaign.ExperimentId is None
            and not hasattr(campaign, 'BudgetId') or campaign.BudgetId is None
        ]
        
        print(f"Found {len(eligible_campaigns)} eligible campaigns")
        
        if not eligible_campaigns:
            print("No eligible campaigns found. Please create a campaign without a shared budget first.")
            return
        
        # Use the first eligible campaign
        base_campaign = eligible_campaigns[0]
        print(f"Using base campaign: {base_campaign.Name} (ID: {base_campaign.Id})")
        
        # Add an experiment for the base campaign
        print("\nAdding experiment...")
        
        current_date = datetime.now()
        
        experiment = Experiment(
            base_campaign_id=base_campaign.Id,
            name=f"{base_campaign.Name}-Experiment{str(uuid.uuid4())[:8]}",
            traffic_split_percent=50,
            # Required. You must set the status to Active; however, the status will be set 
            # automatically by Microsoft Advertising to Creating, and the next time you retrieve 
            # the experiment its status will be either Active, Creating, CreationFailed, Paused, or Scheduled.
            experiment_status='Active',
            start_date=Date(
                day=current_date.day,
                month=current_date.month,
                year=current_date.year
            ),
            end_date=Date(
                day=31,
                month=12,
                year=current_date.year
            )
        )
        
        add_experiments_request = AddExperimentsRequest(
            experiments=[experiment]
        )
        
        add_experiments_response = campaign_service.add_experiments(
            add_experiments_request=add_experiments_request
        )
        
        experiment_ids = add_experiments_response.ExperimentIds
        print(f"Created Experiment IDs: {experiment_ids}")
        
        if add_experiments_response.PartialErrors:
            print(f"Partial Errors: {add_experiments_response.PartialErrors}")
        else:
            print("Experiment created successfully")
        
        # Get experiments by IDs
        print("\nGetting experiments by IDs...")
        
        get_experiments_request = GetExperimentsByIdsRequest(
            experiment_ids=experiment_ids
        )
        
        get_experiments_response = campaign_service.get_experiments_by_ids(
            get_experiments_by_ids_request=get_experiments_request
        )
        
        experiments = get_experiments_response.Experiments
        print(f"Retrieved {len(experiments)} experiments")
        
        for exp in experiments:
            print(f"  Experiment ID: {exp.Id}")
            print(f"  Name: {exp.Name}")
            print(f"  Status: {exp.ExperimentStatus}")
            print(f"  Base Campaign ID: {exp.BaseCampaignId}")
            if hasattr(exp, 'ExperimentCampaignId') and exp.ExperimentCampaignId:
                print(f"  Experiment Campaign ID: {exp.ExperimentCampaignId}")
            print(f"  Traffic Split: {exp.TrafficSplitPercent}%")
        
        if get_experiments_response.PartialErrors:
            print(f"Partial Errors: {get_experiments_response.PartialErrors}")
        
        # Clean up - delete the experiment
        print("\nDeleting experiment...")
        
        experiment = experiments[0]
        
        # If the experiment has graduated, delete the experiment campaign first
        if hasattr(experiment, 'ExperimentStatus') and experiment.ExperimentStatus == "Graduated":
            if hasattr(experiment, 'ExperimentCampaignId') and experiment.ExperimentCampaignId:
                print(f"Experiment has graduated. Deleting experiment campaign {experiment.ExperimentCampaignId}...")
                delete_campaign_request = DeleteCampaignsRequest(
                    account_id=authorization_data.account_id,
                    campaign_ids=[experiment.ExperimentCampaignId]
                )
                campaign_service.delete_campaigns(
                    delete_campaigns_request=delete_campaign_request
                )
        
        # Delete the experiment
        delete_experiments_request = DeleteExperimentsRequest(
            experiment_ids=[experiment.Id]
        )
        
        delete_experiments_response = campaign_service.delete_experiments(
            delete_experiments_request=delete_experiments_request
        )
        
        if delete_experiments_response.PartialErrors:
            print(f"Partial Errors: {delete_experiments_response.PartialErrors}")
        else:
            print(f"Deleted Experiment ID: {experiment.Id}")
        
    except Exception as ex:
        print(f"Error occurred: {str(ex)}")
        import traceback
        traceback.print_exc()


if __name__ == '__main__':
    print("Loading the web service client...")
    
    authorization_data = AuthorizationData(
        account_id=None,
        customer_id=None,
        developer_token=DEVELOPER_TOKEN,
        authentication=None,
    )
    
    authenticate(authorization_data)
    
    campaign_service = ServiceClient(
        service='CampaignManagementService',
        version=13,
        authorization_data=authorization_data,
        environment=ENVIRONMENT,
    )
    
    main(authorization_data)

See Also

Get Started with the Bing Ads API