facebook_ads 0.1.11 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bf22df6e62e386f9fcdb2f9e7d9be3edafb0ff7d
-  data.tar.gz: 0327f5a21d3963224a14c2b429eb9be040476e93
+  metadata.gz: 62ff9dd5a06adb1dd35f8ac42de0c0ad2cfed483
+  data.tar.gz: ca66b643ff764379230f2a9aae554d24b38220c1
 SHA512:
-  metadata.gz: b834ddb9ab674ad353d74171ea3ad90822ac1298b50a2b83d4f62595d93b6738c234736a98a70f823a9df0cd86dadadfa113c24544ee7e770b268a9a40da2be5
-  data.tar.gz: d7027a82225878643cb3f1de1dee0c744cf1a6122412114fc5a752ea07fc1c4831e4d555f5f5f749746a45a109e5a6a0902df375ebc50ee409316f3774bca72f
+  metadata.gz: 5d66eb00859e9faf05c806fb885d4ffe9da2d8d55930974f1a44d4748f4e0ac2950f019091a61c92efd7af80600e01f720d9b4316934c73460fb4065a2a96600
+  data.tar.gz: a18712eb4d1a844ab96ea041d30b072e5b2b6ea792564669ed341e2609befbe5a5abdde56b960a1bf58021a0fa37280f7dc62eb410e9b3fa2eee8a0c6aba93ea

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -1,3 +1,5 @@
+inherit_from: .rubocop_todo.yml
+
 AllCops:
   Exclude:
     - bin/console
@@ -9,15 +11,25 @@ Metrics/CyclomaticComplexity:
   Enabled: false
 Metrics/PerceivedComplexity:
   Enabled: false
-
 Metrics/LineLength:
   Enabled: false
 Metrics/ClassLength:
   Enabled: false
 Metrics/MethodLength:
   Enabled: false
+Metrics/BlockLength:
+  Enabled: false
 Metrics/ParameterLists:
   Enabled: false
 
 Style/Documentation:
   Enabled: false
+Style/IndentationWidth:
+  Enabled: false
+Style/ElseAlignment:
+  Enabled: false
+Style/GuardClause:
+  Enabled: false
+
+# Lint/EndAlignment:
+#   Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,16 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2017-04-25 18:21:46 -0700 using RuboCop version 0.48.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyleAlignWith, SupportedStylesAlignWith, AutoCorrect.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Lint/EndAlignment:
+  Exclude:
+    - 'lib/facebook_ads/ad_account.rb'
+    - 'lib/facebook_ads/base.rb'

data/.travis.yml

@@ -4,5 +4,7 @@ rvm:
 branches:
   only:
     - master
+script:
+  # - bundle exec rubocop
+  - bundle exec rspec
 cache: bundler
