facebook_ads 0.1.11 → 0.1.12

data/lib/facebook_ads/ad_campaign.rb

@@ -2,9 +2,51 @@ module FacebookAds
   # An ad campaign has many ad sets and belongs to an ad account.
   # https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group
   class AdCampaign < Base
-    FIELDS     = %w(id account_id buying_type can_use_spend_cap configured_status created_time effective_status name objective start_time stop_time updated_time spend_cap).freeze
-    STATUSES   = %w(ACTIVE PAUSED DELETED PENDING_REVIEW DISAPPROVED PREAPPROVED PENDING_BILLING_INFO CAMPAIGN_PAUSED ARCHIVED ADSET_PAUSED).freeze
-    OBJECTIVES = %w(CONVERSIONS MOBILE_APP_INSTALLS).freeze
+    FIELDS = %w[
+      id
+      account_id
+      buying_type
+      can_use_spend_cap
+      configured_status
+      created_time
+      effective_status
+      name
+      objective
+      start_time
+      stop_time
+      updated_time spend_cap
+    ].freeze
+
+    STATUSES = %w[
+      ACTIVE PAUSED
+      DELETED
+      PENDING_REVIEW
+      DISAPPROVED
+      PREAPPROVED
+      PENDING_BILLING_INFO
+      CAMPAIGN_PAUSED
+      ARCHIVED
+      ADSET_PAUSED
+    ].freeze
+
+    OBJECTIVES = %w[
+      BRAND_AWARENESS
+      CANVAS_APP_ENGAGEMENT
+      CANVAS_APP_INSTALLS
+      EVENT_RESPONSES
+      LEAD_GENERATION
+      LOCAL_AWARENESS
+      MOBILE_APP_ENGAGEMENT
+      MOBILE_APP_INSTALLS
+      NONE
+      OFFER_CLAIMS
+      PAGE_LIKES
+      POST_ENGAGEMENT
+      LINK_CLICKS
+      CONVERSIONS
+      VIDEO_VIEWS
+      PRODUCT_CATALOG_SALES
+    ].freeze
 
     # belongs_to ad_account
 
@@ -19,8 +61,8 @@ module FacebookAds
     end
 
     def create_ad_set(name:, promoted_object:, targeting:, daily_budget:, optimization_goal:, billing_event: 'IMPRESSIONS', status: 'ACTIVE', is_autobid: true)
-      raise Exception, "Optimization goal must be one of: #{AdSet::OPTIMIZATION_GOALS.to_sentence}" unless AdSet::OPTIMIZATION_GOALS.include?(optimization_goal)
-      raise Exception, "Billing event must be one of: #{AdSet::BILLING_EVENTS.to_sentence}" unless AdSet::BILLING_EVENTS.include?(billing_event)
+      raise Exception, "Optimization goal must be one of: #{AdSet::OPTIMIZATION_GOALS.join(', ')}" unless AdSet::OPTIMIZATION_GOALS.include?(optimization_goal)
+      raise Exception, "Billing event must be one of: #{AdSet::BILLING_EVENTS.join(', ')}" unless AdSet::BILLING_EVENTS.include?(billing_event)
 
       if targeting.is_a?(Hash)
         # NOP

data/lib/facebook_ads/ad_creative.rb

@@ -2,8 +2,8 @@ module FacebookAds
   # Ad ad creative has many ad images and belongs to an ad account.
   # https://developers.facebook.com/docs/marketing-api/reference/ad-creative
   class AdCreative < Base
-    FIELDS               = %w(id name object_story_id object_story_spec object_type thumbnail_url run_status).freeze
-    CALL_TO_ACTION_TYPES = %w(SHOP_NOW INSTALL_MOBILE_APP USE_MOBILE_APP SIGN_UP DOWNLOAD BUY_NOW).freeze
+    FIELDS               = %w[id name object_story_id object_story_spec object_type thumbnail_url run_status].freeze
+    CALL_TO_ACTION_TYPES = %w[SHOP_NOW INSTALL_MOBILE_APP USE_MOBILE_APP SIGN_UP DOWNLOAD BUY_NOW].freeze
 
     class << self
       def photo(name:, page_id:, instagram_actor_id: nil, message:, link:, link_title:, image_hash:, call_to_action_type:)
