Discover v201003: Using Ad Sitelinks

Thursday, September 09, 2010


Introduction
Ad Sitelinks is a feature for search-based ads that allows you to extend the value of your existing AdWords ads by providing additional links to specific, relevant content deep within your website. Rather than sending all users to the same landing page, Sitelinks can provide up to 4 additional links for the user to choose from, as shown below.

(View larger image)

By providing users with more options, you can create richer, more relevant ads that improve the value of your brand terms and other targeted keywords. You can learn more about Sitelinks in the AdWords Help Center.

Using Ad Sitelinks in AdWords API v201003
Sitelinks is supported starting with the v201003 version of the AdWords API. Sitelinks is implemented as campaign ad extensions, and can be managed using the CampaignAdExtensionService. Keep in mind that each campaign can have only one CampaignAdExtension containing a SiteLinkExtension. This means that prior to adding Sitelinks to your campaign, you should check if the campaign already has one, and remove it if does. The C# code snippet below shows how to retrieve the campaign ad extension containing active Sitelinks for a given campaign.

private long? GetActiveSitelinkExtension(long campaignId) {
 long? siteLinkExtensionId = null;

 // Get the campaign ad extension containing sitelinks.
 CampaignAdExtensionSelector selector = new CampaignAdExtensionSelector();
 selector.campaignIds = new long[] { campaignId };
 selector.statuses = new CampaignAdExtensionStatus[] {
CampaignAdExtensionStatus.ACTIVE };

 CampaignAdExtensionPage page = campaignExtensionService.get(selector);
 if (page != null && page.entries != null) {
   foreach (CampaignAdExtension extension in page.entries) {
      if (extension.adExtension is SitelinksExtension) {
         siteLinkExtensionId = extension.adExtension.id;
         break;
      }
   }
 }
 return siteLinkExtensionId;
}

If GetActiveSitelinkExtension returns null, then you can remove the existing SitelinkExtension as shown below.

private SitelinksExtension RemoveActiveSitelinkExtension(
   long campaignId, long siteLinkExtensionId) {
 CampaignAdExtension campaignAdExtension = new CampaignAdExtension();
 campaignAdExtension.campaignId = campaignId;
 campaignAdExtension.adExtension = new AdExtension();
 campaignAdExtension.adExtension.id = siteLinkExtensionId;

 CampaignAdExtensionOperation operation = new CampaignAdExtensionOperation();
 operation.@operator = Operator.REMOVE;
 operation.operand = campaignAdExtension;
 CampaignAdExtensionReturnValue retVal =
     campaignExtensionService.mutate(new CampaignAdExtensionOperation[] {
         operation });
 if (retVal != null && retVal.value != null && retVal.value.Length > 0 &&
     retVal.value[0].adExtension is SitelinksExtension) {
   return (SitelinksExtension) retVal.value[0].adExtension;
 } else {
   return null;
 }
}

You can now add new siteLinks as shown below.

private SitelinksExtension AddSitelinks(long campaignId, Sitelink[]
   siteLinks) {
 SitelinksExtension siteLinkExtension = new SitelinksExtension();
 siteLinkExtension.sitelinks = siteLinks;

 CampaignAdExtension campaignAdExtension = new CampaignAdExtension();
 campaignAdExtension.adExtension = siteLinkExtension;
 campaignAdExtension.campaignId = campaignId;

 CampaignAdExtensionOperation operation = new CampaignAdExtensionOperation();
 operation.@operator = Operator.ADD;
 operation.operand = campaignAdExtension;

 CampaignAdExtensionReturnValue retVal =
     campaignExtensionService.mutate(new CampaignAdExtensionOperation[] {
         operation });
 if (retVal != null && retVal.value != null && retVal.value.Length > 0) {
   return retVal.value[0].adExtension as SitelinksExtension;
 } else {
   return null;
 }
}

The following snippet puts it all together.

Sitelink siteLink1 = new Sitelink();
siteLink1.displayText = "Birthday Flowers";
siteLink1.destinationUrl = "http://www.flowers.com/birthday";

Sitelink siteLink2 = new Sitelink();
siteLink2.displayText = "Deal of the day";
siteLink2.destinationUrl = "http://www.flowers.com/deals/today";

long? linkId = GetActiveSitelinkExtension(campaignId);
if (linkId != 1) {   
 RemoveActiveSitelinkExtension(campaignId, linkId);
}
AddSitelinks(campaignId, new Sitelink[] { siteLink1, siteLink2});

As always, the latest API unit costs for adding, removing or or retrieving Sitelinks is available in the AdWords API rate sheet under the CampaignAdExtensionService.

We've included support for Sitelinks in each of our client libraries to help you get started, so please try it out and share your feedback with us on the forum.

-- Anash P. Oommen, AdWords API Team