adapi 0.0.4 → 0.0.5

data/.gitignore

@@ -5,3 +5,6 @@ pkg/*
 doc/*
 coverage/*
 .yardoc/*
+adapi.yml
+.rvmrc
+.idea/

data/GUIDELINES.markdown

@@ -0,0 +1,61 @@
+
+## Commit Guidelines ##
+
+Thank you for your pull requests! Please make sure that commits comply with
+following guidelines, so that commit messages will self-explanatory and revision
+history easy to browse and searchable:
+
+* commit messages should begin with either *verb* in the simple simple past
+  tense (try to use only the following verbs: *Added*, *Changed* or
+  *Removed*) or *special prefix* in square brackets:
+  
+    * [FIX] - commit fixes a bug. Message should contain description of the bug.  
+      Example: https://github.com/lstejskal/adapi/commit/71f881a85a16a174b2faf86c0ec72d5a490db438
+
+    * [HOTFIX] - commit fixes a bug, but the bugfix is brittle and should be
+      improved. Usually this marks a temporary hack which solves an urgent problem.  
+      Example: https://github.com/lstejskal/adapi/commit/a28e7d1d8d1a26de7e3a380d7fc8153752250388
+  
+    * [REFACTOR] - refactoring without any (or very little) changes in functionality.  
+      Example: https://github.com/lstejskal/adapi/commit/4eef493857ec0dcb581e88f87c51668c81a97d5d
+  
+    * [BUNDLER] something to do with gems  
+      Example: https://github.com/lstejskal/adapi/commit/a2838281b725ed6d826495683c822fd81807c674
+      
+    * You can also make create your own custom prefix, but please do it only sparingly.
+
+* commit messages should be as short as possible and to the point. Ideally we
+  should be able to figure out what the commit is about just by reading the
+  commit message, without a glance into the code.  
+  Example: "[FIX] nil.method error in Keyword#find method"
+
+* commits should not be too long, only deal with one thing or a couple of related things
+
+* avoid afterthought commits and last-minute fixes so popular in SVN. You're in the git now: ammend and rebase.
+
+  Example of unnecessary "afterthought" commits:  
+  10:00 12345 Added BubbleGum class  
+  10:05 12345 [FIX] removed extra comma in BubbleGum class  
+  10:15 12345 [REFACTOR] BubbleGum#chew method  
+
+  Last two fixes should be additionaly included to the first commit by `git ammend` command.
+
+## Branch Structure ##
+
+* *stable branch* - `master`, obviously. And also branch with the same name
+  as current version of gem. For example: if gem is version 0.0.4, stable branch
+  in either `master` and `0-0-4`. `master` branch might also contain latest
+  bugfixes from development branch.
+
+* *development branch* - branch with higher number than current gem version;
+  there should be always only one such branch. For example, if gem is version
+  0.0.4, development branch is `0-0-5`. If you living on the edge is your
+  thing, use development branch. It's not stable, but it won't be intentionally
+  broken either. It contains latest updates and bugfixes. Bigger features have
+  their own branches.
+
+* *feature branch* - named after feature that's being implemented in it. For
+  example: `v201109`, where the latest version of AdWords API is implemented.
+  Lots of action is happening there, expect things to be broken, use at your own
+  risk and make sure you know what you're doing (like, by reading the source
+  code first).

data/README.markdown

@@ -23,9 +23,7 @@ have all planned functionality.
 
 ## Installation ##
 
-```
-gem install adapi
-```
+`gem install adapi`
 
 ### from git repository ###
 
@@ -39,12 +37,41 @@ rake install
 ## 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 ####
+
+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 ####
+
+```ruby
+Adapi::Config.load_settings(:in_hash => {
+  :sandbox => {   
+      :authentication => {
+        :method               => "ClientLogin"
+        :email                => "sandbox_email@gmail.com",
+        :password             => "sandbox_password",
+        :developer_token      => "sandbox_token",
+        :client_customer_id   => "555-666-7777",
+        :user_agent           => "Adwords API Test"
+      },
+      :service => {
+        :environment          => "SANDBOX"
+      }
+  }
+})
+
+Adapi::Config.set(:sandbox)
+```
+
+#### 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.
 
 ```ruby 
-# load the settings
 Adapi::Config.load_settings(:in_hash => {
   :coca_cola => {
     :authentication => {
@@ -83,14 +110,7 @@ Adapi::Config.set(:coca_cola, :client_customer_id => '777-666-5555')
 # do some stuff here...
 ```
 
-### Authentication workflow ###
-
-* load configuration from `~/adapi.yml`
-* load configuration from `~/adwords_api.yml` (default configuration for AdWords gems
-  from Google)
-* set configuration directly to `Adapi::Config` (overrides previous settings)
-
-### Configuration by `adapi.yml` ###
+#### Configuration by `adapi.yml` ####
 
 Stored in `~/adapi.yml`. Supports multiple accounts, which are identifed by
 aliases. Example:
@@ -119,51 +139,52 @@ aliases. Example:
     :environment: SANDBOX
 ```
 
-You tell adapi which account to use by setting an alias:
+To tell adapi which account to use:
 
 ```ruby
 Adapi::Config.set(:sandbox)
 ```
 
-`:default` account is, as name implies, used by default. You must either set an
-alias to `Adapi::Config` or have account with `:default` alias available.
+`:default` account is, as name implies, used by default. If you don't have
+`:default` account available, you have to manually set account alias to
+`Adapi::Config`.
 
-### Configuration by adwords_api.yml ###
+### Authentication workflow ###
 
-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`
+* try to load configuration from `~/adapi.yml`
+* if `~/adapi.yml`doesn't exist, try to load configuration from
+  `~/adwords_api.yml` (used by adwords-api gem)
+* if there are no configuration files available, set configuration directly to
+  `Adapi::Config` (overrides previous settings)
 
-### Configuration directly in code ###
+## API Version Support ##
 
-Before logging into the Adwords API, you can set global settings through
-`Adapi::Config`:
+Adapi 0.0.5 and higher supports only the latest version of Google AdWords API: *v201109*
 
-```ruby
-# load the settings
-Adapi::Config.load_settings(:in_hash => {
-  :sandbox => {   
-      :authentication => {
-        :method               => "ClientLogin"
-        :email                => "sandbox_email@gmail.com",
-        :password             => "sandbox_password",
-        :developer_token      => "sandbox_token",
-        :client_customer_id   => "555-666-7777",
-        :user_agent           => "Adwords API Test"
-      },
-      :service => {
-        :environment          => "SANDBOX"
-      }
-  }
-})
+Older versions of adapi supporting older versions of AdWords API will still be
+available (adapi 0.0.4 supports only v201101), marked by AdWords API version tag.
 
-Adapi::Config.set(:sandbox)
-```
+## Unsupported AdWords services ##
 
-## API Version Support ##
+Following AdWords services are not supported by adapi at the moment. However,
+they will be implemented (this also serves as TODO list):
+
+* Campaign Data Management
+  * ConversionTrackerService
+  * UserListService
+
+* Optimization
+  * BulkOpportunityService
+  * ReportDefinitionService
+  * TargetingIdeaService
+  * TrafficEstimatorService
 
-* adapi supports only the latest version of Google AdWords API: *v201109*
-* older versions will not be supported (well, maybe *v201101*)
-* *v201109* and newer versions will still be supported when new versions are released
+* Account Management
+  * CustomerSyncService
+
+* Utility
+  * MutateJobService
+  * BulkMutateJobService
 
 ## Examples ##
 
@@ -171,6 +192,19 @@ Example 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.
 
+## Logging ##
+
+*STILL IN BETA* By default, nothing is logged. If you set `library/log_level` in
+configuration, SOAP messages will be logged to `~/adapi.log` file according to
+give log level.
+
+Example of logger configuration:
+
+```
+  :library:
+    :log_level: DEBUG
+```
+
 ## Author ##
 
-Lukas Stejskal
+2011-2012 Lukas Stejskal

data/Rakefile

@@ -1,14 +1,42 @@
 require 'bundler/gem_tasks'
 require 'rake'
 
-### Tests ###
+task :default do
+  # run examples using current gem environment
+  # example: rake example=find_campaigns
+  #
+  if ENV.keys.include?("example")
+    ENV["example"] += ".rb" unless ENV["example"] =~ /\.rb$/
+    exec "ruby -Ilib examples/%s" % ENV["example"]
+
+  # load example into irb using current gem environment
+  # example: rake irb=find_campaigns
+  #
+  elsif ENV.keys.include?("irb")
+    exec "irb -Ilib -Iexamples -r%s" % ENV["irb"].gsub(/\.rb$/, '')
+
+  # run default task: test
+  #
+  else
+    Rake::Task['test'].invoke
+  end
+end
 
-task :default => :test
+### Tests ###
 
+# run all tests except integrations tests
+#
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
   test.libs << %w{ lib test }
-  test.pattern = 'test/**/*_test.rb'
+  test.pattern = 'test/unit/*_test.rb'
+  test.verbose = true
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:"test:integration") do |test|
+  test.libs << %w{ lib test }
+  test.pattern = 'test/integration/*_test.rb'
   test.verbose = true
 end
 

