adapi 0.0.3 → 0.0.4

data/.gitignore

@@ -2,3 +2,6 @@
 .bundle
 Gemfile.lock
 pkg/*
+doc/*
+coverage/*
+.yardoc/*

data/README.markdown

@@ -0,0 +1,176 @@
+# Adapi #
+
+## 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
+API-specific objects, inputs and outputs are plain Ruby arrays and hashes. 
+
+Adapi is built on `google-adwords-api` gem. Arrays and hashes instead of objects
+come from there, but adapi takes it several steps further:
+
+* AdWords services are represented by ActiveModel-compatible models with
+  relations. Among other things it's possible to create whole campaign in
+  single method call: `Adapi::Campaign.create(campaign_data)`.
+
+* Various convenience methods are added to the models, for example:
+  `campaign.pause!` (pauses campaign).
+
+* Adapi enables you to easily work with multiple AdWords accounts at the same time.
+
+Adapi is *still in development* and not nearly done yet! Version 1.0.0 should
+have all planned functionality.
+
+## Installation ##
+
+```
+gem install adapi
+```
+
+### from git repository ###
+
+```
+git clone git@github.com:lstejskal/adapi.git
+cd adapi
+bundle install
+rake install
+```
+
+## Configuration ##
+
+This section explains how to connect to specific AdWords account and client.
+
+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 => {
+      :method => 'ClientLogin',
+      :email => 'coca_cola_email@gmail.com',
+      :password => 'coca_cola_password',
+      :developer_token => 'coca_cola_developer_token',
+      :user_agent => 'Coca-Cola Adwords API Test'
+    },
+    :service => {
+      :environment => 'SANDBOX'
+    }
+  },
+ :pepsi => {
+    :authentication => {
+      :method => 'ClientLogin',
+      :email => 'pepsi_email@gmail.com',
+      :password => 'pepsi_password',
+      :developer_token => 'pepsi_developer_token',
+      :user_agent => 'Pepsi Adwords API Test'
+    },
+    :service => {
+      :environment => 'SANDBOX'
+    }
+  }
+})
+
+# set to pepsi and specific client       
+Adapi::Config.set(:pepsi, :client_customer_id => '555-666-7777')
+
+# do some stuff here...
+
+# set to coca-cola and another client       
+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` ###
+
+Stored in `~/adapi.yml`. Supports multiple accounts, which are identifed by
+aliases. Example:
+
+```
+:default:
+  :authentication:
+    :method: ClientLogin
+    :email: default_email@gmail.com
+    :password: default_password
+    :developer_token: default_token
+    :client_customer_id: 777-666-5555
+    :user_agent: My Adwords API Client
+  :service:
+    :environment: PRODUCTION
+
+: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
+```
+
+You tell adapi which account to use by setting an alias:
+
+```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.
+
+### 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`
+
+### Configuration directly in code ###
+
+Before logging into the Adwords API, you can set global settings through
+`Adapi::Config`:
+
+```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"
+      }
+  }
+})
+
+Adapi::Config.set(:sandbox)
+```
+
+## API Version Support ##
+
+* 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
+
+## Examples ##
+
+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.
+
+## Author ##
+
+Lukas Stejskal

data/Rakefile

@@ -1,6 +1,8 @@
 require 'bundler/gem_tasks'
 require 'rake'
 
+### Tests ###
+
 task :default => :test
 
 require 'rake/testtask'
@@ -10,3 +12,33 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = true
 end
 
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |t|
+  t.libs << "test"
+  t.pattern = 'test/*/*_test.rb'
+  t.rcov_opts << '--exclude /gems/'
+end
+
+### Documentation ### 
+
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+desc "Generate documentation"
+task :doc => 'doc:generate'
+
+namespace :doc do
+  GEM_ROOT = File.dirname(__FILE__)
+  RDOC_ROOT = File.join(GEM_ROOT, 'doc')
+
+  YARD::Rake::YardocTask.new(:generate) do |rdoc|
+    rdoc.files = Dir.glob(File.join(GEM_ROOT, 'lib', '**', '*.rb')) +
+      [ File.join(GEM_ROOT, 'README.md') ]
+    rdoc.options = ['--output-dir', RDOC_ROOT, '--readme', 'README.md']
+  end
+
+  desc "Remove generated documentation"
+  task :clobber do
+    FileUtils.rm_rf(RDOC_ROOT) if File.exists?(RDOC_ROOT)
+  end
+end

