blogccasion

APIlity 1.1.0 released

Thomas Steiner headshot

By Thomas Steiner. Written on . Work

Dear APIlity usersGoogle AdWords logo

APIlity 1.1.0 is finally ready. This is a major release, an upgrade is recommanded to all APIlity users.
Please check out the complete ChangeLog.
This release primarily introduces CPM-based bidding. This comes along with a new class Criterion.php for be it KeywordCriteria or be it WebsiteCriteria. However, the already existing Keyword objects are still fully supported. This is the promised "best out of both worlds" feature. In spite of all, the new release hopefully is completely compatible to the older versions.
The object hierarchy has been extended to reflect the new features:
APIlity object hierarchy
Therefore the class organigram has been slightly changed:
APIlity object hierarchy
The most important new features:
  1. New CPM-based bidding feature
  2. AdGroup object extended
    AdGroups now have an additional maxCpm attribute. This influences
    respectively introduces the following functions:
    • addAdGroup() (calling parameters canged)
    • getMaxCpm()
    • setMaxCpm()
    • getAllCriteria()

  3. Campaigns can have CampaignNegativeWebsiteCriteria and
    CampaignNegativeKeywordCriteria
  4. New Report download function. The Report class now offers two new functions:
    • downloadXmlReport()
    • downloadCsvReport()
    This allows (re-)downloading of already existing reports.

This version took a relatively long time to complete. There are several reasons for this:
  • Hidden dependencies for example in AdGroup.php, Report.php and even Campaign.php. New functions where needed for AdGroups as the introduction of Criteria included an extension of the AdGroup objects by a MaxCPM attribute. There were three possibilities to handle this:
    1. have WebsiteCriterion AdGroups and KeywordCriterion AdGroups (logic, but complex as another sub-class level would be required)
    2. modify the maxCpc attribute to represent a unique maxCost attribute (logic as the idea of maximum cost remains, but not downwards compatible)
    3. simply add a maxCpm attribute (not 100% logic as only one of the two maxXxx values can be set, but downwards compatible)
    I decided to choose option three as it is simple, compatible and requires no adaptions to already existing scripts.
  • With the 'best out of both worlds' feature I want to enable clients to get the most out of the API, including the 'old' Keyword functions. However, when the Keyword Service gets deactivated, the Keyword functions can be simply removed.
  • The question of the Criterion structure was to decide
    1. either to model the native API structure (Keyword and Website are both subclasses of Criterion)
    2. or to create a new Website object
    Personally I would have decided to introduce a new Website object, but for consistency reasons I kept to the native API structure.

There remains a small logic weak point in the native API structure: Campaigns have the CampaignNegativeKeywords attribute but at the same time support the CampaignNegativeWebsiteCriteria pseudo-attribute (in APIlity only).
  1. either the CampaignNegativeKeywords attribute should be removed from the Campaign object and Campaign negative items should be managed completely in the Criterion service (IMHO not so logic)
  2. or there should be added a CampaignNegativeWebsites attribute to the Campaign object (very logic, requires deeper changes however).

Images from google.com/apis/adwords and google-apility.sourceforge.net