-script: bundle exec rake test

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## 0.1.12 (2017-05-25)
+ - Added complete set of ad campaign objectives. (#9, @cte)
+ - Switched to rspec from minitest. (#8, @cte)
+ - Formatting tweaks in exception error messages (#7, @dekaikiwi)
+ - Added a reach_estimate method for ad accounts (ae35878, @cte)

data/Gemfile

@@ -1,15 +1,18 @@
 source 'https://rubygems.org'
 gemspec
 
-group :development do
-  gem 'pry', '~> 0.10'
-  gem 'awesome_print', '~> 1.7'
+group :development, :test do
+  gem 'awesome_print'
+  gem 'pry'
+  gem 'rake'
+  gem 'rubocop'
 end
 
 group :test do
-  gem 'rake'
-  gem 'minitest'
-  gem 'webmock'
-  gem 'vcr'
+  gem 'approvals'
   gem 'coveralls', require: false
+  gem 'multi_json'
+  gem 'rspec'
+  gem 'vcr'
+  gem 'webmock'
 end

data/Gemfile.lock

@@ -8,58 +8,92 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.5.0)
+    addressable (2.5.1)
       public_suffix (~> 2.0, >= 2.0.2)
+    approvals (0.0.22)
+      nokogiri (~> 1.6)
+      thor (~> 0.18)
+    ast (2.3.0)
     awesome_print (1.7.0)
     coderay (1.1.1)
-    coveralls (0.8.17)
+    coveralls (0.8.20)
       json (>= 1.8, < 3)
-      simplecov (~> 0.12.0)
+      simplecov (~> 0.14.1)
       term-ansicolor (~> 1.3)
-      thor (~> 0.19.1)
+      thor (~> 0.19.4)
       tins (~> 1.6)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
+    diff-lcs (1.3)
     docile (1.1.5)
-    domain_name (0.5.20161129)
+    domain_name (0.5.20170404)
       unf (>= 0.0.5, < 1.0.0)
     hashdiff (0.3.2)
-    hashie (3.4.6)
+    hashie (3.5.5)
     http-cookie (1.0.3)
       domain_name (~> 0.5)
-    json (2.0.2)
+    json (2.1.0)
     method_source (0.8.2)
     mime-types (3.1)
       mime-types-data (~> 3.2015)
     mime-types-data (3.2016.0521)
-    minitest (5.10.1)
+    mini_portile2 (2.1.0)
+    multi_json (1.12.1)
     netrc (0.11.0)
+    nokogiri (1.7.1)
+      mini_portile2 (~> 2.1.0)
+    parser (2.4.0.0)
+      ast (~> 2.2)
+    powerpack (0.1.1)
     pry (0.10.4)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
       slop (~> 3.4)
-    public_suffix (2.0.4)
+    public_suffix (2.0.5)
+    rainbow (2.2.2)
+      rake
     rake (12.0.0)
-    rest-client (2.0.0)
+    rest-client (2.0.2)
       http-cookie (>= 1.0.2, < 2.0)
       mime-types (>= 1.16, < 4.0)
       netrc (~> 0.8)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.4)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+    rubocop (0.48.1)
+      parser (>= 2.3.3.1, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.8.1)
     safe_yaml (1.0.4)
-    simplecov (0.12.0)
+    simplecov (0.14.1)
       docile (~> 1.1.0)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.0)
     slop (3.6.0)
-    term-ansicolor (1.4.0)
+    term-ansicolor (1.6.0)
       tins (~> 1.0)
     thor (0.19.4)
-    tins (1.13.0)
+    tins (1.13.2)
     unf (0.1.4)
       unf_ext
-    unf_ext (0.0.7.2)
+    unf_ext (0.0.7.4)
+    unicode-display_width (1.2.1)
     vcr (3.0.3)
-    webmock (2.3.1)
+    webmock (3.0.1)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff
@@ -68,14 +102,17 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  awesome_print (~> 1.7)
+  approvals
+  awesome_print
   coveralls
   facebook_ads!
-  minitest
-  pry (~> 0.10)
+  multi_json
+  pry
   rake
+  rspec
+  rubocop
   vcr
   webmock
 
 BUNDLED WITH
-   1.13.7
+   1.14.6

data/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2017 Tophatter, Inc.
+
+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.md

