zuck 0.2.0 → 1.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MGYzNGI4MTQ0ZjJmNzgxZjQwY2JlNTg3YTgyMTc2NzlhYTE2NWNkZA==
+  data.tar.gz: !binary |-
+    ZjllZWZjNTgxYzdhYmRiNjQ1YmE2OTY5NTI5MmMyNmFjY2M2NDgyYQ==
+SHA512:
+  metadata.gz: !binary |-
+    NDU3YjViNWY4NWZiNGMzYTAwZTZmZmZmMWZmODVmNWQ2NjEyMzM3Nzc0OWFi
+    MWM5OWYwYTAyNmM1ODA4MTM1MmExYzI0MWM4YjM1N2MxNzc4NGFmMGYzMDc5
+    ODMwNzkwNTEzMThhYzgzYTE4ZWEyMWQ3NDM4NTdmMmZlMmY5Nzk=
+  data.tar.gz: !binary |-
+    NTZkMDQ0NzZlYzQyMGVmMmJiNjcwZmU2NmYzOTgwZTM1OWY2MGEwNjJhODQ3
+    YjcxMThmNzkxNDllOWYxMDhkMzhmMTBkNDk2ODg1ODFjY2RmYzBiODRjZDY2
+    MWMzZjkxNjhkNThmYjJkN2UxYTM3ZjM3ODE4Njg2ZGU1NDBlM2I=

data/.travis.yml

@@ -3,5 +3,4 @@ rvm:
   - "1.9.2"
   - "1.9.3"
   - jruby-19mode
-  - rbx-19mode
 script: bundle exec rspec spec

data/CHANGELOG.markdown

