adapi 0.0.9 → 0.1.0

data/README.markdown

@@ -1,6 +1,6 @@
-# Adapi #
+# Adapi [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/lstejskal/adapi)
 
-## Description ##
+## Description
 
 Adapi (ADwords API) is a Ruby library for easy and painless work with Google
 Adwords API. Its users shouldn't bother with SOAP and tangle of XML- and
@@ -21,11 +21,13 @@ come from there, but adapi takes it several steps further:
 Adapi is *still in development* and not nearly done yet! Version 1.0.0 should
 have all planned functionality.
 
-## Installation ##
+Adapi supports the latest version of AdWords API: *v201206*. 
+
+## Installation
 
 `gem install adapi`
 
-### from git repository ###
+### from git repository
 
 ```
 git clone git@github.com:lstejskal/adapi.git
@@ -34,17 +36,17 @@ bundle install
 rake install
 ```
 
-## Configuration ##
+## Configuration
 
 This section explains how to connect to specific AdWords account and client.
 There are several options to choose from:
 
-#### Configuration by adwords_api.yml ####
+#### Configuration by adwords_api.yml
 
 If you already have `google-adwords-api` gem configured and use just one account,
 the same configuration will also work for adapi: `~/adwords_api.yml`
 
-#### Single account set directly in code ####
+#### Single account set directly in code
 
 ```ruby
 Adapi::Config.load_settings(:in_hash => {
@@ -66,7 +68,7 @@ Adapi::Config.load_settings(:in_hash => {
 Adapi::Config.set(:sandbox)
 ```
 
-#### Multiple accounts set directly in code ####
+#### Multiple accounts set directly in code
 
 You can set many AdWords accounts to connect to and switch between while running
 the application. You can even update single values of the settings on-the-fly.
@@ -110,7 +112,7 @@ Adapi::Config.set(:coca_cola, :client_customer_id => '777-666-5555')
 # do some stuff here...
 ```
 
-#### Configuration by `adapi.yml` ####
+#### Configuration by `adapi.yml`
 
 Stored in `~/adapi.yml`. Supports multiple accounts, which are identifed by
 aliases. Example:
@@ -149,7 +151,7 @@ Adapi::Config.set(:sandbox)
 `:default` account available, you have to manually set account alias to
 `Adapi::Config`.
 
-### Authentication workflow ###
+### Authentication workflow
 
 * try to load configuration from `~/adapi.yml`
 * if `~/adapi.yml`doesn't exist, try to load configuration from
@@ -157,16 +159,22 @@ Adapi::Config.set(:sandbox)
 * if there are no configuration files available, set configuration directly to
   `Adapi::Config` (overrides previous settings)
 
-## API Version Support ##
+## API Version Support
+
+Adapi supports the latest version of AdWords API: *v201206*. 
 
-Adapi does not support several AdWords API versions at the same time, only the
-latest version: *v201109_1* at the moment.
+For support of earlier versions of AdWords API, downgrade to earlier 
+versions of adapi: 0.0.9 for *v201109_1*, 0.07 for *v201109*. 
+(You shoudn't need it though, because older versions of AdWords API are 
+eventually shut down.) Latest revision for specific AdWords API version 
+is also marked by a tag.
 
-However, support for the older versions is still available in earlier versions
-of adapi (adapi 0.0.7 for *v201109*). Latest revision for specific AdWords API
-version is marked by a tag.
+Adapi tries to not to bother users with AdWords API low-level specifics as much 
+as possible, if you're upgrading to newer version of AdWords API, please be cautious, 
+check the [release notes](https://developers.google.com/adwords/api/docs/reference/)
+and update your code accordingly. Adapi won't accept obsolete attributes etc. 
 
-## Unsupported AdWords services ##
+## Unsupported AdWords services
 
 Following AdWords services are not supported by adapi at the moment. However,
 they will be implemented (this also serves as TODO list):
@@ -188,18 +196,18 @@ they will be implemented (this also serves as TODO list):
   * MutateJobService
   * BulkMutateJobService
 
-## Examples ##
+## Examples
 
 Examples are available in [examples directory](./master/examples/). For now, they
 are mostly just uninspired rewrites of examples from `google-adwords-api` gem,
 but that's going to change when proper UI to AdWords models will be implemented.
 
-### Getting started ###
+### Getting started
 
 Here are some examples to get you started with adapi. (All this is also
 available in [examples directory](./master/examples/).)
 
-#### Create complete campaign ###
+#### Create complete campaign
 
 Creates a campaign with ad_groups and ad_texts from hash - by single method call.
 
@@ -246,7 +254,7 @@ campaign = Adapi::Campaign.create(
 )
 ```
 
