zuck 0.0.9 → 0.1.0

data/README.markdown

@@ -10,10 +10,6 @@ for a nice diagram that explains how things work.
 
 ![](https://dl.dropbox.com/u/1953503/kw29_koelner_gelierzucker_31_oder_diamant_feinster_zucker_462982.jpeg)
 
-We just hacked this up and are not using it in production yet,
-so handle with care. On the other hand, simplecov reports 100%
-coverage. But as it is a gem in a very early stage, a warning was
-due.
 
 Usage
 =====

data/VERSION

@@ -1 +1 @@
-0.0.9
+0.1.0

data/lib/zuck/facebook/ad_keyword.rb

@@ -0,0 +1,45 @@
+module Zuck
+  module AdKeyword
+    extend Zuck::Helpers
+    extend self
+
+    # Given a keyword, make a guess on what the closest keyword
+    # on the facebook ads api is. It tends to use a # prefixed
+    # keyword if available, and also a more popular one over a less
+    # popular one
+    def best_guess(graph, keyword)
+      search(graph, keyword).sort do |a,b|
+        if a[:audience].to_i > 0 || b[:audience].to_i > 0
+          a[:audience].to_i <=> b[:audience].to_i
+        else
+          b[:keyword].length <=> a[:keyword].length
+        end
+      end.last
+    end
+
+    # Checks the ad api to see if the given keywords are valid
+    # @return [Hash] The keys are the (lowercased) keywords and the values their validity
+    def validate(graph, keywords)
+      keywords = normalize_array(keywords).map{|k| k.gsub(',', '%2C')}
+      search = graph.search(nil, type: 'adkeywordvalid', keyword_list: keywords.join(","))
+      results = {}
+      search.each do |r|
+        results[r['name']] = r['valid']
+      end
+      results
+    end
+
+    # Ad keyword search
+    def search(graph, keyword)
+      results = graph.search(keyword, type: :adkeyword).map do |r|
+        audience = r['description'].scan(/[0-9]+/).join('').to_i rescue nil
+        {
+          keyword: r['name'],
+          id:   r['id'],
+          audience: audience
+        }
+      end
+    end
+  end
+
+end

data/lib/zuck/facebook/targeting_spec.rb

@@ -49,6 +49,8 @@ module Zuck
   #     => 12345
   #
   class TargetingSpec
+    include Zuck::Helpers
+
     attr_reader :spec, :graph
 
     # @param graph [Koala::Facebook::API] The koala graph object to use
@@ -103,23 +105,11 @@ module Zuck
     def validate_keyword(keyword)
       if @validated_keywords[keyword] == nil
         keywords = normalize_array([@spec[:keywords]] + [keyword])
-        @validated_keywords = self.class.validate_keywords(@graph, keywords)
+        @validated_keywords = Zuck::AdKeyword.validate(@graph, keywords)
       end
       @validated_keywords[keyword] == true
     end
 
-    # Checks the ad api to see if the given keywords are valid
-    # @return [Hash] The keys are the (lowercased) keywords and the values their validity
-    def self.validate_keywords(graph, keywords)
-      keywords = normalize_array(keywords).map{|k| k.gsub(',', '%2C')}
-      search = graph.search(nil, type: 'adkeywordvalid', keyword_list: keywords.join(","))
-      results = {}
-      search.each do |r|
-        results[r['name']] = r['valid']
-      end
-      results
-    end
-
     # Fetches a bunch of reach estimates from facebook at once.
     # @param graph Koala graph instance
     # @param specs [Array<Hash>] An array of specs as you would pass to {#initialize}
@@ -162,22 +152,6 @@ module Zuck
 
     private
 
-    def self.normalize_array(arr)
-      [arr].flatten.compact.map(&:to_s).uniq.sort
-    end
-
-    def self.normalize_countries(countries)
-      normalize_array(countries).map(&:upcase)
-    end
-
-    def normalize_array(arr)
-      self.class.normalize_array(arr)
-    end
-
-    def normalize_countries(countries)
-      self.class.normalize_countries(countries)
-    end
-
     def validate_spec
       @spec[:countries]   = normalize_countries(@spec[:countries])
       @spec[:keywords]    = normalize_array(@spec[:keywords])

data/lib/zuck/helpers.rb

@@ -0,0 +1,11 @@
+module Zuck
+  module Helpers
+    def normalize_array(arr)
+      [arr].flatten.compact.map(&:to_s).uniq.sort
+    end
+
+    def normalize_countries(countries)
+      normalize_array(countries).map(&:upcase)
+    end
+  end
+end

data/lib/zuck.rb

@@ -2,6 +2,7 @@ require 'active_support/all'
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 require 'zuck/koala/koala_methods'
 require 'zuck/fb_object'
+require 'zuck/helpers'
 Dir[File.expand_path("../zuck/facebook/**/*.rb", __FILE__)].each{ |f| require f}
 
 module Zuck

data/spec/fixtures/ad_keyword_search_disney.yml

@@ -0,0 +1,53 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://graph.facebook.com/search?access_token=CAAEvJ5vzhl8BAE7m0kztNbbASKHymRlXoBZCdZCtMsebNEgaR0yOmZCBfeTIXT8MnuV3ZCH5lBDQOcC4S9geswWZBuF707gJ42lV9DHgGILsRaiG2upipiHggl7UZAeDVgBSSsap9s9uv1ghZCxNsmH&q=disney&type=adkeyword
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      User-Agent:
+      - Faraday v0.8.7
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - ! '*/*'
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Origin:
+      - ! '*'
+      Cache-Control:
+      - private, no-cache, no-store, must-revalidate
+      Content-Type:
+      - application/json; charset=UTF-8
+      Etag:
+      - ! '"167c644dd8fab56d0277dc91306a5636a7994715"'
+      Expires:
+      - Sat, 01 Jan 2000 00:00:00 GMT
+      Pragma:
+      - no-cache
+      X-Fb-Rev:
+      - '880776'
+      X-Fb-Debug:
+      - Fc7xjOmnC+MtzLHCEOi9yDh3oWYLK/7+pqNc61S25kg=
+      Date:
+      - Fri, 19 Jul 2013 09:46:15 GMT
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '589'
+    body:
+      encoding: US-ASCII
+      string: ! '{"data":[{"name":"Disney Channel","id":6003711659516},{"name":"Disneyland","id":6003361056187},{"name":"Disney","id":6003663755307},{"name":"#The
+        Walt Disney Company","description":"Audience: 72,500,000","id":6003270522085},{"name":"#Disneyland","description":"Audience:
+        24,100,000","id":6003274193708},{"name":"#Disney Channel","description":"Audience:
+        17,800,000","id":6003327130854},{"name":"#The Walt Disney Company#Walt Disney
+        Pictures","description":"Audience: 14,600,000","id":6004710425192},{"name":"#Walt
+        Disney Pictures","description":"Audience: 14,600,000","id":6003050377616}]}'
+    http_version: 
+  recorded_at: Fri, 19 Jul 2013 09:46:19 GMT
+recorded_with: VCR 2.3.0

data/spec/fixtures/ad_keyword_search_nonexistant.yml

@@ -0,0 +1,48 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://graph.facebook.com/search?access_token=CAAEvJ5vzhl8BAE7m0kztNbbASKHymRlXoBZCdZCtMsebNEgaR0yOmZCBfeTIXT8MnuV3ZCH5lBDQOcC4S9geswWZBuF707gJ42lV9DHgGILsRaiG2upipiHggl7UZAeDVgBSSsap9s9uv1ghZCxNsmH&q=ick%20spickeby&type=adkeyword
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      User-Agent:
+      - Faraday v0.8.7
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - ! '*/*'
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Origin:
+      - ! '*'
+      Cache-Control:
+      - private, no-cache, no-store, must-revalidate
+      Content-Type:
+      - application/json; charset=UTF-8
+      Etag:
+      - ! '"1050253aec7b29caff644806927dabfa81406eee"'
+      Expires:
+      - Sat, 01 Jan 2000 00:00:00 GMT
+      Pragma:
+      - no-cache
+      X-Fb-Rev:
+      - '880776'
+      X-Fb-Debug:
+      - 9OW6+vCkQZB0G4ete2rLeuHXg2keTeb0soekntO0k0c=
+      Date:
+      - Fri, 19 Jul 2013 10:16:13 GMT
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '11'
+    body:
+      encoding: US-ASCII
+      string: ! '{"data":[]}'
+    http_version: 
+  recorded_at: Fri, 19 Jul 2013 10:16:17 GMT
+recorded_with: VCR 2.3.0

data/spec/fixtures/ad_keyword_search_steve_carell.yml

@@ -0,0 +1,49 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://graph.facebook.com/search?access_token=CAAEvJ5vzhl8BAE7m0kztNbbASKHymRlXoBZCdZCtMsebNEgaR0yOmZCBfeTIXT8MnuV3ZCH5lBDQOcC4S9geswWZBuF707gJ42lV9DHgGILsRaiG2upipiHggl7UZAeDVgBSSsap9s9uv1ghZCxNsmH&q=steve%20carell&type=adkeyword
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      User-Agent:
+      - Faraday v0.8.7
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - ! '*/*'
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Access-Control-Allow-Origin:
+      - ! '*'
+      Cache-Control:
+      - private, no-cache, no-store, must-revalidate
+      Content-Type:
+      - application/json; charset=UTF-8
+      Etag:
+      - ! '"60ec5ec86640fb83726a422cc072f56d0f507bc4"'
+      Expires:
+      - Sat, 01 Jan 2000 00:00:00 GMT
+      Pragma:
+      - no-cache
+      X-Fb-Rev:
+      - '880776'
+      X-Fb-Debug:
+      - kQjivQ0nnGBYWqGHMoygWVVEMyXLEezpddYiJnNYitM=
+      Date:
+      - Fri, 19 Jul 2013 10:09:06 GMT
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '248'
+    body:
+      encoding: US-ASCII
+      string: ! '{"data":[{"name":"Anything With Steve Carell","id":6003332902745},{"name":"Keep
+        Steve Carell On Office","id":6003656406820},{"name":"Steve Carell","id":6004016779789}]}'
+    http_version: 
+  recorded_at: Fri, 19 Jul 2013 10:09:10 GMT
+recorded_with: VCR 2.3.0

data/spec/lib/zuck/facebook/ad_keyword_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+describe Zuck::AdKeyword do
+  let(:graph){ Koala::Facebook::API.new('CAAEvJ5vzhl8BAE7m0kztNbbASKHymRlXoBZCdZCtMsebNEgaR0yOmZCBfeTIXT8MnuV3ZCH5lBDQOcC4S9geswWZBuF707gJ42lV9DHgGILsRaiG2upipiHggl7UZAeDVgBSSsap9s9uv1ghZCxNsmH')}
+
+  it "finds the best keyword with a #" do
+    VCR.use_cassette('ad_keyword_search_disney') do
+      Zuck::AdKeyword.best_guess(graph, 'disney')[:keyword].should == '#The Walt Disney Company'
+    end
+  end
+
+  it "finds the best keyword when no keyword with # is available" do
+    VCR.use_cassette('ad_keyword_search_steve_carell') do
+      Zuck::AdKeyword.best_guess(graph, 'steve carell')[:keyword].should == 'Steve Carell'
+    end
+  end
+
+  it "returns nil when nothing could be found" do
+    VCR.use_cassette('ad_keyword_search_nonexistant') do
+      Zuck::AdKeyword.best_guess(graph, 'ick spickeby').should be_nil
+    end
+  end
+end

data/spec/lib/zuck/facebook/targeting_spec_spec.rb

@@ -3,41 +3,6 @@ require 'spec_helper'
 describe Zuck::TargetingSpec do
   let(:ad_account){ "2ijdsfoij" }
   let(:graph){ mock('koala') }
-  let(:reach_response){
-      {                             # These can probably go since we have
-      "users" => 23688420,          # vcr cassetes with http requests and
-      "bid_estimations" => [        # responses in place
-        {
-          "location" => 3,
-          "cpc_min" => 37,
-          "cpc_median" => 44,
-          "cpc_max" => 57,
-          "cpm_min" => 6,
-          "cpm_median" => 12,
-          "cpm_max" => 33
-        }
-      ],
-      "imp_estimates" => [
-      ],
-      "data" => {
-        "users" => 23688420,
-        "bid_estimations" => [
-          {
-            "location" => 3,
-            "cpc_min" => 37,
-            "cpc_median" => 44,
-            "cpc_max" => 57,
-            "cpm_min" => 6,
-            "cpm_median" => 12,
-            "cpm_max" => 33
-          }
-        ],
-        "imp_estimates" => [
-        ]
-      }
-    }
-  }
-
 
   describe "validating keywords" do
 
@@ -166,7 +131,13 @@ describe Zuck::TargetingSpec do
   describe "Batch processing" do
     let(:graph){ Koala::Facebook::API.new('AAAEvJ5vzhl8BAPLr6fQgNy2wdUHDJ7ZAoX9PTZCFnebwuTBZBEqO7lNTVZA3XNsTHPTATpTmVFs6o6Jp1pZAL8ZA54BRBXWYtztVug8bm2BAZDZD') }
     let(:ad_account){ 'act_10150585630710217' }
+    let(:spec_mock){ mock(fetch_reach: {some: :data}) }
 
+    it "fetches each reach" do
+      requests = [{some: :thing}] * 51
+      Zuck::TargetingSpec.should_receive(:new).exactly(51).and_return spec_mock
+      Zuck::TargetingSpec.batch_reaches(graph, ad_account, requests)
+    end
     it "doesn't split up small bunches" do
       requests = [{some: :thing}] * 50
       graph.should_receive(:batch).once.and_return([])
@@ -178,5 +149,15 @@ describe Zuck::TargetingSpec do
       graph.should_receive(:batch).twice.and_return([])
       Zuck::TargetingSpec.batch_reaches(graph, ad_account, requests)
     end
+
+    it "reformats results including errors" do
+      responses = [{facebook: :response}, Koala::KoalaError.new]
+      requests = [{some: :thing}] * 51
+      graph.should_receive(:batch).twice.and_return(responses)
+      reaches = Zuck::TargetingSpec.batch_reaches(graph, ad_account, requests)
+
+      reaches[0][:success].should == true
+      reaches[1][:success].should == false
+    end
   end
 end

data/zuck.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "zuck"
-  s.version = "0.0.9"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jannis Hermanns"]
-  s.date = "2013-07-04"
+  s.date = "2013-07-19"
   s.description = "This gem allows to easily access facebook's ads api in ruby. See https://developers.facebook.com/docs/reference/ads-api/"
   s.email = "jannis@gmail.com"
   s.extra_rdoc_files = [
@@ -34,6 +34,7 @@ Gem::Specification.new do |s|
     "lib/zuck/facebook/ad_campaign.rb",
     "lib/zuck/facebook/ad_creative.rb",
     "lib/zuck/facebook/ad_group.rb",
+    "lib/zuck/facebook/ad_keyword.rb",
     "lib/zuck/facebook/targeting_spec.rb",
     "lib/zuck/fb_object.rb",
     "lib/zuck/fb_object/dsl.rb",
@@ -43,9 +44,13 @@ Gem::Specification.new do |s|
     "lib/zuck/fb_object/read.rb",
     "lib/zuck/fb_object/read_only.rb",
     "lib/zuck/fb_object/write.rb",
+    "lib/zuck/helpers.rb",
     "lib/zuck/koala/koala_methods.rb",
     "spec/fixtures/a_single_account.yml",
     "spec/fixtures/a_single_campaign.yml",
+    "spec/fixtures/ad_keyword_search_disney.yml",
+    "spec/fixtures/ad_keyword_search_nonexistant.yml",
+    "spec/fixtures/ad_keyword_search_steve_carell.yml",
     "spec/fixtures/create_ad_campaign.yml",
     "spec/fixtures/create_ad_group.yml",
     "spec/fixtures/delete_ad_group.yml",
@@ -60,6 +65,7 @@ Gem::Specification.new do |s|
     "spec/fixtures/reach_for_valid_keywords_male_young.yml",
     "spec/lib/zuck/facebook/ad_account_spec.rb",
     "spec/lib/zuck/facebook/ad_campaign_spec.rb",
+    "spec/lib/zuck/facebook/ad_keyword_spec.rb",
     "spec/lib/zuck/facebook/targeting_spec_spec.rb",
     "spec/lib/zuck/fb_object/helpers_spec.rb",
     "spec/lib/zuck/koala/koala_methods_spec.rb",

metadata

@@ -2,14 +2,14 @@
 name: zuck
 version: !ruby/object:Gem::Version
   prerelease: 
-  version: 0.0.9
+  version: 0.1.0
 platform: ruby
 authors:
 - Jannis Hermanns
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-04 00:00:00.000000000 Z
+date: 2013-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rvm
@@ -324,6 +324,7 @@ files:
 - lib/zuck/facebook/ad_campaign.rb
 - lib/zuck/facebook/ad_creative.rb
 - lib/zuck/facebook/ad_group.rb
+- lib/zuck/facebook/ad_keyword.rb
 - lib/zuck/facebook/targeting_spec.rb
 - lib/zuck/fb_object.rb
 - lib/zuck/fb_object/dsl.rb
@@ -333,9 +334,13 @@ files:
 - lib/zuck/fb_object/read.rb
 - lib/zuck/fb_object/read_only.rb
 - lib/zuck/fb_object/write.rb
+- lib/zuck/helpers.rb
 - lib/zuck/koala/koala_methods.rb
 - spec/fixtures/a_single_account.yml
 - spec/fixtures/a_single_campaign.yml
+- spec/fixtures/ad_keyword_search_disney.yml
+- spec/fixtures/ad_keyword_search_nonexistant.yml
+- spec/fixtures/ad_keyword_search_steve_carell.yml
 - spec/fixtures/create_ad_campaign.yml
 - spec/fixtures/create_ad_group.yml
 - spec/fixtures/delete_ad_group.yml
@@ -350,6 +355,7 @@ files:
 - spec/fixtures/reach_for_valid_keywords_male_young.yml
 - spec/lib/zuck/facebook/ad_account_spec.rb
 - spec/lib/zuck/facebook/ad_campaign_spec.rb
+- spec/lib/zuck/facebook/ad_keyword_spec.rb
 - spec/lib/zuck/facebook/targeting_spec_spec.rb
 - spec/lib/zuck/fb_object/helpers_spec.rb
 - spec/lib/zuck/koala/koala_methods_spec.rb
@@ -371,7 +377,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       segments:
       - 0
-      hash: 2966043831358265203
+      hash: 1542161049211835241
       version: '0'
   none: false
 required_rubygems_version: !ruby/object:Gem::Requirement