data/adapi.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.version     = Adapi::VERSION
   s.authors     = ["Lukas Stejskal"]
   s.email       = ["lucastej@gmail.com"]
-  s.homepage    = ""
+  s.homepage    = "https://github.com/lstejskal/adapi"
   s.summary     = %q{User-friendly interface to Google Adwords API}
   s.description = %q{This gem provides user-friendly interface to Google Adwords API.}
 
@@ -18,8 +18,15 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_dependency "google-ads-common", "~> 0.5.0"
-  s.add_dependency "google-adwords-api", "~> 0.4.0"
+  # require specific version of ad-common and adwords-api gems,
+  # they're stil changing a lot and automatic updates through '~>'
+  # can easily break something
+  #
+  # PS: ads-common is "freezed" - required before adwords-api
+  #  
+  s.add_dependency "google-ads-common", "0.6.2"
+  s.add_dependency "google-adwords-api", "0.5.0"
+
   s.add_dependency "activemodel", "~> 3.1"
   s.add_dependency "activesupport", "~> 3.1"
   s.add_dependency "rake", "~> 0.9.2"

data/examples/add_ad_group.rb

@@ -3,7 +3,7 @@
 require 'adapi'
 
 # create campaign
-require File.join(File.dirname(__FILE__), 'add_bare_campaign')
+require_relative 'add_bare_campaign'
 
 # create ad group
 

