Integration Docs

Introduction

The typical use case for this type of feed is that an eCommerce customer could have new products arrive and Finch would insert new product related keywords for optimization. However, the feed is not specific to products. It uses general keywords so your feed could include authors, category titles, brands, etc... The goal of the keyword feed is not to replace your existing, high-impression keywords. Rather to expose your inventory and build out long-tail keywords in your account.

How does it work?

Finch will consume the feed and look for changes in the file. New keywords not found in any campaign will be added to a new "feeder" campaign. For keywords that already exist in a campaign, if the feed contains one or more complete ad copies for the keyword, the keyword's ad group is updated with the new ad copy from the feed and its existing ads are paused. If Ad Params (price, quantity, lead time, etc... See Below) are used, then changes to the ad params in the feed for existing keywords will also be updated. If desired, a modified feed with just keywords and ad params is supported. The ability to pause ad groups is also supported.

The "feeder" campaign will share budget with the existing Finch campaign, and will start running as soon as it is created. Finch will use the default maximum CPC from the base campaign as a starting point for these new keywords, and will begin optimizing the bids for the keywords in the "feeder" campaign right from the start.

If you use Magento, Finch has a solution that will work with very little configuration. Please email This e-mail address is being protected from spambots. You need JavaScript enabled to view it. for additional details

Integration

Feed Format

