Mandatory Code Changes Required by adCenter API Users in Preparation for URL by Match Type Updates


We’re fast approaching our next milestone in releasing URL by Match Type. In March, we announced the ramped release of URL by Match Type and have been steadily enabling advertisers ever since. Our focus has now turned to our API customers.

With adCenter’s URL by Match Type feature, you will have more control and precision for managing each bidded keyword match type within the same ad group by assigning a unique destination URL. This will enable you to manage each URL and match type more independently to optimize and improve your campaign performance while making cross platform changes with more accuracy and ease. This feature also improves your ability to measure and track keyword performance by match type to more effectively optimize your campaigns.

Timing and Impact

We will be rolling this feature out over many months, and the first wave of customers to be enabled for URL by Match Type will be advertisers with a customer-level market country setting of US, DE, AT, CH.

adCenter API users who have their customer level Market setting set to the U.S., must prepare their account by making updates to their adCenter API code by July 1 to ensure the continued ability to manage campaigns with adCenter API. adCenter API users (or Agencies/SEMs who manage advertisers) who have a customer level market setting of the Germany, Switzerland, and Austria, must update their adCenter API code by June 1.

Timeframe of enablement of customers belonging to other markets (UK, France, India, Canada and Singapore) is forthcoming and we will keep you informed as we update our release plan. (To determine your customer level Market setting, API users can pull this information from the v7 Customer data object or the v8 Customer data object.)

Details on code changes are provided below, but you can also refer to our MSDN documentationwhich contains this same information.

Mandatory adCenter API Code changes required

There are a few code updates API customers will need to make in order to leverage the functionality of URL by Match Type and ensure continued management of their adCenter accounts with adCenter API:

Current Rules

New Rules

The Keyword (KW) data object can have up to four different bids against (ExactMatchBid, PhraseMatchBid, BroadMatchBid, ContentMatchBid). Any match bid value on the KW object that is unused defaults (and is persisted in adCenter) as null.

Note: Although content match is shown as an option, there is no contextual network within EMEA.

Keyword Object will only accept a bid for one of the four match types.

adCenter only allows a single instance of a keyword literal within the same ad group (e.g., you are unable to have two keyword objects that represent the bidded keyword “car”).

Business rule relaxed to allow multiple instances of the keyword in an ad group so long as there is no conflict/existing match type bid on the same keyword in the same ad group.

· Keyword Object and non-zero values:

· Missing Bid: implies inheritance of bid from the ad group

· Setting a bid explicitly to null: implies inheritance of bid from the ad group

· Setting Bid to zero: Equivalent of deleting the match type for the Keyword

· Keyword Object and non-zero values:

· As each Keyword Object instance can only have one match type bid, the remaining match type bids will need to be empty (different from null); Note that empty values will not default bids from the ad group. 

· Setting a bid explicitly to null: inherit the ad group bid for that match type (No change to this behavior)

· Setting a bid to zero: not allowed (to delete a match type; advertisers need to call DeleteKeywords)

Content bids use the URL in the keyword object.

Keyword IDs can be created individually for content.

For Existing Keywords:

All existing Keywords will be converted so that the new “After Enablement” rules for the keyword object are not violated. See image below:

adCenter will determine what new Keyword Match Types to generate based on the number of clicks per match type over the last 30 days. The best performing match type will remain unchanged, and the remaining bidded match types will be moved to new KW instances that will have the same KW string, editorial status, URL and bid. There are some additional caveats API customers should be aware of:

  • If a KW has fewer than 1000 impressions, the KW ID retained will be based on the most restrictive MT. (Exact is the most restrictive with Broad being the least restrictive.)
  • If two MTs are tied for performance, the most restrictive MT remains unchanged and remaining MTs will be represented as new KWs moving forward.
  • Hybrid ad groups (ad groups that surface ads in Search & Content Networks): New KW ids will be created to represent content bids, regardless if the content MT bid is being inherited from the ad group.
  • Content-Only ad groups, exact, phrase, broad match types will get new IDs; existing IDs will always be retained with the content match type.
  • Ad groups will retain the 10,000 keyword object limit. If the limit is exceeded during migration, the migration itself will not fail, however no new KWs can be added until the KW count is under 10K.
  • New KWs will retain the editorial status of the original KW, but quality scores will be re-calculated.
  • To determine the migration status of an account, adCenter is exposing a new service operation called GetAccountMigrationStatuses.