data/examples/add_bare_ad_group.rb

@@ -3,7 +3,7 @@
 require 'adapi'
 
 # create campaign
-require File.join(File.dirname(__FILE__), 'add_bare_campaign')
+require_relative 'add_bare_campaign'
 
 # create ad group with basic data only
 # this script is used as an include in other scripts
@@ -12,9 +12,7 @@ $ad_group_data = {
   :campaign_id => $campaign[:id],
   :name => "AdGroup #%d" % (Time.new.to_f * 1000).to_i,
   :status => 'ENABLED',
-  # TODO refactor AdGroup.bids DSL
   :bids => {
-    # this should be set automatically, it's dependent on Campaign.bids
     :xsi_type => 'BudgetOptimizerAdGroupBids',
     :proxy_keyword_max_cpc => 10
   }
@@ -22,6 +20,5 @@ $ad_group_data = {
  
 $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

data/examples/add_campaign.rb

@@ -19,6 +19,7 @@ campaign_data = {
     :target_content_contextual => false
   },
 
+  # PS: :targets key is obsolete, this should be named :criteria, but it still works
   :targets => {
     :language => [ 'en', 'cs' ],
     # TODO test together with city target

data/examples/add_campaign_criteria.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+
+require 'adapi'
+
+# create campaign
+require_relative 'add_bare_campaign'
+
+$campaign_criterion = Adapi::CampaignCriterion.new(
+  :campaign_id => $campaign[:id],
+  :criteria => {
+    :language => %w{ en cs },
+
+    :location => { 
+      :id => 21137
+      # :name => { :city => 'Prague', :region => 'CZ-PR', :country => 'CZ' }
+      # :proximity => { :geo_point => '50.083333,14.366667', :radius => '50 km' }
+    },
+
+    # add custom platform criteria
+    :platform => [ { :id => 30001} ]
+  }
+)
+
+$campaign_criterion.create
+
+p $campaign_criterion.attributes
+

data/examples/add_invalid_ad_group.rb

@@ -1,9 +1,11 @@
 # encoding: utf-8
 
+# This example should throw an error on ad.url
+
 require 'adapi'
 
 # create campaign
-require File.join(File.dirname(__FILE__), 'add_bare_campaign')
+require_relative 'add_bare_campaign'
 
 # create ad group
 

data/examples/add_invalid_text_ad.rb

@@ -9,7 +9,7 @@ require 'adapi'
 #pp "Running in #{Adapi::Config.read[:service][:environment]}"
 
 # create ad group
-require File.join(File.dirname(__FILE__), 'add_bare_ad_group')
+require_relative 'add_bare_ad_group'
 
 $ad = Adapi::Ad::TextAd.create(
   :ad_group_id => $ad_group[:id],

data/examples/add_keywords.rb

@@ -3,7 +3,7 @@
 require 'adapi'
 
 # create ad group
-require File.join(File.dirname(__FILE__), 'add_bare_ad_group')
+require_relative 'add_bare_ad_group'
 
 $keywords = Adapi::Keyword.new(
   :ad_group_id => $ad_group[:id],

data/examples/add_negative_campaign_criteria.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+require 'adapi'
+
+# create campaign
+require_relative 'add_bare_campaign'
+
+$campaign_criterion = Adapi::CampaignCriterion.new(
+  :campaign_id => $campaign[:id],
+  :negative => true,
+  :criteria => {
+    :language => %w{ de },
+
+    :location => { 
+      :name => { :city => 'Oslo' }
+    }
+  }
+)
+
+$campaign_criterion.create
+
+p $campaign_criterion.attributes
+