adapi 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in adapi.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+== MIT License
+
+Copyright (c) 2011, Lukas Stejskal.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.rdoc

@@ -0,0 +1,127 @@
+== Adapi
+
+Adapi (shortened "AdWords API") is a 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 (remember adwords4r gem?), inputs and outputs are plain
+Ruby arrays and hashes.
+
+Adapi is built on new Google Adwords API gems: google-ads-common and
+google-adwords-api. Arrays and hashes instead of objects come from there, but
+adapi takes it several steps further. AdWords services are represented by models
+with relations, so 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 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
+all planned functionality.
+
+== Installation
+
+       gem install adapi
+
+=== from git repository
+
+       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).
+
+=== 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_email: default_client_email@gmail.com
+          :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_email: sandbox_client_email@gmail.com
+          :user_agent: Adwords API Test
+        :service:
+          :environment: SANDBOX
+
+You tell adapi which account to use by setting an alias:
+
+      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:
+
+      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
+
+== Examples
+
+Example are available in /examples directory. For now, they are mostly just dumb
+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

@@ -0,0 +1,12 @@
+require 'bundler/gem_tasks'
+require 'rake'
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << %w{ lib test }
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+

data/adapi.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "adapi/version"
+
+Gem::Specification.new do |s|
+  s.name        = "adapi"
+  s.version     = Adapi::VERSION
+  s.authors     = ["Lukas Stejskal"]
+  s.email       = ["lucastej@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{User-friendly interface to Google Adwords API}
+  s.description = %q{This gem provides user-friendly interface to Google Adwords API.}
+
+  s.rubyforge_project = "adapi"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  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.1"
+  s.add_dependency "google-adwords-api", "~> 0.4.1"
+
+  s.add_development_dependency "turn"
+  s.add_development_dependency "shoulda"
+  s.add_development_dependency "fakeweb"
+  s.add_development_dependency "factory_girl"
+end

data/examples/add_ad.rb

@@ -0,0 +1,17 @@
+
+require 'adapi'
+
+# create ad group
+require 'add_bare_ad_group'
+
+ad_data = {
+  :ad_group_id => $ad_group[:id],
+  :xsi_type => 'TextAd',
+  :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'
+}
+
+p Adapi::Ad.create(:data => ad_data)

data/examples/add_ad_group.rb

@@ -0,0 +1,46 @@
+
+require 'adapi'
+
+# create campaign
+require '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],
+  :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' }
+    }
+  ],
+
+  :ads => [
+    {
+      :xsi_type => 'TextAd',
+      :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'
+    }
+  ]
+
+}
+ 
+p Adapi::AdGroup.create(:data => ad_group_data)

data/examples/add_ad_group_criteria.rb

@@ -0,0 +1,20 @@
+
+require 'adapi'
+
+# create ad group
+require 'add_bare_ad_group'
+
+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' }
+}
+
+p Adapi::AdGroupCriterion.create(
+  :ad_group_id => $ad_group[:id],
+  :criteria => [keyword_criterion, placement_criterion]
+)

data/examples/add_bare_ad_group.rb

@@ -0,0 +1,26 @@
+
+require 'adapi'
+
+# create campaign
+require 'add_bare_campaign'
+
+# create ad group with basic data only
+# this script is used as an include in other scripts
+
+$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
+      }
+    }
+  }
+}
+ 
+$ad_group = Adapi::AdGroup.create(:data => $ad_group_data)
+
+p $ad_group

data/examples/add_bare_campaign.rb

@@ -0,0 +1,27 @@
+
+require 'adapi'
+
+# add campaign with basic data only
+# this script is used as an include in other scripts
+
+$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'
+  },
+
+  :network_setting => {
+    :target_google_search => true,
+    :target_search_network => true,
+    :target_content_network => false,
+    :target_content_contextual => false
+  }
+}
+ 
+$campaign = Adapi::Campaign.create($campaign_data)
+
+p $campaign

data/examples/add_campaign.rb

@@ -0,0 +1,68 @@
+
+require 'adapi'
+
+# create campaign by single command, with campaing targets, with ad_groups
+# including keywords and ads
+
+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'
+  },
+
+  :network_setting => {
+    :target_google_search => true,
+    :target_search_network => true,
+    :target_content_network => false,
+    :target_content_contextual => false
+  },
+
+  :targets => {
+    :language => [ 'en', 'cs' ],
+    :geo => { :country => 'CZ' }
+  },
+
+  :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' }
+        }
+      ],
+    
+      :ads => [
+        {
+          :xsi_type => 'TextAd',
+          :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'
+        }
+      ]
+    }
+  ]
+
+}
+ 
+p Adapi::Campaign.create(campaign_data)

data/examples/add_campaign_targets.rb

@@ -0,0 +1,16 @@
+
+require 'adapi'
+
+# create campaign
+require 'add_bare_campaign'
+
+# create campaign targets
+campaign_target_data = {
+  :campaign_id => $campaign[:id],
+  :targets => {
+    :language => [ 'en', 'cs' ],
+    :geo => { :country => 'CZ' }
+  }
+}
+
+p Adapi::CampaignTarget.create(campaign_target_data)

data/examples/custom_settings.yml

@@ -0,0 +1,22 @@
+
+:default:
+  :authentication:
+    :method: ClientLogin
+    :email: default_email@gmail.com
+    :password: default_password
+    :developer_token: default_token
+    :client_email: default_client_email@gmail.com
+    :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_email: sandbox_client_email@gmail.com
+    :user_agent: Adwords API Test
+  :service:
+    :environment: SANDBOX