Finch requires a valid XML file to be sent with the following XML structure. Remember that some entities (<, >, ", ', &) are not valid in XML and must be changed (to &lt;, &gt;, &quot;, &apos;, &amp;)

You are responsible for the ad copy and making sure that it does not exceed the maximum amount of characters.

Example 1:


 
  tight cargo pants
  Buy Tight Cargo Pants Now 
  Free Shipping for Orders $50+! 
  See How Much You Could Save 
  We have been selling only the highest quality goods for over 35 years. 
  Easily compare pants side-by-side in just a few seconds. 
  CargoPants
  http://www.example.com/tight-cargo-pants
  Source 1
 
 
  short cargo pants
  Buy Short Cargo Pants Now 
  Multiple Styles to Choose From 
  See How Much You Could Save
  We have been selling only the highest quality goods for over 35 years. 
  Easily compare pants side-by-side in just a few seconds. 
  http://www.example.com/short-cargo-pants
  Source 2
 
 
  long cargo pants
  yes
 

Field Descriptions

  • keyword: The keyword that you want to insert. Finch will create broad match modified, exact, and phrase match keywords, so you don't need to worry about that. In most locations, keywords are limited to 10 words with a maximum of 80 characters. Google doesn't allow search operators (+, $, %, -, #, .., ", *) to be included in keywords.
  • headline1: The title (or headline) 1 of the expanded text ad. 30 Characters Maximum, depending on language.
  • headline2: The title (or headline) 2 of the expanded text ad. 30 Characters Maximum, depending on language.
  • headline3: The optional title (or headline) 3 of the expanded text ad. 30 Characters Maximum, depending on language. Google only.
  • desc1: The description of the expanded text ad. 90 Characters Maximum on Google, 80 on other ad platforms, depending on language and country. Note, Finch still supports "desc" for this item, however you should update to "desc1" at your next convenience.
  • desc2: The optional second description of the expanded text ad. 90 Characters Maximum, depending on language and country. Google only.
  • final-url: The Final URL that this ad will click through to.
  • path1 and path2 (optional): The optional display URL paths of the expanded text ad. 15 Characters maximum, depending on language.
  • paused (optional): If set to yes, the ad groups containing that keyword will be paused. If not specified, or set to no, ad groups containing the keyword will be created or re-activated.
  • label (optional): The label(s) that you wish to be set to the ad group associated with the keyword. See below for more details on labels.

Ad Quality

The ads you use in the keyword feed will be sent directly to Google or Bing. Poor ad quality will directly impact your click through rate. Finch does not review or modify ads based on content or quality - however, Finch may reject your feed based on ad quality.

Finch recommends a couple of things:

  1. Involve both your creative and development team while creating and reviewing the content of the ads.
  2. Use AdWord's Keyword Insertion feature to display what the User searched as part of the ad copy - versus the keyword that triggered the ad.
  3. Create category specific ads and assign them to all the keywords in a product category.

Support for multiple ads per keyword

Ad Groups make it possible to have multiple ads per group. With Finch, each keyword is its own ad group and the Finch keyword feed allows multiple ads per keyword. The keywords in the keyword tag must be identical. Any existing ads for this keyword will be paused. Only the ads included in the feed will be active. Changes to the feed will result in changes to the ads. If you change the ads through Google or Bing, then they will be overwritten by the feed.

Example 2:


 
  tight cargo pants
  Buy Tight Cargo Pants Now 
  Free Shipping for Orders $50+! 
  See How Much You Could Save
  We have been selling only the highest quality goods for over 35 years. 
  Easily compare pants side-by-side in just a few seconds. 
  CargoPants
  <final-url>http://www.example.com/tight-cargo-pants</final-url>
 
 
  tight cargo pants
  Tight Cargo Pants On Sale 
  Multiple Styles to Choose From 
  See How Much You Could Save
  We have been the fashion trend setters worldwide for over 35 years. 
  Easily compare pants side-by-side in just a few seconds. 
  <final-url>http://www.example.com/tight-cargo-pants</final-url>
 

Support for Ad Params

Finch supports the use of Ad Params. Ad Params allow you to include numerical variables in the text lines of your ads. Google AdWords allows up to 2 of these, while Bing Ads allows up to 3. These could be price, quantity, shipping price, estimated arrival time, etc... If the params aren't provided, then the default text (shown after the params) are used, e.g. 50 in the case of {param1:50}. The ad text with the default text must be below the character limit for the given field. Only numerical chars or currency symbols are allowed in the params, but any string is allowed in the default text.

In the example below, the price of $49.99 would be included in the ad's headline 2, and 20 would be substituted in the description. If the params change in the XML feed, then these will be updated as soon as that feed is processed.

Example 3:


 
  tight cargo pants
  Buy Tight Cargo Pants Now 
  Pants start at {param1: a good price} 
  See How Much You Could Save
  Over {param2:2} tight cargo pants in stock. 
  Easily compare pants side-by-side in just a few seconds. 
  <final-url>http://www.example.com/tight-cargo-pants</final-url>
  $49.99
  20
 

You can also send a file that only contains the keywords and ad params. This can be used to update the ad params for existing keywords in the base campaign, as well as keywords that you have added through the feed.

Example 4:


 
  tight cargo pants
  $49.99
  20
  500
 

Support for Labels

Finch supports the use of Google's Labels for AdWords campaign groups (Bing Ads does not currently support labels). Labels allow you to tag objects within your AdWords campaigns and then do reporting on them. Finch places the labels you specify on the ad group containing the keyword. By default, Finch will only add a label to the ad group if the keyword does not exist before the feed is uploaded. Finch supports 3 modes on the label:

  • ADD_IF_KEYWORD_IS_NEW: This is the default. If no mode is specified then this setting is used. The label will only be placed on the ad group if the keyword is new. This is the mode that should be used when you are trying to track the performance of new keywords added via the keyword feed by particular channels.
  • ADD: This will add the label to both new and pre-existing ad groups if it does not exist on the ad group already.
  • REMOVE: this will remove the label from the ad group

Multiple labels can be sent per keyword. In the example below, the Source 1 label would only be added if the keyword is new whereas the Brand X label would be added regardless if the keyword was new or not. The On Sale label would be removed.

Example 5:


 
  tight cargo pants
  Buy Tight Cargo Pants Now 
  Free Shipping for Orders $50+! 
  See How Much You Could Save
  We have been selling only the highest quality goods for over 35 years. 
  Easily compare pants side-by-side in just a few seconds. 
  CargoPants
  <final-url>http://www.example.com/tight-cargo-pants</final-url>
  
  
  
 

You can also send a file that only contains the keywords and labels. This can be used to update the labels for existing keywords in the base campaign, as well as keywords that you have added through the feed.

Example 6:


 
  tight cargo pants
  
  
  
 

Support for Pausing and Re-Enabling

Finch supports pausing and re-enabling ad groups for your keywords through the feed. A typical use case for this is to handle pausing ad groups when the corresponding product is out of stock, and re-enabling them when the product is back in stock. The XML field paused is not required for any item in the feed. If it is not included (or is included and has the value no), then the item in the feed is considered active, and the corresponding ad groups are created (or changed to be active, if necessary). If the field is included and the value is yes, then the ad groups (one of each match type) containing that keyword will be paused; in these cases, no other information (headline1, desc, etc.) is necessary for the keyword, and if sent, will be ignored.

Sending the Feed to Finch

Step 1: Set up permissions

Contact your Finch representative and let them know what user(s) on your Finch account should have access to upload these keyword files. Once they have let you know that the permissions for those user(s) have been set up, you will see a new menu item ("Import Files") once you log into Finch at https://admin.finch.com as a user with these permissions.

Step 2: Create and test your file

Once you get a test file created in the specified XML format, it's time to upload it to Finch for verification. Log into your Finch account as a user who has been given permissions from Step 1. Click on the "Import Files -> Import New File" menu item. Select the campaign that you would like to insert the keywords into, choose the appropriate file from your computer to test, and submit the file. Our system will validate the file soon after it is uploaded. You can alternatively upload your test file(s) by writing code to submit it as described in Step 3.

You can click on the "Import Files -> Imported Files" menu item to see all files that you have uploaded. By clicking on the "Details" link in the right-most column, you can see details about what was found during validation of that file, including statistics such as the number of new keywords in the file and number of keywords that will have updated ad params, as well as any errors and warnings found. If the settings ("Import Files -> Settings") for your campaign require you to review the files before they go live, then even if the file did not contain any errors, if you decide that you don't want its changes to take effect (perhaps it was a test file with dummy data, or maybe you noticed problems with the way the ad copy appeared even though the system did not detect errors), you can easily do this. When looking at the details of that file, you can click on the "File Approval" tab and click the "Reject File" button, which will prevent the file from being processed any further and keep any of its changes from going live. If any errors are found during system validation, the file will also not be processed any further, and none of its changes will take effect.

As long as your settings for the target campaign require you to review files before they go live, you can upload as many test files as you need and reject them so they do not make any changes at Finch or Google. Be aware, though, that if you change your settings so the campaign no longer requires you to review files before they go live, then once you upload a file, if it passes system validation without errors, its changes will take effect without further input on your part.

NOTE that there is a limit of only one "active" file per campaign, where an "active" file indicates a file that might still be processed -- in other words, a file that has not failed validation, been rejected during your or Finch's manual review, or been fully processed (its changes having gone live). So, once you upload a test file for a campaign, before you can upload another file for that campaign, you will need to either approve the file and allow it to be processed, or you will need to reject it on the "File Approval" tab. Note also that there is a 50 megabyte limit on the size of the file. If the file might come anywhere close to that limit, please compress it using either "zip" or "gzip" before sending it to or scheduling it with Finch.

Step 3. Providing the Feed to Finch

After the feed has been built, Finch expects a new copy of the feed daily. This can be done one of two ways:

  • POSTing the Feed to Finch - This is Finch's preferred method for security reasons.
  • Scheduling the Feed for Download by Finch - This is the simplest method, but requires the feed to be publicly available.

Select one of the following options for more details:

Contact Info

If you have any questions about the feed or how to submit it, please contact Jason Lowry at This e-mail address is being protected from spambots. You need JavaScript enabled to view it. or 'lowrykun' on Skype.