adapi 0.0.2 → 0.0.3

data/README.rdoc

@@ -13,7 +13,7 @@ single method call: Adapi::Campaign.create(campaign_data). Various convenience
 methods are added to the models, for example: campaign.pause! (pauses
 campaign). Adapi enables multiple AdWords accounts to be used at the same time.
 
-Adapi is STILL IN DEVELOPMENT, not nearly done yet! Version 0.1.0 should have
+Adapi is STILL IN DEVELOPMENT and not nearly done yet! Version 1.0.0 should have
 all planned functionality.
 
 == Installation
@@ -25,12 +25,50 @@ all planned functionality.
        bundle install
        rake install
 
-== Configuration of AdWords Account(s)
-
-This section explains how to connect to specific account and client.
-
-In general, you can set many AdWords accounts to connect to (similarly as you
-can set up several databases in Rails, for example).
+== 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.
+
+       # 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
 
@@ -83,38 +121,35 @@ the same configuration will also work for adapi: ~/adwords_api.yml
 Before logging into the Adwords API, you can set global settings through
 Adapi::Config:
 
-      Adapi::Config.set({
-        :authentication:
-          :method: ClientLogin
-          :email: sandbox_email@gmail.com
-          :password: sandbox_password
-          :developer_token: sandbox_token
-          :client_email: sandbox_client_email@gmail.com
-          :user_agent: Adwords API Test
-        :service:
-          :environment: SANDBOX
-      })
-
-This will override any previous configuration and set the account as :default.
-You can specify more accounts this way, with aliases, in the same way as in
-~/adapi.yml.
-
-== API
-
-There are two ways of working with API. Both examples show adding an ad to
-specific campaign's ad group:
-
-=== Model-centric
-
-       Adapi::Campaign.create(campaign_data)
-
-=== TODO Collection-centric 
-
-       account = Adapi::Account.new(:account_alias)
-
-       campaign = account.campaigns.create(campaign_data)
-
-       account.campaigns[ campaign[:id] ].ad_groups << ad_group_data
+  # 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_email     => "sandbox_client_email@gmail.com",
+          :user_agent       => "Adwords API Test"
+        },
+        :service => {
+          :environment      => "SANDBOX"
+        }
+    }
+  })
+  
+  Adapi::Config.set(:sandbox)
+
+== TODO API
+
+AdWords Services are implemented as models, similar to ActiveRecord models of
+database tables. They are built on ActiveModel.
+
+== API Version Support
+
+Adapi supports only the latest version of Google AdWords API: v201101. Older
+versions will not be supported. v201101 and newer versions will still be
+supported when new versions are released.
 
 == Examples
 

data/adapi.gemspec

@@ -20,6 +20,10 @@ 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 "rake", "~> 0.9.2"
+  s.add_dependency "curb", "~> 0.7.15"
 
   s.add_development_dependency "turn"
   s.add_development_dependency "shoulda"

data/examples/add_ad_group.rb

@@ -2,7 +2,7 @@
 require 'adapi'
 
 # create campaign
-require 'add_bare_campaign'
+require File.join(File.dirname(__FILE__), 'add_bare_campaign')
 
 # create ad group
 