@@ -28,6 +28,14 @@ You'll need an [Access Token](https://developers.facebook.com/docs/marketing-api
 FacebookAds.access_token = '[YOUR_ACCESS_TOKEN]'
 ```
 
+## API Version
+
+This gem currently uses v2.8 of the Marketing API (soon to be updated to 2.9). You can change the version as desired with the following:
+
+```ruby
+FacebookAds.base_uri = 'https://graph.facebook.com/v2.9'
+```
+
 ## Console
 
 This gem provides a console using [Pry](https://github.com/pry/pry) and [AwesomePrint](https://github.com/awesome-print/awesome_print) for you to test & debug.

data/facebook_ads.gemspec

@@ -1,9 +1,9 @@
 # To release a new version:
 # gem build facebook_ads.gemspec
-# gem push facebook_ads-0.1.11.gem
+# gem push facebook_ads-0.1.12.gem
 Gem::Specification.new do |s|
   s.name        = 'facebook_ads'
-  s.version     = '0.1.11'
+  s.version     = '0.1.12'
   s.platform    = Gem::Platform::RUBY
   s.licenses    = ['MIT']
   s.authors     = ['Chris Estreich']

data/lib/facebook_ads/ad.rb

@@ -2,8 +2,8 @@ module FacebookAds
   # An ad belongs to an ad set. It is created using an ad creative.
   # https://developers.facebook.com/docs/marketing-api/reference/adgroup
   class Ad < Base
-    FIELDS   = %w(id account_id campaign_id adset_id adlabels bid_amount bid_info bid_type configured_status conversion_specs created_time creative effective_status last_updated_by_app_id name tracking_specs updated_time ad_review_feedback).freeze
-    STATUSES = %w(ACTIVE PAUSED DELETED PENDING_REVIEW DISAPPROVED PREAPPROVED PENDING_BILLING_INFO CAMPAIGN_PAUSED ARCHIVED ADSET_PAUSED).freeze
+    FIELDS   = %w[id account_id campaign_id adset_id adlabels bid_amount bid_info bid_type configured_status conversion_specs created_time creative effective_status last_updated_by_app_id name tracking_specs updated_time ad_review_feedback].freeze
+    STATUSES = %w[ACTIVE PAUSED DELETED PENDING_REVIEW DISAPPROVED PREAPPROVED PENDING_BILLING_INFO CAMPAIGN_PAUSED ARCHIVED ADSET_PAUSED].freeze
 
     # belongs_to ad_account
 

data/lib/facebook_ads/ad_account.rb

@@ -2,7 +2,7 @@ module FacebookAds
   # An ad account has many ad campaigns, ad images, and ad creatives.
   # https://developers.facebook.com/docs/marketing-api/reference/ad-account
   class AdAccount < Base
-    FIELDS = %w(id account_id account_status age created_time currency name).freeze
+    FIELDS = %w[id account_id account_status age created_time currency name].freeze
 
     class << self
       def all(query = {})
@@ -25,15 +25,15 @@ module FacebookAds
     end
 
     def create_ad_campaign(name:, objective:, status: 'ACTIVE')
-      raise Exception, "Objective must be one of: #{AdCampaign::OBJECTIVES.to_sentence}" unless AdCampaign::OBJECTIVES.include?(objective)
-      raise Exception, "Status must be one of: #{AdCampaign::STATUSES.to_sentence}" unless AdCampaign::STATUSES.include?(status)
+      raise Exception, "Objective must be one of: #{AdCampaign::OBJECTIVES.join(', ')}" unless AdCampaign::OBJECTIVES.include?(objective)
+      raise Exception, "Status must be one of: #{AdCampaign::STATUSES.join(', ')}" unless AdCampaign::STATUSES.include?(status)
       query = { name: name, objective: objective, status: status }
       result = AdCampaign.post("/#{id}/campaigns", query: query)
       AdCampaign.find(result['id'])
     end
 
     def create_dynamic_ad_campaign(name:, product_catalog_id:, status: 'ACTIVE')
-      raise Exception, "Status must be one of: #{AdCampaign::STATUSES.to_sentence}" unless AdCampaign::STATUSES.include?(status)
+      raise Exception, "Status must be one of: #{AdCampaign::STATUSES.join(', ')}" unless AdCampaign::STATUSES.include?(status)
       query = { name: name, objective: 'PRODUCT_CATALOG_SALES', status: status, promoted_object: { product_catalog_id: product_catalog_id } }
       result = AdCampaign.post("/#{id}/campaigns", query: query)
       AdCampaign.find(result['id'])
@@ -96,21 +96,43 @@ module FacebookAds
       end.flatten
     end
 
+    def reach_estimate(targeting:, optimization_goal:, currency: 'USD')
+      raise Exception, "Optimization goal must be one of: #{AdSet::OPTIMIZATION_GOALS.join(', ')}" unless AdSet::OPTIMIZATION_GOALS.include?(optimization_goal)
+
+      if targeting.is_a?(AdTargeting)
+        if targeting.validate!
+          targeting = targeting.to_hash
+        else
+          raise Exception, 'The provided targeting spec is not valid.'
+        end
+      end
+
+      query = {
+        targeting_spec: targeting.to_json,
+        optimize_for: optimization_goal,
+        currency: currency
+      }
+      self.class.get("/#{id}/reachestimate", query: query, objectify: false)
+    end
+
     # has_many applications
 
     def applications
       self.class.get("/#{id}/advertisable_applications", objectify: false)
     end
 
-    def create_ad_audience_with_pixel(name:, pixel_id:, event_name:)
+    # hash_many ad_audiences
+
+    def create_ad_audience_with_pixel(name:, pixel_id:, event_name:, subtype: 'WEBSITE', retention_days: 15)
       query = {
-          name: name,
-          pixel_id: pixel_id,
-          subtype: 'WEBSITE',
-          retention_days: 15,
-          rule: { event: { i_contains: event_name } }.to_json,
-          prefill: 1
-        }
+        name: name,
+        pixel_id: pixel_id,
+        subtype: subtype,
+        retention_days: retention_days,
+        rule: { event: { i_contains: event_name } }.to_json,
+        prefill: 1
+      }
+
       result = AdAudience.post("/#{id}/customaudiences", query: query)
       AdAudience.find(result['id'])
     end
@@ -118,29 +140,40 @@ module FacebookAds
     private
 
     def create_carousel_ad_creative(creative)
-      required = %i(name page_id link message assets call_to_action_type multi_share_optimized multi_share_end_card)
+      required = %i[name page_id link message assets call_to_action_type multi_share_optimized multi_share_end_card]
+
       unless (keys = required - creative.keys).length.zero?
-        raise Exception, "Creative is missing the following: #{keys.to_sentence}"
+        raise Exception, "Creative is missing the following: #{keys.join(', ')}"
       end
 
-      raise Exception, "Creative call_to_action_type must be one of: #{AdCreative::CALL_TO_ACTION_TYPES.to_sentence}" unless AdCreative::CALL_TO_ACTION_TYPES.include?(creative[:call_to_action_type])
+      raise Exception, "Creative call_to_action_type must be one of: #{AdCreative::CALL_TO_ACTION_TYPES.join(', ')}" unless AdCreative::CALL_TO_ACTION_TYPES.include?(creative[:call_to_action_type])
+
       query = if creative[:product_set_id].present?
-        AdCreative.product_set(name: creative[:name], page_id: creative[:page_id], link: creative[:link], message: creative[:message], headline: creative[:headline], description: creative[:description], product_set_id: creative[:product_set_id])
+        AdCreative.product_set(
+          name: creative[:name],
+          page_id: creative[:page_id],
+          link: creative[:link],
+          message: creative[:message],
+          headline: creative[:headline],
+          description: creative[:description],
+          product_set_id: creative[:product_set_id]
+        )
       else
         AdCreative.carousel(creative)
       end
+
       result = AdCreative.post("/#{id}/adcreatives", query: query)
       AdCreative.find(result['id'])
     end
 
     def create_image_ad_creative(creative)
-      required = %i(name page_id message link link_title image_hash call_to_action_type)
+      required = %i[name page_id message link link_title image_hash call_to_action_type]
 
       unless (keys = required - creative.keys).length.zero?
-        raise Exception, "Creative is missing the following: #{keys.to_sentence}"
+        raise Exception, "Creative is missing the following: #{keys.join(', ')}"
       end
 
-      raise Exception, "Creative call_to_action_type must be one of: #{AdCreative::CALL_TO_ACTION_TYPES.to_sentence}" unless AdCreative::CALL_TO_ACTION_TYPES.include?(creative[:call_to_action_type])
+      raise Exception, "Creative call_to_action_type must be one of: #{AdCreative::CALL_TO_ACTION_TYPES.join(', ')}" unless AdCreative::CALL_TO_ACTION_TYPES.include?(creative[:call_to_action_type])
       query = AdCreative.photo(creative)
       result = AdCreative.post("/#{id}/adcreatives", query: query)
       AdCreative.find(result['id'])

data/lib/facebook_ads/ad_audience.rb

@@ -1,7 +1,7 @@
 module FacebookAds
   # https://developers.facebook.com/docs/marketing-api/reference/custom-audience
   class AdAudience < Base
-    FIELDS = %w(id account_id subtype name description approximate_count data_source delivery_status external_event_source lookalike_audience_ids lookalike_spec operation_status opt_out_link permission_for_actions pixel_id retention_days rule time_content_updated time_created time_updated).freeze
+    FIELDS = %w[id account_id subtype name description approximate_count data_source delivery_status external_event_source lookalike_audience_ids lookalike_spec operation_status opt_out_link permission_for_actions pixel_id retention_days rule time_content_updated time_created time_updated].freeze
 
     # belongs_to ad_account