We just announced two new ValueTrack parameters on the Inside AdWords blog. ValueTrack is a feature that helps you pass dynamic AdWords ad click information in your Destination URL. The new {matchtype} parameter provides you with the matchtype of the keyword for search ads (“b” for broad, “p” for phrase, and “e” for exact). The new {network} parameter gives you information about where the ad appeared (“g” for Google search, “s” for search partners, and “d” for display partners).
To learn more about how to implement all 13 ValueTrack parameters, visit the AdWords Help Center.
-- Jason Shafton, Product Marketing Manager
Introducing two new ValueTrack parameters
Tuesday, October 19, 2010
AdWords Downtime: October 16, 10am-2pm PDT
Thursday, October 14, 2010
We'll be performing routine system maintenance on Saturday, October 16 from approximately 10:00am to 2:00pm PDT. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.
Best,
- Eric Koleda, AdWords API Team
Discover v201008 - ServicedAccountService
Tuesday, October 12, 2010
The ability to retrieve a list of client accounts and their details is useful when you’re managing a large number of accounts using the AdWords API. This was previously possible only with AccountService in the legacy v13 version of the AdWords API. The v201008 version introduces the ServicedAccountService, which brings similar functionality to the new AdWords API. This blog post discusses the differences between the old AccountService and the new ServicedAccountService.
Retrieving client account hierarchy
In v13, you could retrieve the list of client accounts linked to an MCC using the getClientAccounts or getClientAccountInfos methods of AccountService. In the v201008 version of the AdWords API, you can use the get method of ServicedAccountService to get the same results. The following code shows the service in action.
// Get the ServicedAccountService.
ServicedAccountService servicedAccountService =
(ServicedAccountService) user.GetService(AdWordsService.v201008.
ServicedAccountService);
ServicedAccountSelector selector = new ServicedAccountSelector();
try {
ServicedAccountGraph graph = servicedAccountService.get(selector);
if (graph != null && graph.accounts != null) {
// Display the accounts.
Console.WriteLine("There are {0} customers under this account" +
" hierarchy.", graph.accounts.Length);
for (int i = 0; i < graph.accounts.Length; i++) {
Console.WriteLine("{0}) Customer id: {1}\nLogin email: {2}\n" +
"Company name: {3}\nIsMCC: {4}\n", i + 1,
graph.accounts[i].customerId, graph.accounts[i].login,
graph.accounts[i].companyName,
graph.accounts[i].canManageClients);
}
}
} catch (Exception ex) {
Console.WriteLine("Failed to retrieve accounts. Exception says \"{0}\"",
ex.Message);
}
ServicedAccountService also allows you to retrieve links that exist between the accounts. To retrieve the links, set the enablePaging field of ServicedAccountSelector to false. The following code shows how to retrieve account links:
selector.enablePaging = false;
selector.serviceTypes = new ServiceType[] { ServiceType.UI_AND_API,
ServiceType.API_ONLY };
...
...
if (graph != null && graph.accounts != null) {
// Display the accounts.
...
...
// Display the links.
foreach (Link link in graph.links) {
Console.WriteLine("There is a {0} link of type {1} from" +
"{2:###-###-####} to {3:###-###-####}", link.typeOfLink,
link.serviceType, link.managerId.id, link.clientId.id);
}
}
An important difference between AccountService.getClientAccounts and ServicedAccountService.get is that getClientAccounts returns only the immediate child accounts, whereas ServicedAccountService.get() returns all of the accounts in the hierarchy. This was harder to do in v13 as you first had to call getClientAccountInfos to find out whether or not a child account is a manager, and then recursively call getClientAccounts to navigate the entire account hierarchy.
To retrieve only the immediate child accounts of your MCC to mimic the behavior of v13’s getClientAccounts method, you can select the relevant accounts as follows:
private Account[] GetClientAccountsForMCC(ServicedAccountGraph graph,
long mccId) {
List retval = new List();
foreach (Link link in graph.links) {
if (link.managerId.id == mccId) {
foreach (Account account in graph.accounts) {
if (account.customerId == link.clientId.id) {
retval.Add(account);
}
}
}
}
return retval.ToArray();
}
Retrieving and updating account information
In v13, you can retrieve and update some fields of a client account using getAccountInfo and updateAccountInfo. This functionality isn’t yet available in v201008, but will be available in a future version of the AdWords API.
Retrieving MCC alerts
In v13, you could retrieve the MCC alerts about your child accounts using getMccAlerts. This functionality is now available through AlertService, another new service introduced in v201008. We will write more about AlertService in a future post.
Please check out this service and share your feedback with us on the forum.
-- Anash P. Oommen, AdWords API Team
More features added to version v201008
Wednesday, September 29, 2010
Last week, we announced version v201008 of the AdWords API. Today, we’re releasing more new features as part of this version that we think you’ll be excited to start using.
Here’s what we’ve added:
- Remarketing: Reach customers who have shown an interest in your product or service by visiting your site, and show them relevant ads across the Google Display Network. Note that with this release, you can create new remarketing lists only by generating new remarketing tags. We’ll add support for creating lists with existing remarketing and conversion tags in the next version of the API. Learn more about remarketing
- My Client Center (MCC) features: Retrieve your MCC account hierarchy with the new ServicedAccountService
- AlertService: Retrieve alerts for the AdWords accounts under your MCC account
- Change History (beta): Use the new CustomerSyncService beta to get a list of entities that have changed over a specific period of time
Please check out these new features and as always, share your feedback on the developer forum.
Posted by Jason Shafton, Product Marketing Manager
Discover v201008: ExperimentService
Tuesday, September 28, 2010
Access to manage AdWords Campaign Experiments (ACE) has been introduced through the ExperimentService as part of the v201008 version of the AdWords API. Now you are able to configure split test experiments for a campaign through the API. A split test experiment lets you more precisely measure the impact of changes to keywords, bids, ad groups, and placements before you apply them to all auctions. This reduces guesswork and lowers the potential risk. For common usage scenarios and more details, check out this blog post and the AdWords Help Center.
Lets get hands on with the code and see how to use ACE via the AdWords API. The following code snippets are available as part of the Perl client library.
Creating your experiment
You start by defining your experiment, which includes creating the experiment, attaching it to a campaign, setting its start time, end time, and percentage split. You then send an add operation through a service mutate call.
# Create experiment.
my $experiment = Google::Ads::AdWords::v201008::Experiment->new({
campaignId => $campaign_id,
name => "Interplanetary Experiment #" . POSIX::strftime("%s", localtime),
queryPercentage => 10,
startDateTime => POSIX::strftime("%Y%m%d %H%M%S", localtime)
});
# Create operation.
my $experiment_operation =
Google::Ads::AdWords::v201008::ExperimentOperation->new({
operator => "ADD",
operand => $experiment
});
# Add experiment.
my $result = $client->ExperimentService()->mutate({
operations => [$experiment_operation]
});
# Valuable for ValueTrack usage
my $experiment_id = $experiments->get_entries()->[0]->get_id();
my $control_id = $experiments->get_entries()->[0]->get_controlId();
In the last few lines of code, experiment id and control id are extracted from the just-created experiment. These values are important for use with the ValueTrack tag used for campaign tracking and analytics since they uniquely identify which split each click is coming from. For details on using the ValueTrack tag with ACE please consult the AdWords Help Center.
Defining your experimental changes
Now lets apply some bid changes to an existing ad group and assign it to both the experimental and the control splits by using the flag named
experimentDeltaStatus. Applying changes to other parts of your campaign are very similar to the following example, refer to the AdGroupExperimentData and the BiddableAdGroupCriterionExperimentData objects in documentation for more information about the experimental changes that can be applied to ad groups and criteria respectively. It is also worth to mention that new ad groups and new criteria can be added to your campaign experiment executing add operations and setting the experimentData to your new objects. You can also check a variety of experiment examples which we included in client libraries.# Set ad group for the experiment.
my $ad_group = Google::Ads::AdWords::v201008::AdGroup->new({
id => $ad_group_id
});
# Create experiment bid multiplier rule that will modify ad group bid for the
# experiment.
my $bid_multiplier =
Google::Ads::AdWords::v201008::ManualCPCAdGroupExperimentBidMultipliers->
new({
maxCpcMultiplier => Google::Ads::AdWords::v201008::BidMultiplier->
new({
multiplier => 1.5
})
});
# Set experiment data to the ad group.
my $experiment_data =
Google::Ads::AdWords::v201008::AdGroupExperimentData->new({
experimentId => $experiment_id,
experimentDeltaStatus => "MODIFIED",
experimentBidMultipliers => $bid_multiplier
});
$ad_group->set_experimentData($experiment_data);
# Create operation.
my $operation = Google::Ads::AdWords::v201008::AdGroupOperation->new({
operand => $ad_group,
operator => "SET"
});
# Update ad group.
$experiments = $client->AdGroupService()->mutate({
operations => [$operation]
});
Deciding to promote or discard your experiment
After you’ve assessed the performance impact of the experimental changes, you can promote or delete the experiment. The following example shows you how to promote your experiment, effectively applying all experimental changes to 100% of your campaign traffic.
# Set experiment's status to PROMOTED.
my $experiment = Google::Ads::AdWords::v201008::Experiment->new({
id => $experiment_id,
status => "PROMOTED"
});
# Create operation.
my $experiment_operation =
Google::Ads::AdWords::v201008::ExperimentOperation->new({
operator => "SET",
operand => $experiment
});
# Update experiment.
my $result = $client->ExperimentService()->mutate({
operations => [$experiment_operation]
});
Promoting an experiment applies all changes in the experimental split to your campaign. All control only elements become paused. Everything else running in both control and experiment splits continues running as normal.
If you don’t like the performance impact you see with the experiment, you can delete it by sending a mutate operation with the experiment status set as DELETED. Deleting an experiment will effectively discard any changes and additions assigned to the experimental split.
Like other products in beta, ACE has some core features still undergoing active development. Reporting is one area that’s getting special attention. Currently, getting performance data segmented by experiment and control splits is not supported through the AdWords API. Until it’s available, you can pull click and conversion data for each split from a tracking system using ValueTrack tags, as described above. Alternatively, experiments can be implemented so that every ad group is either control only or experiment only. You can then aggregate results for each campaign split using each ad group’s
experimentDeltaStatus and check for statistically significant differences. A final interim solution is for users to log into the AdWords UI to check segmented performance stats.If you have any questions about how to use this service we’ll be happy to address them on the forum. Have fun experimenting.
Best,
- David Torres, AdWords API Team
New codes and content in the documentation
Thursday, September 23, 2010
We’ve been hard at work updating the existing documentation and adding new resources. Here are some of the recent changes:
- The overview and sandbox documentation have been updated to reflect changes in the newer versions of the AdWords API.
- The geotargeting codes section have been updated to include the latest information. Province and city codes are now available for all supported countries.
- New code lists for mobile carriers and mobile platforms have been added.
- A listing of the available report fields for each type report have been added. This can act as a supplement to the information provided by the ReportDefinitionService.getReportFields() method.
- The forum has been directly integrated into the documentation for easy access to the knowledge of the AdWords API community.
(View larger image)
We’re always looking for new ways to improve our documentation, so if you have any ideas, let us know on the forum.
Best,
- Eric Koleda, AdWords API Team
Announcing Four AdWords API workshops
Friday, September 17, 2010
Join the AdWords API engineering team for a day of hacking on the latest features. Events will be held in the following cities:
- London, September 28th
- Hamburg, September 30th
- San Francisco, October 7th
- New York, October 12th
- The new CustomerSyncService (Change History)
- AdWords Campaign Experiments
- The new TrafficEstimatorService
- The completely rewritten (forthcoming) Java Client Library
- Migrating from v13 to v2010 reports
- New Ad Extensions and Product Ads
Seats are limited. For more information and to register, visit: https://sites.google.com/site/awapiworkshops/
-- Aaron Karp, AdWords API Team