@@ -10,29 +10,11 @@ ad_group_data = {
   :name => "AdGroup #%d" % (Time.new.to_f * 1000).to_i,
   :status => 'ENABLED',
   :campaign_id => $campaign[:id],
-  :bids => {
-    :xsi_type => 'ManualCPCAdGroupBids',
-    :keyword_max_cpc => {
-      :amount => {
-        :micro_amount => 10000000
-      }
-    }
-  },
 
-  :criteria => [
-    { # keyword_criterion
-      :xsi_type => 'BiddableAdGroupCriterion',
-      :criterion => { :xsi_type => 'Keyword', :text => 'codez', :match_type => 'BROAD' }
-    },
-    { # placement_criterion
-      :xsi_type => 'BiddableAdGroupCriterion',
-      :criterion => { :xsi_type => 'Placement', :url => 'http://www.blogger.com' }
-    }
-  ],
+  :keywords => [ 'dem codez', '"top coder"', '[-code]' ],
 
   :ads => [
     {
-      :xsi_type => 'TextAd',
       :headline => "Code like Neo",
       :description1 => 'Need mad coding skills?',
       :description2 => 'Check out my new blog!',
@@ -40,7 +22,9 @@ ad_group_data = {
       :display_url => 'http://www.demcodez.com'
     }
   ]
-
 }
  
-p Adapi::AdGroup.create(:data => 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_bare_ad_group.rb

@@ -2,18 +2,21 @@
 require 'adapi'
 
 # create campaign
-require 'add_bare_campaign'
+require File.join(File.dirname(__FILE__), 'add_bare_campaign')
 
 # create ad group with basic data only
 # this script is used as an include in other scripts
 
 $ad_group_data = {
+  :campaign_id => $campaign[:id],
   :name => "AdGroup #%d" % (Time.new.to_f * 1000).to_i,
   :status => 'ENABLED',
-  :campaign_id => $campaign[:id],
+  # TODO refactor AdGroup.bids DSL
   :bids => {
-    :xsi_type => 'ManualCPCAdGroupBids',
-    :keyword_max_cpc => {
+    # 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
       }
@@ -21,6 +24,8 @@ $ad_group_data = {
   }
 }
  
-$ad_group = Adapi::AdGroup.create(:data => $ad_group_data)
+$ad_group = Adapi::AdGroup.create($ad_group_data)
+
 
-p $ad_group
+p "Created ad_group ID #{$ad_group.id} for campaign ID #{$ad_group.campaign_id}"
+p $ad_group.attributes

data/examples/add_bare_campaign.rb

@@ -7,12 +7,9 @@ require 'adapi'
 $campaign_data = {
   :name => "Campaign #%d" % (Time.new.to_f * 1000).to_i,
   :status => 'PAUSED',
-  :bidding_strategy => { :xsi_type => 'ManualCPC' },
-  :budget => {
-    :period => 'DAILY',
-    :amount => { :micro_amount => 50000000 },
-    :delivery_method => 'STANDARD'
-  },
+  # :bidding_strategy => 'ManualCPC',
+  :bidding_strategy => { :xsi_type => 'BudgetOptimizer', :bid_ceiling => 55 },
+  :budget => 50,
 
   :network_setting => {
     :target_google_search => true,
@@ -24,4 +21,5 @@ $campaign_data = {
  
 $campaign = Adapi::Campaign.create($campaign_data)
 
-p $campaign
+p "Created campaign ID #{$campaign.id}"
+p $campaign.attributes

data/examples/add_campaign.rb

@@ -7,12 +7,9 @@ require 'adapi'
 campaign_data = {
   :name => "Campaign #%d" % (Time.new.to_f * 1000).to_i,
   :status => 'PAUSED',
-  :bidding_strategy => { :xsi_type => 'ManualCPC' },
-  :budget => {
-    :period => 'DAILY',
-    :amount => { :micro_amount => 50000000 },
-    :delivery_method => 'STANDARD'
-  },
+  # Automatic CPC: BudgetOptimizer or ManualCPC
+  :bidding_strategy => { :xsi_type => 'BudgetOptimizer', :bid_ceiling => 100 },
+  :budget => { :amount => 50, :delivery_method => 'STANDARD' },
 
   :network_setting => {
     :target_google_search => true,
@@ -23,36 +20,19 @@ campaign_data = {
 
   :targets => {
     :language => [ 'en', 'cs' ],
-    :geo => { :country => 'CZ' }
+    # TODO test together with city target
+    :geo => { :proximity => { :geo_point => '38.89859,-77.035971', :radius => '10 km' } }
   },
 
   :ad_groups => [
     {
       :name => "AdGroup #%d" % (Time.new.to_f * 1000).to_i,
       :status => 'ENABLED',
-      :bids => {
-        :xsi_type => 'ManualCPCAdGroupBids',
-        :keyword_max_cpc => {
-          :amount => {
-            :micro_amount => 10000000
-          }
-        }
-      },
-    
-      :criteria => [
-        { # keyword_criterion
-          :xsi_type => 'BiddableAdGroupCriterion',
-          :criterion => { :xsi_type => 'Keyword', :text => 'codez', :match_type => 'BROAD' }
-        },
-        { # placement_criterion
-          :xsi_type => 'BiddableAdGroupCriterion',
-          :criterion => { :xsi_type => 'Placement', :url => 'http://www.blogger.com' }
-        }
-      ],
-    
+
+      :keywords => [ 'dem codez', '"top coder"', "[-code]" ],
+
       :ads => [
         {
-          :xsi_type => 'TextAd',
           :headline => "Code like Neo",
           :description1 => 'Need mad coding skills?',
           :description2 => 'Check out my new blog!',
@@ -65,4 +45,7 @@ campaign_data = {
 
 }
  
-p Adapi::Campaign.create(campaign_data)
+$campaign = Adapi::Campaign.create(campaign_data)
+
+p "Created campaign ID #{$campaign.id}"
+p $campaign.attributes

data/examples/add_campaign_targets.rb

@@ -2,15 +2,24 @@
 require 'adapi'
 
 # create campaign
-require 'add_bare_campaign'
+require File.join(File.dirname(__FILE__), 'add_bare_campaign')
 
-# create campaign targets
-campaign_target_data = {
+# TODO we should be able call it from campaign instance, for example:
+# $campaign.set_targets(:language => [ 'en' ], ...)
+
+$campaign_target = Adapi::CampaignTarget.new(
   :campaign_id => $campaign[:id],
   :targets => {
-    :language => [ 'en', 'cs' ],
-    :geo => { :country => 'CZ' }
+    :language => [ 'en' ],
+    :geo => {
+      # :country => 'CZ'
+      # :province => 'CZ-PR'
+      # :city => { :city_name => 'Prague', :province_code => 'CZ-PR', :country_code => 'CZ' }
+      :proximity => { :geo_point => '50.083333,14.366667', :radius => '50 km' }
+    }
   }
-}
+)
+
+$campaign_target.create
 
-p Adapi::CampaignTarget.create(campaign_target_data)
+p $campaign_target.attributes

data/examples/add_invalid_ad_group.rb

@@ -0,0 +1,35 @@
+
+require 'adapi'
+
+# create campaign
+require File.join(File.dirname(__FILE__), 'add_bare_campaign')
+
+# create ad group
+
+ad_group_data = {
+  :name => "AdGroup #%d" % (Time.new.to_f * 1000).to_i,
+  :status => 'ENABLED',
+  :campaign_id => $campaign[:id],
+
+  :keywords => [ 'dem codez', '"top coder"', '[-code]' ],
+
+  :ads => [
+    {
+      :headline => "Code like Neo",
+      :description1 => 'Need mad coding skills?',
+      :description2 => 'Check out my new blog!',      
+      # this should throw an error
+      :url => 'http://www.demcodez.com THIS IS INVALID',
+      :display_url => 'http://www.demcodez.com'
+    }
+  ]
+}
+ 
+$ad_group = Adapi::AdGroup.create(ad_group_data)
+
+if $ad_group.errors.empty?
+  p $ad_group.data
+else
+  p "ERRORS:"
+  p $ad_group.errors.to_a
+end

data/examples/add_invalid_text_ad.rb

@@ -0,0 +1,30 @@
+
+require 'adapi'
+
+# PolicyViolations will appread only in production, not in sandbox
+#
+#Adapi::Config.load_settings
+#Adapi::Config.set(:production_settings)
+#
+#pp "Running in #{Adapi::Config.read[:service][:environment]}"
+
+# create ad group
+require File.join(File.dirname(__FILE__), 'add_bare_ad_group')
+
+$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
+  :url => 'http://www.demcodez.com',
+  :display_url => 'http://www.demcodez.com',
+  :status => 'PAUSED'
+)
+
+if $ad.errors.empty?
+  p "OK"
+  p $ad.data
+else
+  p "ERROR"
+  p $ad.errors.messages
+end

data/examples/add_keywords.rb

@@ -0,0 +1,14 @@
+
+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', '"top coder"', '[-code]' ]
+)
+
+$r = $keywords.create
+
+p $keywords

data/examples/add_text_ad.rb

@@ -0,0 +1,23 @@
+
+require 'adapi'
+
+# create ad group
+require File.join(File.dirname(__FILE__), 'add_bare_ad_group')
+
+ad = Adapi::Ad::TextAd.create(
+  :ad_group_id => $ad_group[:id],
+  :headline => "Code like Neo",
+  :description1 => 'Need mad coding skills?',
+  :description2 => 'Check out my new blog!',
+  :url => 'http://www.demcodez.com',
+  :display_url => 'http://www.demcodez.com',
+  :status => 'PAUSED'
+)
+
+if ad
+  p "OK"
+  p ad.data
+else
+  p "ERROR"
+  p ad.errors.messages
+end