data/adapi.gemspec

@@ -20,13 +20,16 @@ Gem::Specification.new do |s|
 
   s.add_dependency "google-ads-common", "~> 0.5.0"
   s.add_dependency "google-adwords-api", "~> 0.4.0"
-  s.add_dependency "activemodel", "~> 3.1.0" # , :require => "active_model"
-  s.add_dependency "activesupport", "~> 3.1.0" #, :require => "active_support"
+  s.add_dependency "activemodel", "~> 3.1"
+  s.add_dependency "activesupport", "~> 3.1"
   s.add_dependency "rake", "~> 0.9.2"
-  s.add_dependency "curb", "~> 0.7.15"
+  s.add_dependency "curb", "~> 0.7"
 
-  s.add_development_dependency "turn"
+  s.add_development_dependency "yard", "~> 0.7"
+  s.add_development_dependency "rcov", "~> 0.9"
+  s.add_development_dependency "turn", "0.8.2" # PS: 0.8.3 is broken
   s.add_development_dependency "shoulda"
   s.add_development_dependency "fakeweb"
   s.add_development_dependency "factory_girl"
+  s.add_development_dependency "minitest"
 end

data/examples/add_ad_group.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 require 'adapi'
 

data/examples/add_bare_ad_group.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 require 'adapi'
 
@@ -15,12 +16,7 @@ $ad_group_data = {
   :bids => {
     # this should be set automatically, it's dependent on Campaign.bids
     :xsi_type => 'BudgetOptimizerAdGroupBids',
-    # :keyword_max_cpc => 10
-    :proxy_keyword_max_cpc => {
-      :amount => {
-        :micro_amount => 10000000
-      }
-    }
+    :proxy_keyword_max_cpc => 10
   }
 }
  

data/examples/add_bare_campaign.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 require 'adapi'
 

data/examples/add_campaign.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 require 'adapi'
 

data/examples/add_campaign_targets.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 require 'adapi'
 

data/examples/add_invalid_ad_group.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 require 'adapi'
 

data/examples/add_keywords.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 require 'adapi'
 