-#### Create campaign step by step ###
+#### Create campaign step by step
 
 Creates a campaign with ad_groups and ad_texts step by step.
 
@@ -295,7 +303,7 @@ new_campaign = Adapi::Campaign.find_complete(campaign.id)
 puts new_campaign.to_hash.inspect
 ```
 
-#### Create campaign criteria ###
+#### Create campaign criteria
 
 Campaign criteria (formerly targets) have been rewritten from the scratch for
 *v201109*. The goal is to provide a simple DSL for criteria so user doesn't have
@@ -303,7 +311,7 @@ to deal with somewhat convoluted AdWords API syntax made for machines, not
 humans. So far, this has been done only for *language* and *location* criterion.
 You can use any other criteria, you just have to enter them in AdWords format.
 
-##### Language #####
+##### Language
 
 ```ruby
 Adapi::CampaignCriterion.create(
@@ -317,7 +325,7 @@ Adapi::CampaignCriterion.create(
 `:language` parameter accepts string or symbols for single language target or
 array of strings/symbols for several language targets.
 
-##### Location #####
+##### Location
 
 ```ruby
 Adapi::CampaignCriterion.create(
@@ -384,7 +392,7 @@ Adapi::CampaignCriterion.create(
 )
 ```
 
-##### Criterion in AdWords format #####
+##### Criterion in AdWords format
 
 Convenient shortcuts for other criteria besides *language* and *location* are
 not yet implemented. However, you can use any other criteria, you just have to
@@ -399,7 +407,7 @@ Adapi::CampaignCriterion.create(
 )
 ```
 
-## Logging ##
+## Logging
 
 By default, communication with AdWords API is not logged. In order to log
 messages of certain log level or above, set `library/log_level` in configuration
@@ -421,7 +429,7 @@ Example of logger configuration:
     :log_pretty_format: true
 ```
 
-## Author ##
+## Author
 
 2011-2012 Lukas Stejskal, Ataxo Interactive, a.s.
 

data/adapi.gemspec

@@ -27,20 +27,20 @@ Gem::Specification.new do |s|
   # versions of both gems are freezed, because both gems change a lot and
   # automatic updates through '~>' can (and already did) break something
   #
-  s.add_dependency "google-ads-common", "0.7.3"
-  s.add_dependency "google-adwords-api", "0.6.2"
+  s.add_dependency "google-ads-common", "0.8.0"
+  s.add_dependency "google-adwords-api", "0.7.0"
 
   s.add_dependency "activemodel", "~> 3.0"
   s.add_dependency "activesupport", "~> 3.0"
   s.add_dependency "rake", "~> 0.9.2"
-  s.add_dependency "curb", "~> 0.8.0"
+  s.add_dependency "curb", "~> 0.8.1"
 
-  s.add_development_dependency "yard", "~> 0.7"
+  s.add_development_dependency "yard", "~> 0.8"
   s.add_development_dependency "rcov", "~> 0.9"
   s.add_development_dependency "turn", "~> 0.9.6"
-  s.add_development_dependency "shoulda"
-  s.add_development_dependency "fakeweb"
-  s.add_development_dependency "factory_girl", "~> 3.3.0"
-  s.add_development_dependency "minitest"
+  s.add_development_dependency "shoulda", "~> 3.1"
+  s.add_development_dependency "fakeweb", "~> 1.3"
+  s.add_development_dependency "factory_girl", "~> 3.3"
+  s.add_development_dependency "minitest", "~> 3.3"
 
 end

data/examples/add_ad_group.rb

@@ -2,12 +2,9 @@
 
 require 'adapi'
 
-# create campaign
 require_relative 'add_bare_campaign'
 
-# create ad group
-
-ad_group_data = {
+$ad_group_data = {
   :name => "AdGroup #%d" % (Time.new.to_f * 1000).to_i,
   :status => 'ENABLED',
   :campaign_id => $campaign[:id],
@@ -25,7 +22,16 @@ ad_group_data = {
   ]
 }
  
-$ad_group = Adapi::AdGroup.create(ad_group_data)
+$ad_group = Adapi::AdGroup.create($ad_group_data)
+
+unless $ad_group.errors.empty?
+
+  puts "ERROR WHEN CREATING AD GROUP:"
+  pp $ad_group.errors.full_messages
+
+else
+
+  puts "\nCREATED AD GROUP #{$ad_group[:id]} FOR CAMPAIGN #{$ad_group[:campaign_id]}\n"
+  pp $ad_group.attributes
 
-p "Created ad_group ID #{$ad_group.id} for campaign ID #{$ad_group.campaign_id}"
-p $ad_group.attributes
+end

data/examples/add_bare_ad_group.rb

@@ -2,7 +2,6 @@
 
 require 'adapi'
 
-# create campaign
 require_relative 'add_bare_campaign'
 
 # create ad group with basic data only
@@ -14,13 +13,20 @@ $ad_group_data = {
   :status => 'ENABLED',
   :bids => {
     :xsi_type => 'BudgetOptimizerAdGroupBids',
-    # FIXME this probably can't be set
-    :proxy_keyword_max_cpc => 15,
-    :proxy_site_max_cpc => 30
+    :proxy_keyword_max_cpc => 15
   }
 }
  
 $ad_group = Adapi::AdGroup.create($ad_group_data)
 
-p "Created ad_group ID #{$ad_group.id} for campaign ID #{$ad_group.campaign_id}"
-p $ad_group.attributes
+unless $ad_group.errors.empty?
+
+  puts "ERROR WHEN CREATING AD GROUP:"
+  pp $ad_group.errors.full_messages
+
+else
+
+  puts "\nCREATED AD GROUP #{$ad_group[:id]} FOR CAMPAIGN #{$ad_group[:campaign_id]}\n"
+  pp $ad_group.attributes
+
+end

data/examples/add_bare_campaign.rb

@@ -16,13 +16,20 @@ $campaign_data = {
   :network_setting => {
     :target_google_search => true,
     :target_search_network => true,
-    :target_content_network => false,
-    :target_content_contextual => false,
-    :target_partner_search_network => false
+    :target_content_network => false
   }
 }
- 
+
 $campaign = Adapi::Campaign.create($campaign_data)
 
-p "Created campaign ID #{$campaign.id}"
-p $campaign.attributes
+unless $campaign.errors.empty?
+
+  puts "ERROR WHEN CREATING CAMPAIGN:"
+  pp $campaign.errors.full_messages
+
+else
+
+  puts "\nCREATED CAMPAIGN #{$campaign[:id]}\n"
+  pp $campaign.attributes
+
+end

data/examples/add_campaign.rb

@@ -15,8 +15,7 @@ campaign_data = {
   :network_setting => {
     :target_google_search => true,
     :target_search_network => true,
-    :target_content_network => false,
-    :target_content_contextual => false
+    :target_content_network => false
   },
 
   # PS: :targets key is obsolete, this should be named :criteria, but it still works
@@ -46,15 +45,28 @@ campaign_data = {
   ]
 
 }
- 
-$campaign = Adapi::Campaign.create(campaign_data)
 
-$campaign = Adapi::Campaign.find($campaign.id)
+$campaign = Adapi::Campaign.new(campaign_data)
 
-p "\nCAMPAIGN #{$campaign.id} DATA:"
-pp $campaign.attributes
+$campaign.create
 
-$campaign_criterion = Adapi::CampaignCriterion.find( :campaign_id => $campaign.id )
+unless $campaign.errors.empty?
 
-p "\nCAMPAIGN CRITERIA:"
-pp $campaign_criterion
+  puts "ERROR WHEN CREATING CAMPAIGN:"
+  pp $campaign.errors.full_messages
+
+else
+
+  puts "\nCREATED CAMPAIGN #{$campaign[:id]}\n"
+
+  $campaign = Adapi::Campaign.find($campaign[:id])
+
+  puts "\nCAMPAIGN DATA:"
+  pp $campaign.attributes
+
+  $campaign_criteria = Adapi::CampaignCriterion.find( :campaign_id => $campaign[:id] )
+
+  puts "\nCRITERIA:"
+  pp $campaign_criteria
+
+end

data/examples/add_campaign_criteria.rb

@@ -2,12 +2,11 @@
 
 require 'adapi'
 
-# create campaign
 require_relative 'add_bare_campaign'
 
-$campaign_criterion = Adapi::CampaignCriterion.new(
-  :campaign_id => $campaign.id,
-  :targets => { #  obsolete, use :criteria instead
+$campaign_criteria_data = {
+  :campaign_id => $campaign[:id],
+  :criteria => {
     :language => %w{ en cs },
 
     :location => { 
@@ -19,9 +18,24 @@ $campaign_criterion = Adapi::CampaignCriterion.new(
     # add custom platform criteria
     :platform => [ { :id => 30001} ]
   }
-)
+}
 
-$campaign_criterion.create
+$campaign_criteria = Adapi::CampaignCriterion.new($campaign_criteria_data)
 
-$campaign_criterion = Adapi::CampaignCriterion.find( :campaign_id => $campaign.id)
-pp $campaign_criterion
+$campaign_criteria.create
+
+unless $campaign_criteria.errors.empty?
+
+  puts "ERROR WHEN CREATING CAMPAIGN CRITERIA FOR CAMPAIGN #{$campaign[:id]}:"
+  pp $campaign_criteria.errors.full_messages
+
+else
+
+  puts "\nCREATED CAMPAIGN CRITERIA FOR CAMPAIGN #{$campaign[:id]}\n"
+
+  $campaign_criteria = Adapi::CampaignCriterion.find( :campaign_id => $campaign[:id] )
+
+  puts "\nCRITERIA:"
+  pp $campaign_criteria
+
+end

data/examples/add_invalid_ad_group.rb

@@ -27,10 +27,14 @@ ad_group_data = {
  
 $ad_group = Adapi::AdGroup.create(ad_group_data)
 
-if $ad_group.errors.empty?
-  puts "OK"
-  pp $ad_group.attributes
+unless $ad_group.errors.empty?
+
+  puts "ERROR WHEN CREATING AD GROUP:"
+  pp $ad_group.errors.full_messages
+
 else
-  puts "ERROR:"
-  puts $ad_group.errors.full_messages.join("\n")
+
+  puts "AD GROUP #{$ad_group[:id]} CREATED"
+  pp $ad_group.attributes
+
 end

data/examples/add_invalid_keywords.rb

@@ -4,6 +4,9 @@ require 'adapi'
 
 # Errors will appear only in production, not in sandbox
 #
+# Adapi performs exemption requests on receiving policy violation errors.
+# If keyword errors are exemptable, they will eventually pass.
+#
 #Adapi::Config.load_settings
 #Adapi::Config.set(:production_settings)
 #

data/examples/add_invalid_text_ad.rb

@@ -3,6 +3,9 @@ require 'adapi'
 
 # PolicyViolations will appear only in production, not in sandbox
 #
+# Adapi performs exemption requests on receiving policy violation errors.
+# If text_ad errors are exemptable, they will eventually pass.
+#
 #Adapi::Config.load_settings
 #Adapi::Config.set(:production_settings)
 #
@@ -10,21 +13,24 @@ require 'adapi'
 
 require_relative 'add_bare_ad_group'
 
+# PS: exemptable PolicyViolationError is triggered by "ho":
+# legimitateword in Czech, but suspicious word in English
+#
 $ad = Adapi::Ad::TextAd.create(
   :ad_group_id => $ad_group[:id],
-  :headline => "Code a Blog",
-  :description1 => 'Need mad coding skill?',
-  :description2 => 'Check out my new blog!!!', # !!! - this is invalid
+  :headline => "Neo Blog - poznej ho",
+  :description1 => 'Poznej ho kdekoliv',
+  :description2 => 'Check out my ho blog',
   :url => 'http://www.demcodez.com',
   :display_url => 'http://www.demcodez.com',
   :status => 'PAUSED'
 )
 
 if $ad.errors.empty?
-  puts "OK"
+  puts "INVALID TEXT AD CREATED"
   $fresh_ad = Adapi::Ad::TextAd.find(:first, :id => $ad.id, :ad_group_id => $ad_group[:id])
   pp $fresh_ad.attributes
 else
-  puts "ERROR"
-  puts $ad.errors.full_messages.join("\n")
+  puts "ERRORS:"
+  pp $ad.errors.messages
 end