@@ -1,6 +1,17 @@
+1.0.0
+-----
+- Implement Facebook's April 9 breaking changes, which also change this
+  gem
+- AdKeyword/keywords are gone, welcome AdInterest/interests
+  (see [the
+docs](https://developers.facebook.com/docs/reference/ads-api/interest-targeting))
+- locations became geo_locations, and you can now also target cities
+  (see [the
+docs](https://developers.facebook.com/docs/reference/ads-api/targeting-specs))
+
 0.2.0
 -----
-- implement Facbook's [Oct 2013 breaking changes](https://developers.facebook.com/roadmap/#q4_2013)
+- implement Facebook's [Oct 2013 breaking changes](https://developers.facebook.com/roadmap/#q4_2013)
 
 0.0.9
 -----

data/Gemfile

@@ -2,14 +2,14 @@ source 'http://rubygems.org'
 
 gem 'rvm'
 gem 'bundler'
-gem 'koala', '>=1.6'
+gem 'koala', '~>1.6.0'
 gem 'activesupport'
 
 group :development do
-  gem "shoulda", ">= 0"
+  gem "shoulda", "~> 3.3.2"
   gem "rdoc", "~> 3.12"
-  gem "jeweler", "~> 1.8.4"
-  gem "simplecov", ">= 0", :require => false
+  gem "jeweler", "~> 2.0.1"
+  gem "simplecov", "~> 0.7.1", :require => false
 end
 
 group :development, :test do

data/Gemfile.lock

@@ -7,12 +7,20 @@ GEM
     addressable (2.3.3)
     bourne (1.1.2)
       mocha (= 0.10.5)
+    builder (3.2.2)
     coderay (1.0.8)
     crack (0.3.1)
     diff-lcs (1.1.3)
     faraday (0.8.7)
       multipart-post (~> 1.1)
-    git (1.2.5)
+    git (1.2.6)
+    github_api (0.10.2)
+      addressable
+      faraday (~> 0.8.7)
+      hashie (>= 1.2)
+      multi_json (~> 1.4)
+      nokogiri (~> 1.6.0)
+      oauth2
     growl (1.0.3)
     guard (1.6.1)
       listen (>= 0.6.0)
@@ -28,14 +36,22 @@ GEM
     guard-yard (2.0.1)
       guard (>= 1.1.0)
       yard (>= 0.7.0)
+    hashie (2.1.1)
+    highline (1.6.21)
     i18n (0.6.1)
-    jeweler (1.8.4)
-      bundler (~> 1.0)
+    jeweler (2.0.1)
+      builder
+      bundler (>= 1.0)
       git (>= 1.2.5)
+      github_api
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
       rake
       rdoc
-    json (1.7.5)
-    json (1.7.5-java)
+    json (1.8.1)
+    json (1.8.1-java)
+    jwt (0.1.11)
+      multi_json (>= 1.5)
     koala (1.6.0)
       addressable (~> 2.2)
       faraday (~> 0.8)
@@ -44,17 +60,30 @@ GEM
     lumberjack (1.0.2)
     metaclass (0.0.1)
     method_source (0.8.1)
+    mini_portile (0.5.3)
     mocha (0.10.5)
       metaclass (~> 0.0.1)
     multi_json (1.7.2)
+    multi_xml (0.5.5)
     multipart-post (1.2.0)
+    nokogiri (1.6.1)
+      mini_portile (~> 0.5.0)
+    nokogiri (1.6.1-java)
+      mini_portile (~> 0.5.0)
+    oauth2 (0.9.3)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 0.1.8)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (~> 1.2)
     pry (0.9.10)
       coderay (~> 1.0.5)
       method_source (~> 0.8)
       slop (~> 3.3.1)
-    rake (10.0.3)
+    rack (1.5.2)
+    rake (10.3.1)
     rb-fsevent (0.9.1)
-    rdoc (3.12)
+    rdoc (3.12.2)
       json (~> 1.4)
     redcarpet (2.2.2)
     rspec (2.12.0)
@@ -97,14 +126,14 @@ DEPENDENCIES
   guard-bundler
   guard-rspec
   guard-yard
-  jeweler (~> 1.8.4)
-  koala (>= 1.6)
+  jeweler (~> 2.0.1)
+  koala (~> 1.6.0)
   rb-fsevent
   rdoc (~> 3.12)
   redcarpet
   rspec
   rvm
-  shoulda
-  simplecov
+  shoulda (~> 3.3.2)
+  simplecov (~> 0.7.1)
   vcr
   webmock (~> 1.8.0)

data/README.markdown

@@ -88,14 +88,14 @@ group.ad_status
 => 3
 ```
 
-AdKeyword convenience methods
+AdInterest convenience methods
 --------
 
 ```ruby
 graph = Zuck.graph
 
 # Search for keywords (to auto complete, for example) (yes, facebook sometimes returns ids as string and sometimes as numbers)
-Zuck::AdKeyword.search(graph, "Auto")
+Zuck::AdInterest.search(graph, "Auto")
 =>  [
       {:keyword=>"Auto", :id=>"6003156165433", :audience=>nil},
       {:keyword=>"#Automobile", :id=>6003176678152, :audience=>97900000},
@@ -104,20 +104,20 @@ Zuck::AdKeyword.search(graph, "Auto")
     ]
 
 # Quickly check if a keyword is valid
-Zuck::AdKeyword.validate(graph, '#Eminem')
+Zuck::AdInterest.validate(graph, '#Eminem')
 => {"#Eminem" => true}
 
 # Quickly check a couple of keywords
-Zuck::AdKeyword.validate(graph, ['#Eminem', 'Wil Ferel', 'Bronson'])
+Zuck::AdInterest.validate(graph, ['#Eminem', 'Wil Ferel', 'Bronson'])
 => {"#Eminem"=>true, "Bronson"=>true, "Wil Ferel"=>false}
 
 # Make a best guess on how a keyword is called on Facebook
-Zuck::AdKeyword.best_guess(graph, 'Disney')
+Zuck::AdInterest.best_guess(graph, 'Disney')
 => {:keyword=>"#The Walt Disney Company", :id=>6003270522085, :audience=>72500000}
 
 # Sometimes a best guess does not return a keyword with a # prefix, and that
 # means that we don't know the audience of that keyword:
-Zuck::AdKeyword.best_guess(graph, 'Moviepilot')
+Zuck::AdInterest.best_guess(graph, 'Moviepilot')
 => {:keyword=>"Moviepilot", :id=>6003327847780, :audience=>nil}
 
 ```

data/VERSION

@@ -1 +1 @@
-0.2.0
+1.0.0

data/lib/zuck/facebook/ad_interest.rb

@@ -0,0 +1,44 @@
+module Zuck
+  module AdInterest
+    extend Zuck::Helpers
+    extend self
+
+    # Given an interest, make a guess on what the closest interest
+    # on the facebook ads api is. It tends to use a # prefixed
+    # interest if available, and also a more popular one over a less
+    # popular one
+    def best_guess(graph, interest)
+      search(graph, interest).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[:interest].length <=> a[:interest].length
+        end
+      end.last
+    end
+
+    # Checks the ad api to see if the given interests are valid
+    # @return [Hash] The keys are the (lowercased) interests and the values their validity
+    def validate(graph, interests)
+      interests = normalize_array(interests).map{|k| k.gsub(',', '%2C')}
+      search = graph.search(nil, type: 'adinterestvalid', interest_list: [interests].flatten)
+      results = {}
+      search.each do |r|
+        results[r['name']] = r['valid']
+      end
+      results
+    end
+
+    # Ad interest search
+    def search(graph, interest)
+      results = graph.search(interest, type: :adinterest).map do |r|
+        {
+          interest: r['name'],
+          id:   r['id'],
+          audience: r['audience_size']
+        }
+      end
+    end
+  end
+
+end

data/lib/zuck/facebook/targeting_spec.rb

@@ -35,13 +35,13 @@ module Zuck
   # Some helpers around https://developers.facebook.com/docs/reference/ads-api/targeting-specs/
   # Use like this:
   #
-  #     > ts = Facebook::TargetingSpec.new(graph, ad_account, keyword: 'foo', countries: ['US'])
+  #     > ts = Facebook::TargetingSpec.new(graph, ad_account, interest: 'foo', geo_locations: {countries: ['US']})
   #     > ts.spec
   #     => {
   #        :countries => [
   #          [0] "US"
   #        ],
-  #         :keywords => [
+  #         :interests => [
   #          [0] "foo"
   #        ]
   #     }
@@ -65,10 +65,10 @@ module Zuck
     #   - `:age_class` (optional): Set it to `young` or `old` to autoconfigure `age_min` and `age_max`
     #     for people older or younger than 25
     #   - `:locales` (optional): [disabled] Array of integers, valid keys are here https://graph.facebook.com/search?type=adlocale&q=en
-    #   - `:keywords`: Array of strings with keywords
+    #   - `:interests`: Array of strings with interests
     #
     def initialize(graph, ad_account, spec = nil)
-      @validated_keywords = {}
+      @validated_interests = {}
       @graph = graph
       @ad_account = "act_#{ad_account}".gsub('act_act_', 'act_')
       self.spec = spec
@@ -91,23 +91,23 @@ module Zuck
       result.with_indifferent_access
     end
 
-    def validate_keywords
-      @spec[:keywords].each do |w|
-        raise(InvalidKeywordError, w) unless validate_keyword(w)
+    def validate_interests
+      @spec[:interests].each do |w|
+        raise(InvalidKeywordError, w) unless validate_interest(w)
       end
     end
 
-    # Validates a single keyword from the cache or calls
-    # {TargetingSpec.validate_keywords}.to validate the keywords via
+    # Validates a single interest from the cache or calls
+    # {TargetingSpec.validate_interests}.to validate the interests via
     # facebook's api.
-    # @param keyword [String] A single keyword
+    # @param interest [String] A single interest
     # @return boolean
-    def validate_keyword(keyword)
-      if @validated_keywords[keyword] == nil
-        keywords = normalize_array([@spec[:keywords]] + [keyword])
-        @validated_keywords = Zuck::AdKeyword.validate(@graph, keywords)
+    def validate_interest(interest)
+      if @validated_interests[interest] == nil
+        interests = normalize_array([@spec[:interests]] + [interest])
+        @validated_interests = Zuck::AdInterest.validate(@graph, interests)
       end
-      @validated_keywords[keyword] == true
+      @validated_interests[interest] == true
     end
 
     # Fetches a bunch of reach estimates from facebook at once.
@@ -153,17 +153,18 @@ module Zuck
     private
 
     def validate_spec
-      @spec[:countries]   = normalize_countries(@spec[:countries])
-      @spec[:keywords]    = normalize_array(@spec[:keywords])
+      @spec[:interests]    = normalize_array(@spec[:interests])
       @spec[:broad_age] ||= false
       validate_countries
-      unless @spec[:keywords].present? or @spec[:connections].present?
-        raise(ParamsMissingError, "Need to set :keywords or :connections")
+      unless @spec[:interests].present? or @spec[:connections].present?
+        raise(ParamsMissingError, "Need to set :interests or :connections")
       end
     end
 
     def validate_countries
-      self.class.valid_countries?(@spec[:countries])
+      return unless @spec[:geo_locations] and @spec[:geo_locations][:countries]
+      @spec[:geo_locations][:countries] = normalize_countries(@spec[:geo_locations][:countries])
+      self.class.valid_countries?(@spec[:geo_locations][:countries])
     end
 
     def self.valid_countries?(countries)
@@ -193,8 +194,8 @@ module Zuck
       @spec[:genders] = [1] if gender.to_s == 'male'
       @spec[:genders] = [2] if gender.to_s == 'female'
 
-      keyword = spec.delete(:keyword)
-      @spec[:keywords] = normalize_array([keyword, @spec[:keywords]])
+      interest = spec.delete(:interest)
+      @spec[:interests] = normalize_array([interest, @spec[:interests]])
 
       country = spec.delete(:country)
       @spec[:countries] = normalize_countries([country, @spec[:countries]])

data/spec/fixtures/ad_interest_search_disney.yml

@@ -0,0 +1,54 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://graph.facebook.com/search?access_token=CAAEvJ5vzhl8BAPGZCZCPL4FxryEHXGxPCuCGeqe3PEWIjhIvJ00HB8PPpokFmUkemvmEUHirqdNMc7zIDLSTVnX6jTQjAgSlzcYrAYJRQ32fr6RM5ZAnKPdgFEwN5tgvswatXZAI4vu7ZBAQexRl9MU0CpwW7JDDBZAGo5XDrCKrBxkUUWJUvh&q=disney&type=adinterest
+    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:
+      Etag:
+      - ! '"8b5fcea570986b5e25aff7226b80215ebf71cf56"'
+      Content-Type:
+      - application/json; charset=UTF-8
+      Pragma:
+      - no-cache
+      Access-Control-Allow-Origin:
+      - ! '*'
+      X-Fb-Rev:
+      - '1216101'
+      Cache-Control:
+      - private, no-cache, no-store, must-revalidate
+      Expires:
+      - Sat, 01 Jan 2000 00:00:00 GMT
+      X-Fb-Debug:
+      - oBEMRG6MgL42DEtthxp3LNt+Gzgr2GbJckt8uA8N/q8=
+      Date:
+      - Tue, 22 Apr 2014 16:22:30 GMT
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '854'
+    body:
+      encoding: US-ASCII
+      string: ! '{"data":[{"name":"The Walt Disney Company","id":6003270522085,"audience_size":129354141,"path":[],"description":null},{"name":"Disney
+        Channel","id":6003327130854,"audience_size":45965936,"path":[],"description":null},{"name":"Walt
+        Disney","id":6003284678611,"audience_size":38133064,"path":[],"description":null},{"name":"Disneyland","id":6003274193708,"audience_size":31257896,"path":[],"description":null},{"name":"Walt
+        Disney Parks and Resorts","id":6003318701218,"audience_size":26448385,"path":[],"description":null},{"name":"List
+        of Disney Channel Original Movies","id":6003220883649,"audience_size":38392980,"path":[],"description":null},{"name":"Disney
+        XD","id":6003540152503,"audience_size":16841504,"path":[],"description":null},{"name":"Walt
+        Disney Animation Studios","id":6003375444677,"audience_size":17506594,"path":[],"description":null}]}'
+    http_version: 
+  recorded_at: Tue, 22 Apr 2014 16:22:31 GMT
+recorded_with: VCR 2.3.0

data/spec/fixtures/ad_interest_search_moviepilot.yml

@@ -0,0 +1,138 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://graph.facebook.com/search?access_token=CAAEvJ5vzhl8BAPGZCZCPL4FxryEHXGxPCuCGeqe3PEWIjhIvJ00HB8PPpokFmUkemvmEUHirqdNMc7zIDLSTVnX6jTQjAgSlzcYrAYJRQ32fr6RM5ZAnKPdgFEwN5tgvswatXZAI4vu7ZBAQexRl9MU0CpwW7JDDBZAGo5XDrCKrBxkUUWJUvh&q=moviepilotcom&type=adinterest
+    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:
+      Etag:
+      - ! '"f4708ef59d4457b905f54670ff7a3ab8fb53d758"'
+      Content-Type:
+      - application/json; charset=UTF-8
+      Pragma:
+      - no-cache
+      Access-Control-Allow-Origin:
+      - ! '*'
+      X-Fb-Rev:
+      - '1216101'
+      Cache-Control:
+      - private, no-cache, no-store, must-revalidate
+      Expires:
+      - Sat, 01 Jan 2000 00:00:00 GMT
+      X-Fb-Debug:
+      - 9Ihh9aS8WUH+aH6uc7MUk/Kxu6CV8yMAw6N0dClTJaM=
+      Date:
+      - Tue, 22 Apr 2014 16:22:30 GMT
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '107'
+    body:
+      encoding: US-ASCII
+      string: ! '{"data":[{"name":"moviepilotcom","id":6003495809986,"audience_size":4992196,"path":[],"description":null}]}'
+    http_version: 
+  recorded_at: Tue, 22 Apr 2014 16:22:32 GMT
+- request:
+    method: get
+    uri: https://graph.facebook.com/search?access_token=CAAEvJ5vzhl8BAPGZCZCPL4FxryEHXGxPCuCGeqe3PEWIjhIvJ00HB8PPpokFmUkemvmEUHirqdNMc7zIDLSTVnX6jTQjAgSlzcYrAYJRQ32fr6RM5ZAnKPdgFEwN5tgvswatXZAI4vu7ZBAQexRl9MU0CpwW7JDDBZAGo5XDrCKrBxkUUWJUvh&q=moviepilotcocomm&type=adinterest
+    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:
+      Etag:
+      - ! '"1050253aec7b29caff644806927dabfa81406eee"'
+      Content-Type:
+      - application/json; charset=UTF-8
+      Pragma:
+      - no-cache
+      Access-Control-Allow-Origin:
+      - ! '*'
+      X-Fb-Rev:
+      - '1216101'
+      Cache-Control:
+      - private, no-cache, no-store, must-revalidate
+      Expires:
+      - Sat, 01 Jan 2000 00:00:00 GMT
+      X-Fb-Debug:
+      - bBOfyA7fkYvP457S15CzkxmNavxH4F+Zx+Sys3Ux4v0=
+      Date:
+      - Tue, 22 Apr 2014 16:23:50 GMT
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '11'
+    body:
+      encoding: US-ASCII
+      string: ! '{"data":[]}'
+    http_version: 
+  recorded_at: Tue, 22 Apr 2014 16:23:52 GMT
+- request:
+    method: get
+    uri: https://graph.facebook.com/search?access_token=CAAEvJ5vzhl8BAPGZCZCPL4FxryEHXGxPCuCGeqe3PEWIjhIvJ00HB8PPpokFmUkemvmEUHirqdNMc7zIDLSTVnX6jTQjAgSlzcYrAYJRQ32fr6RM5ZAnKPdgFEwN5tgvswatXZAI4vu7ZBAQexRl9MU0CpwW7JDDBZAGo5XDrCKrBxkUUWJUvh&q=moviepilot&type=adinterest
+    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:
+      Etag:
+      - ! '"60861a1401b05970d9b7f19b2f1a6cbf470fe17b"'
+      Content-Type:
+      - application/json; charset=UTF-8
+      Pragma:
+      - no-cache
+      Access-Control-Allow-Origin:
+      - ! '*'
+      X-Fb-Rev:
+      - '1216101'
+      Cache-Control:
+      - private, no-cache, no-store, must-revalidate
+      Expires:
+      - Sat, 01 Jan 2000 00:00:00 GMT
+      X-Fb-Debug:
+      - uo6B1d8Kd0luLkuJlq53BjWBVCcZl93SjpuywRl/Aro=
+      Date:
+      - Tue, 22 Apr 2014 16:24:12 GMT
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '201'
+    body:
+      encoding: US-ASCII
+      string: ! '{"data":[{"name":"moviepilotcom","id":6003495809986,"audience_size":4992196,"path":[],"description":null},{"name":"moviepilot","id":6003327847780,"audience_size":2036083,"path":[],"description":null}]}'
+    http_version: 
+  recorded_at: Tue, 22 Apr 2014 16:24:13 GMT
+recorded_with: VCR 2.3.0