@@ -11,4 +12,15 @@ $keywords = Adapi::Keyword.new(
 
 $r = $keywords.create
 
-p $keywords
+# get array of keywords from Keyword instance
+$google_keywords = Adapi::Keyword.find(:all, :ad_group_id => $ad_group[:id]).keywords
+
+$params_keywords = Adapi::Keyword.parameterized($google_keywords)
+
+$short_keywords = Adapi::Keyword.shortened($google_keywords)
+
+p "PARAMS:"
+pp $params_keywords
+
+p "\nSHORT:"
+pp $short_keywords

data/examples/custom_settings.yml

@@ -5,7 +5,7 @@
     :email: default_email@gmail.com
     :password: default_password
     :developer_token: default_token
-    :client_email: default_client_email@gmail.com
+    :client_customer_id: 555-666-7777
     :user_agent: My Adwords API Client
   :service:
     :environment: PRODUCTION
@@ -16,7 +16,7 @@
     :email: sandbox_email@gmail.com
     :password: sandbox_password
     :developer_token: sandbox_token
-    :client_email: sandbox_client_email@gmail.com
+    :client_customer_id: 555-666-7777
     :user_agent: Adwords API Test
   :service:
     :environment: SANDBOX

data/examples/customize_configuration.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 require 'adapi'
 
 # this example shows how to load custom settings

data/examples/delete_keyword.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+
+require 'adapi'
+
+# create ad group
+require File.join(File.dirname(__FILE__), 'add_bare_ad_group')
+
+$keywords = Adapi::Keyword.new(
+  :ad_group_id => $ad_group[:id],
+  :keywords => [ 'dem codez', '-hacker' ]
+)
+
+$r = $keywords.create
+
+# get array of keywords for ad_group
+$google_keywords = Adapi::Keyword.find(:all, :ad_group_id => $ad_group[:id]).keywords
+
+p "BEFORE DELETE: #{$google_keywords.size} keywords"
+
+if Adapi::Keyword.new(:ad_group_id => $ad_group[:id]).delete($google_keywords.first[:text][:criterion][:id])
+  p "SUCCESS: first keyword deleted."
+else
+  p "ERROR: keyword could not be deleted."
+end
+
+$google_keywords = Adapi::Keyword.find(:all, :ad_group_id => $ad_group[:id]).keywords
+p "AFTER DELETE: #{$google_keywords.size} keywords"

data/examples/find_all_campaigns.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+require 'adapi'
+
+# find all campaigns for customer
+ 
+$campaigns = Adapi::Campaign.find :all
+
+p "Found %s campaigns." % $campaigns.size
+
+$campaigns.each do |campaign|
+  p "ID: %s, NAME %s" % [ campaign[:id], campaign[:name] ]
+end

data/examples/find_campaign.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+require 'adapi'
+
+# create campaign
+require File.join(File.dirname(__FILE__), 'add_campaign')
+
+$campaign = Adapi::Campaign.find_complete($campaign.id).to_hash
+
+puts "Campaign id: %s" % $campaign[:id]
+puts "Name: %s" % $campaign[:name]
+puts "Status: %s" % $campaign[:status]
+
+puts "\nBudget delivery method: %s" % $campaign[:budget][:delivery_method]
+puts "Budget period: %s" % $campaign[:budget][:period]
+# TODO budget.amount
+
+puts "\nBidding strategy type: %s" % $campaign[:bidding_strategy][:xsi_type]
+# TODO bidding_strategy.bid_ceiling
+
+puts "\nTargets:"
+$campaign[:targets].each do |target|
+  p target[:xsi_type]
+  p target
+end
+
+puts "\nAd groups (#{$campaign[:ad_groups].size} in total):"
+$campaign[:ad_groups].each do |ad_group|
+  puts "ID: %s, NAME %s, STATUS %s" % [ ad_group[:id], ad_group[:name], ad_group[:status] ]
+  puts "KEYWORDS: %s" % ad_group[:keywords].join(", ")
+  puts "ADS:"
+  ad_group[:ads].each do |ad|
+    puts "\nheadline: %s" % ad[:headline] 
+    puts "description1: %s" % ad[:description1]
+    puts "description2: %s" % ad[:description2]
+    puts "url: %s" % ad[:url]
+    puts "display_url: %s" % ad[:display_url]
+  end
+end

data/examples/find_campaign_ad_groups.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+require 'adapi'
+
+# create campaign
+require File.join(File.dirname(__FILE__), 'add_bare_ad_group')
+
+# find all ad_groups for campaign
+ 
+$ad_groups = Adapi::AdGroup.find :all, :campaign_id => $campaign.to_param
+
+p "Found %s ad groups." % $ad_groups.size
+
+$ad_groups.each do |ad_group|
+  puts "ID: %s, NAME %s, STATUS %s" % [ ad_group[:id], ad_group[:name], ad_group[:status] ]
+  puts "KEYWORDS: %s" % ad_group[:keywords].join(", ")
+  puts "ADS:"
+  ad_group[:ads].each do |ad|
+    puts "\nheadline: %s" % ad[:headline] 
+    puts "description1: %s" % ad[:description1]
+    puts "description2: %s" % ad[:description2]
+    puts "url: %s" % ad[:url]
+    puts "display_url: %s" % ad[:display_url]
+  end
+end