Content Match Types When surfacing ads through the content network, adCenter will match against the Keyword ID that has a Content match type. In the event that a Content match type has not been created (the word “Car” is created for Exact , Phrase and Broad, but not Content), that KW continue to serve in the Content Network, however attribution will be associated with the least restrictive match type (in the order of broad, phrase, exact). It’s important to note that the contextual network is not available within EMEA, so the above information applies to the North American marketplace.

For reporting, all impression and performance data will be reported under “Content” for both delivered and bidded match types.

Reporting After Migration

If you are reporting on match type performance and reporting over a period that spans pre and post enablement, there could be two different keywords IDs with historic performance data that need to be referenced. For example, in the figure below, the March 1 rows represent performance data prior to the migration, and March 2 rows represent data reported after migration. In this example, reporting on the performance of exact match over the two day period would require referencing two different Keyword IDs. Note that if you do not report using the keyword ID column, the match type performance would be aggregated as-expected.

To assist you, adCenter is also releasing two different reporting capabilities:

· KeywordMigration Report (in Reporting v8 only). This report will surface a new report that will show the keyword conversion “mapping” to reflect keywords and their “originating” KW, if any.

· A New column called KeywordMatchTypeID (in the Keyword Performance Report). When selected as a column, the KW performance report will show post-migration keyword IDs (where new KWs were generated) and present a “unified” view of performance data. Using this column, the previous example would look as such:

Suggested Best Practices

· Pre-Enablement

o Clean up ad groups at risk of exceeding the 10,000 keyword limitafter feature enablement. Once this feature is introduced, each match type will count as a separate keyword. All keywords will be retained, but you will not be able to add new keywords to the ad group if the limit is exceeded.

o For any match types you do not wish to have normalized into a new keyword, explicitly save a bid of 0.00 priorto migration; match type bids with null values will be normalized.Eliminate any five-cent bids designed to concede traffic.

- In API version 7 and 8, code for the new service operation GetAccountMigrationStatusesto track account migration status. (Guideline: 15k calls every 4 hours)

· Post-Enablement

o Synchronize campaigns for newly generated KW instancesSupport new URL by MT business logic and accounts for any breaking changes (see table above)

o Code for reporting changes (refer to reporting section)

    • Update destination URLs/tracking codes to each keyword match type if applicable(Guideline: 250k updates an hour, note that existing editorial validations and rules will continue to apply as today)

Reporting Changes

Additional Resources

Comments (2)

  1. Anonymous-EN@Community.MicrosoftAdvertising.com says:

    As I understand it, this change will this affect v7 users as well as v8. This is a huge change for us and I have to say I'm shocked if adCenter goes ahead with this in the middle of a release, breaking existing code, which is really bad practise. July 1st is less than 1.5 months away and that is simply not enough time. We will have to redo a ton of code and in my mind, it's just unacceptable to implement a change like this in the middle of existing releases. It should've been slated for a yet unreleased version, v9 I assume.

    We have a number of other unrelated software projects scheduled for the next 2 months and might have to shut down our adCenter support for a large number of customers on July 1st 🙁

    But let me say that I do welcome the changes. This will be a great improvement to adCenter, however, its place is in a new release. The planned change is painful for us because it touches so many existing components, such as …

    ? adCenter to local storage sync C# code.

    ? Keyword database schema.

    ? UI that presents the keywords to users.

    ? SSIS packages.

    ? Data warehouse schema.

    ? Analysis Services cube.

    ? A number of Paid Search reports.

    ? Making sure new match types are correctly migrated to existing keywords in local storage and data warehouse for millions of keywords.

    On top of the developer changes outlined above, this also has a very large QA testing impact. I really hope you will reconsider the timing of this change.

    Thanks,

    Hans Ravnaas

  2. Anonymous-EN@Community.MicrosoftAdvertising.com says:

    I would really appreciate if someone from adCenter could comment on why such a significant change is necessary for v7 and v8. We customers have built complex systems on top of existing functionality and it's very disruptive and time consuming to now have to update our solution to meet these new and unexpected requirements in such a short time. Please let us know why this was not introducted in v9.

Skip to main content