@@ -54,7 +54,6 @@ module FacebookAds
           }
         }
 
-
         {
           name: name,
           object_story_spec: object_story_spec.to_json
@@ -62,7 +61,8 @@ module FacebookAds
       end
 
       def product_set(name:, page_id:, link:, message:, headline:, description:, product_set_id:)
-        { name: name,
+        {
+          name: name,
           object_story_spec: {
             page_id: page_id,
             template_data: {

data/lib/facebook_ads/ad_exception.rb

@@ -1,5 +1,11 @@
 module FacebookAds
   class AdException < StandardError
-    attr_accessor :code, :title, :message
+    attr_reader :code, :title, :message
+
+    def initialize(code:, title:, message:)
+      @code = code
+      @title = title
+      @message = message
+    end
   end
 end

data/lib/facebook_ads/ad_image.rb

@@ -3,7 +3,7 @@ module FacebookAds
   # An image will always produce the same hash.
   # https://developers.facebook.com/docs/marketing-api/reference/ad-image
   class AdImage < Base
-    FIELDS = %w(id hash account_id name permalink_url original_width original_height).freeze
+    FIELDS = %w[id hash account_id name permalink_url original_width original_height].freeze
 
     class << self
       def find(_id)
@@ -11,6 +11,10 @@ module FacebookAds
       end
     end
 
+    # @TODO:
+    # You are setting a key that conflicts with a built-in method FacebookAds::AdImage#hash defined in Hash.
+    # This can cause unexpected behavior when accessing the key via as a property.
+    # You can still access the key via the #[] method.
     def hash
       self[:hash]
     end
@@ -20,7 +24,7 @@ module FacebookAds
     end
 
     def destroy
-      super(path: "/act_#{account_id}/adimages", query: { hash: hash })
+      super(path: "/act_#{account_id}/adimages", query: { hash: self[:hash] })
     end
   end
 end

data/lib/facebook_ads/ad_insight.rb

@@ -4,7 +4,7 @@ module FacebookAds
   # https://developers.facebook.com/docs/marketing-api/insights/overview
   # https://developers.facebook.com/docs/marketing-api/insights/fields/v2.8
   class AdInsight < Base
-    FIELDS = %w(account_id campaign_id adset_id ad_id objective impressions unique_actions cost_per_unique_action_type clicks cpc cpm cpp ctr spend reach relevance_score).freeze
+    FIELDS = %w[account_id campaign_id adset_id ad_id objective impressions unique_actions cost_per_unique_action_type clicks cpc cpm cpp ctr spend reach relevance_score].freeze
 
     class << self
       def find(_id)

data/lib/facebook_ads/ad_product.rb

@@ -1,6 +1,6 @@
 module FacebookAds
   # https://developers.facebook.com/docs/marketing-api/reference/product-item
   class AdProduct < Base
-    FIELDS = %w(id retailer_id name description brand category currency price image_url url).freeze
+    FIELDS = %w[id retailer_id name description brand category currency price image_url url].freeze
   end
 end

data/lib/facebook_ads/ad_product_catalog.rb

@@ -1,7 +1,7 @@
 module FacebookAds
   # https://developers.facebook.com/docs/marketing-api/reference/product-catalog
   class AdProductCatalog < Base
-    FIELDS = %w(id name vertical product_count feed_count).freeze
+    FIELDS = %w[id name vertical product_count feed_count].freeze
 
     class << self
       def all(query = {})

data/lib/facebook_ads/ad_product_feed.rb

@@ -1,6 +1,6 @@
 module FacebookAds
   # https://developers.facebook.com/docs/marketing-api/reference/product-feed
   class AdProductFeed < Base
-    FIELDS = %w(id country created_time default_currency deletion_enabled delimiter encoding file_name latest_upload name product_count quoted_fields_mode schedule).freeze
+    FIELDS = %w[id country created_time default_currency deletion_enabled delimiter encoding file_name latest_upload name product_count quoted_fields_mode schedule].freeze
   end
 end

data/lib/facebook_ads/ad_product_set.rb

@@ -1,6 +1,6 @@
 module FacebookAds
   # https://developers.facebook.com/docs/marketing-api/reference/product-set
   class AdProductSet < Base
-    FIELDS = %w(id auto_creation_url filter name product_catalog product_count).freeze
+    FIELDS = %w[id auto_creation_url filter name product_catalog product_count].freeze
   end
 end

data/lib/facebook_ads/ad_set.rb

@@ -20,7 +20,7 @@ module FacebookAds
     # ).freeze
 
     # Fields we might actually care about:
-    FIELDS = %w(
+    FIELDS = %w[
       id account_id campaign_id
       name
       status configured_status effective_status
@@ -29,11 +29,11 @@ module FacebookAds
       promoted_object
       targeting
       created_time updated_time
-    ).freeze
+    ].freeze
 
-    STATUSES           = %w(ACTIVE PAUSED DELETED PENDING_REVIEW DISAPPROVED PREAPPROVED PENDING_BILLING_INFO CAMPAIGN_PAUSED ARCHIVED ADSET_PAUSED).freeze
-    BILLING_EVENTS     = %w(APP_INSTALLS IMPRESSIONS).freeze
-    OPTIMIZATION_GOALS = %w(APP_INSTALLS OFFSITE_CONVERSIONS).freeze
+    STATUSES           = %w[ACTIVE PAUSED DELETED PENDING_REVIEW DISAPPROVED PREAPPROVED PENDING_BILLING_INFO CAMPAIGN_PAUSED ARCHIVED ADSET_PAUSED].freeze
+    BILLING_EVENTS     = %w[APP_INSTALLS IMPRESSIONS].freeze
+    OPTIMIZATION_GOALS = %w[APP_INSTALLS OFFSITE_CONVERSIONS].freeze
 
     # belongs_to ad_account
 

data/lib/facebook_ads/ad_targeting.rb

@@ -7,8 +7,8 @@ module FacebookAds
     ANDROID_OS         = 'Android'.freeze
     APPLE_OS           = 'iOS'.freeze
     OSES               = [ANDROID_OS, APPLE_OS].freeze
-    ANDROID_DEVICES    = %w(Android_Smartphone Android_Tablet).freeze
-    APPLE_DEVICES      = %w(iPhone iPad iPod).freeze
+    ANDROID_DEVICES    = %w[Android_Smartphone Android_Tablet].freeze
+    APPLE_DEVICES      = %w[iPhone iPad iPod].freeze
     DEVICES            = ANDROID_DEVICES + APPLE_DEVICES
     INSTALLED          = 'installed'.freeze
     NOT_INSTALLED      = 'not_installed'.freeze
@@ -53,7 +53,7 @@ module FacebookAds
         user_os: user_os,
         user_device: user_device,
         app_install_state: app_install_state
-      }.compact
+      }.reject { |_k, v| v.nil? }
     end
   end
 end

data/lib/facebook_ads/base.rb

@@ -11,7 +11,7 @@ module FacebookAds
         uri = "#{FacebookAds.base_uri}#{path}?" + build_nested_query(query)
         FacebookAds.logger.debug "GET #{uri}"
         response = begin
-          RestClient.get(uri)
+          RestClient.get(uri, accept: :json, accept_encoding: :identity)
         rescue RestClient::Exception => e
           exception(:get, path, e)
         end
@@ -75,6 +75,7 @@ module FacebookAds
 
         hash.each_pair do |key, value|
           # https://github.com/intridea/hashie/blob/master/lib/hashie/mash.rb#L111
+          # key = '_hash' if key == 'hash'
           object.custom_writer(key, value, false)
         end
 
@@ -137,15 +138,15 @@ module FacebookAds
           begin
             if (error = JSON.parse(response)['error']).nil?
               response
+            elsif error['error_subcode'].nil? || error['error_user_title'].nil? || error['error_user_msg'].nil?
+              "#{error['type']} / #{error['code']}: #{error['message']}"
             else
-              if error['error_subcode'].nil? ||
-                 error['error_user_title'].nil? ||
-                 error['error_user_msg'].nil?
-                "#{error['type']} / #{error['code']}: #{error['message']}"
-              else
-                exception = AdException.new(code: error['error_subcode'], title: error['error_user_title'], message: error['error_user_msg'])
-                "#{error['error_subcode']} / #{error['error_user_title']}: #{error['error_user_msg']}"
-              end
+              exception = AdException.new(
+                code: error['error_subcode'],
+                title: error['error_user_title'],
+                message: error['error_user_msg']
+              )
+              "#{exception.code} / #{exception.title}: #{exception.message}"
             end
           rescue JSON::ParserError
             response

data/spec/facebook_ads/ad_account_spec.rb

@@ -0,0 +1,93 @@
+require 'spec_helper'
+
+# FACEBOOK_ACCESS_TOKEN=... rspec spec/facebook_ads/ad_account_spec.rb
+describe FacebookAds::AdAccount do
+  let(:account) do
+    FacebookAds::AdAccount.new(
+      id: 'act_10152335766987003',
+      account_id: '10152335766987003',
+      account_status: 1,
+      age: 466.0,
+      created_time: '2014-10-24T14:38:31-0700',
+      currency: 'USD',
+      name: 'Chris Estreich'
+    )
+  end
+
+  describe '#all' do
+    it 'lists all accounts', :vcr do
+      accounts = FacebookAds::AdAccount.all
+      verify(format: :json) { JSON.dump(accounts) }
+    end
+  end
+
+  describe '#find_by' do
+    it 'finds a specific account', :vcr do
+      account = FacebookAds::AdAccount.find_by(name: 'iOS')
+      verify(format: :json) { JSON.dump(account) }
+    end
+  end
+
+  describe '.ad_campaigns' do
+    it 'lists campaigns', :vcr do
+      ad_campaigns = account.ad_campaigns
+      verify(format: :json) { JSON.dump(ad_campaigns) }
+    end
+  end
+
+  describe '.create_ad_campaign' do
+    it 'creates a new ad campaign', :vcr do
+      ad_campaign = account.create_ad_campaign(name: 'Test', objective: 'MOBILE_APP_INSTALLS')
+      verify(format: :json) { JSON.dump(ad_campaign) }
+    end
+  end
+
+  describe '.ad_images' do
+    it 'lists images', :vcr do
+      ad_images = account.ad_images(hashes: %w[d8fc613662fb5ef6cf5fb9d1fe779315])
+      verify(format: :json) { JSON.dump(ad_images) }
+      expect(ad_images.first.hash).to eq('d8fc613662fb5ef6cf5fb9d1fe779315')
+    end
+  end
+
+  describe '.create_ad_images' do
+    it 'creates an image', :vcr do
+      ad_images = account.create_ad_images(['https://img0.etsystatic.com/108/1/13006112/il_570xN.1047856494_l2gp.jpg'])
+      verify(format: :json) { JSON.dump(ad_images) }
+      expect(ad_images.first.hash).to eq('d8fc613662fb5ef6cf5fb9d1fe779315')
+    end
+  end
+
+  describe '.ad_creatives' do
+    it 'lists creatives', :vcr do
+      ad_creatives = account.ad_creatives
+      verify(format: :json) { JSON.dump(ad_creatives) }
+    end
+  end
+
+  describe '.ad_sets' do
+    it 'lists ad sets', :vcr do
+      ad_sets = account.ad_sets
+      verify(format: :json) { JSON.dump(ad_sets) }
+    end
+  end
+
+  describe '.ads' do
+    it 'lists ads', :vcr do
+      ads = account.ads
+      verify(format: :json) { JSON.dump(ads) }
+    end
+  end
+
+  describe '.reach_estimate' do
+    it 'estimates the reach of a targeting spec', :vcr do
+      targeting = FacebookAds::AdTargeting.new
+      targeting.genders = [FacebookAds::AdTargeting::WOMEN]
+      targeting.age_min = 18
+      targeting.age_max = 20
+      targeting.countries = ['US']
+      reach = account.reach_estimate(targeting: targeting, optimization_goal: 'OFFSITE_CONVERSIONS')
+      verify(format: :json) { JSON.dump(reach) }
+    end
+  end
+end

data/spec/facebook_ads/ad_campaign_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+# FACEBOOK_ACCESS_TOKEN=... rspec spec/facebook_ads/ad_campaign_spec.rb
+describe FacebookAds::AdCampaign do
+  xdescribe '.ad_sets' do
+  end
+
+  xdescribe '.create_ad_set' do
+  end
+
+  describe '.destroy' do
+    it 'creates a new ad campaign', :vcr do
+      ad_campaign = FacebookAds::AdCampaign.find('6076262142242')
+      expect(ad_campaign.destroy).to be(true)
+      ad_campaign = FacebookAds::AdCampaign.find(ad_campaign.id)
+      expect(ad_campaign.effective_status).to eq('DELETED')
+    end
+  end
+end

data/spec/facebook_ads/ad_creative_spec.rb

@@ -0,0 +1,4 @@
+require 'spec_helper'
+
+describe FacebookAds::AdCreative do
+end

data/spec/facebook_ads/ad_image_spec.rb

@@ -0,0 +1,4 @@
+require 'spec_helper'
+
+describe FacebookAds::AdImage do
+end

data/spec/facebook_ads/ad_insight_spec.rb

@@ -0,0 +1,4 @@
+require 'spec_helper'
+
+describe FacebookAds::AdInsight do
+end

data/spec/facebook_ads/ad_product_catalog_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+describe FacebookAds::AdProductCatalog do
+  # def test_all
+  #   vcr do
+  #     catalog = FacebookAds::AdProductCatalog.all.first
+  #     assert_equal '197871307315718', catalog.id
+  #     assert_equal 'Test', catalog.name
+  #     assert_equal 'commerce', catalog.vertical
+  #     assert_equal 1, catalog.product_count
+  #     assert_equal 1, catalog.feed_count
+  #   end
+  # end
+  #
+  # def test_create
+  #   vcr do
+  #     catalog = FacebookAds::AdProductCatalog.create(name: 'Foo Bar')
+  #     assert_equal 'Foo Bar', catalog.name
+  #     assert_equal 'commerce', catalog.vertical
+  #     assert_equal 0, catalog.product_count
+  #     assert_equal 0, catalog.feed_count
+  #     catalog = FacebookAds::AdProductCatalog.find(catalog.id)
+  #     assert_equal true, catalog.destroy
+  #     assert_nil FacebookAds::AdProductCatalog.find_by(name: 'Foo Bar')
+  #   end
+  # end
+end

data/spec/facebook_ads/ad_product_feed_spec.rb

@@ -0,0 +1,4 @@
+require 'spec_helper'
+
+describe FacebookAds::AdProductFeed do
+end

data/spec/facebook_ads/ad_product_set_spec.rb

@@ -0,0 +1,4 @@
+require 'spec_helper'
+
+describe FacebookAds::AdProductSet do
+end