facebook_ads 0.1.5 → 0.1.7

data/lib/facebook_ads/ad_insight.rb

@@ -2,23 +2,22 @@ module FacebookAds
   # Ad insights exist for ad accounts, ad campaigns, ad sets, and ads.
   # A lot more can be done here.
   # 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(ad_id objective impressions unique_actions cost_per_unique_action_type clicks cpc cpm ctr spend)
+    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)
+      def find(_id)
         raise Exception, 'NOT IMPLEMENTED'
       end
     end
 
-    def update(data)
+    def update(_data)
       raise Exception, 'NOT IMPLEMENTED'
     end
 
     def destroy
       raise Exception, 'NOT IMPLEMENTED'
     end
-
   end
 end

data/lib/facebook_ads/ad_product.rb

@@ -0,0 +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
+  end
+end

data/lib/facebook_ads/ad_product_catalog.rb

@@ -0,0 +1,60 @@
+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
+
+    class << self
+      def all
+        get("/#{FacebookAds.business_id}/product_catalogs", objectify: true)
+      end
+
+      def find_by(conditions)
+        all.detect do |object|
+          conditions.all? do |key, value|
+            object.send(key) == value
+          end
+        end
+      end
+
+      def create(name:)
+        catalog = post("/#{FacebookAds.business_id}/product_catalogs", query: { name: name }, objectify: true)
+        find(catalog.id)
+      end
+    end
+
+    # has_many ad_product_feeds
+
+    def ad_product_feeds
+      AdProductFeed.paginate("/#{id}/product_feeds")
+    end
+
+    # catalog.create_ad_product_feed(name: 'Test', schedule: { url: 'https://tophatter.com/admin/ad_automation/ad_product_feeds/1.csv', interval: 'HOURLY' })
+    def create_ad_product_feed(name:, schedule:)
+      feed = AdProductCatalog.post("/#{id}/product_feeds", query: { name: name, schedule: schedule }, objectify: true)
+      AdProductFeed.find(feed.id)
+    end
+
+    # has_many product_groups
+
+    # def ad_product_groups
+    #   AdProductGroup.paginate("/#{id}/product_groups")
+    # end
+
+    # has_many product_sets
+
+    # def ad_product_sets
+    #   AdProductSet.paginate("/#{id}/product_sets")
+    # end
+
+    # has_many ad_products
+
+    def ad_products
+      AdProduct.paginate("/#{id}/products")
+    end
+
+    def create_ad_product(data)
+      product = AdProductCatalog.post("/#{id}/products", query: data, objectify: true)
+      AdProduct.find(product.id)
+    end
+  end
+end

data/lib/facebook_ads/ad_product_feed.rb

@@ -0,0 +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
+  end
+end

data/lib/facebook_ads/ad_product_set.rb

@@ -0,0 +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
+  end
+end

data/lib/facebook_ads/ad_set.rb

@@ -2,34 +2,32 @@ module FacebookAds
   # An ad set belongs to a campaign and has many ads.
   # https://developers.facebook.com/docs/marketing-api/reference/ad-campaign
   class AdSet < Base
-
-    FIELDS             = %w(id account_id campaign_id adlabels adset_schedule bid_amount bid_info billing_event configured_status created_time creative_sequence effective_status end_time frequency_cap frequency_cap_reset_period frequency_control_specs is_autobid lifetime_frequency_cap lifetime_imps name optimization_goal promoted_object rf_prediction_id rtb_flag start_time targeting updated_time use_new_app_click pacing_type budget_remaining daily_budget lifetime_budget)
-    STATUSES           = %w(ACTIVE PAUSED DELETED PENDING_REVIEW DISAPPROVED PREAPPROVED PENDING_BILLING_INFO CAMPAIGN_PAUSED ARCHIVED ADSET_PAUSED)
-    BILLING_EVENTS     = %w(APP_INSTALLS IMPRESSIONS) # %w(CLICKS LINK_CLICKS OFFER_CLAIMS PAGE_LIKES POST_ENGAGEMENT VIDEO_VIEWS)
-    OPTIMIZATION_GOALS = %w(APP_INSTALLS OFFSITE_CONVERSIONS) # %w(NONE BRAND_AWARENESS CLICKS ENGAGED_USERS EXTERNAL EVENT_RESPONSES IMPRESSIONS LEAD_GENERATION LINK_CLICKS OFFER_CLAIMS PAGE_ENGAGEMENT PAGE_LIKES POST_ENGAGEMENT REACH SOCIAL_IMPRESSIONS VIDEO_VIEWS)
+    FIELDS             = %w(id account_id campaign_id adlabels adset_schedule bid_amount bid_info billing_event configured_status created_time creative_sequence effective_status end_time frequency_cap frequency_cap_reset_period frequency_control_specs is_autobid lifetime_frequency_cap lifetime_imps name optimization_goal promoted_object rf_prediction_id rtb_flag start_time targeting updated_time use_new_app_click pacing_type budget_remaining daily_budget lifetime_budget).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
 
     def ad_account
-      @ad_set ||= FacebookAds::AdAccount.find(account_id)
+      @ad_account ||= AdAccount.find("act_#{account_id}")
     end
 
     # belongs_to ad_campaign
 
     def ad_campaign
-      @campaign ||= FacebookAds::AdCampaign.find(campaign_id)
+      @campaign ||= AdCampaign.find(campaign_id)
     end
 
     # has_many ads
 
     def ads(effective_status: ['ACTIVE'], limit: 100)
-      FacebookAds::Ad.paginate("/#{id}/ads", query: { effective_status: effective_status, limit: limit })
+      Ad.paginate("/#{id}/ads", query: { effective_status: effective_status, limit: limit })
     end
 
     def create_ad(name:, creative_id:)
-      ad = FacebookAds::Ad.post("/act_#{account_id}/ads", query: { name: name, adset_id: id, creative: { creative_id: creative_id }.to_json }, objectify: true) # Returns a FacebookAds::Ad instance.
-      FacebookAds::Ad.find(ad.id)
+      ad = Ad.post("/act_#{account_id}/ads", query: { name: name, adset_id: id, creative: { creative_id: creative_id }.to_json }, objectify: true) # Returns an Ad instance.
+      Ad.find(ad.id)
     end
-
   end
 end

data/lib/facebook_ads/ad_targeting.rb

@@ -1,35 +1,34 @@
-# https://developers.facebook.com/docs/marketing-api/targeting-specs
 module FacebookAds
+  # https://developers.facebook.com/docs/marketing-api/targeting-specs
   class AdTargeting
-
     MEN                = 1
     WOMEN              = 2
-    GENDERS            = [MEN, WOMEN]
-    ANDROID_OS         = 'Android'
-    APPLE_OS           = 'iOS'
-    OSES               = [ANDROID_OS, APPLE_OS]
-    ANDROID_DEVICES    = %w(Android_Smartphone Android_Tablet)
-    APPLE_DEVICES      = %w(iPhone iPad iPod)
+    GENDERS            = [MEN, WOMEN].freeze
+    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
     DEVICES            = ANDROID_DEVICES + APPLE_DEVICES
-    INSTALLED          = 'installed'
-    NOT_INSTALLED      = 'not_installed'
-    APP_INSTALL_STATES = [INSTALLED, NOT_INSTALLED]
+    INSTALLED          = 'installed'.freeze
+    NOT_INSTALLED      = 'not_installed'.freeze
+    APP_INSTALL_STATES = [INSTALLED, NOT_INSTALLED].freeze
 
     attr_accessor :genders, :age_min, :age_max, :countries, :user_os, :user_device, :app_install_state
 
     def initialize
-      # self.genders           = [WOMEN] # If nil, defaults to all genders.
-      # self.age_min           = 18 # If nil, defaults to 18.
-      # self.age_max           = 65 # If nil, defaults to 65+.
-      self.countries         = ['US']
-      # self.user_os           = [ANDROID_OS]
-      # self.user_device       = ANDROID_DEVICES
+      # self.genders = [WOMEN] # If nil, defaults to all genders.
+      # self.age_min = 18 # If nil, defaults to 18.
+      # self.age_max = 65 # If nil, defaults to 65+.
+      self.countries = ['US']
+      # self.user_os = [ANDROID_OS]
+      # self.user_device = ANDROID_DEVICES
       # self.app_install_state = NOT_INSTALLED
     end
 
     def validate!
       { gender: genders, countries: countries, user_os: user_os, user_device: user_device }.each_pair do |key, array|
-        if array.present? && !array.is_a?(Array)
+        if !array.nil? && !array.is_a?(Array)
           raise Exception, "#{self.class.name}: #{key} must be an array"
         end
       end
@@ -37,8 +36,8 @@ module FacebookAds
       { genders: [genders, GENDERS], user_os: [user_os, OSES], user_device: [user_device, DEVICES] }.each_pair do |key, provided_and_acceptable|
         provided, acceptable = provided_and_acceptable
 
-        if provided.present? && (invalid = provided.detect { |value| !acceptable.include?(value) }).present?
-          raise Exception, "#{self.class.name}: #{bad} is an invalid #{key}"
+        if !provided.nil? && !(invalid = provided.detect { |value| !acceptable.include?(value) }).nil?
+          raise Exception, "#{self.class.name}: #{invalid} is an invalid #{key}"
         end
       end
 
@@ -56,6 +55,5 @@ module FacebookAds
         app_install_state: app_install_state
       }.compact
     end
-
   end
 end

data/lib/facebook_ads/base.rb

@@ -1,47 +1,70 @@
 module FacebookAds
+  # The base class for all ads objects.
   class Base < Hashie::Mash
-
     class << self
-
       def find(id)
         get("/#{id}", objectify: true)
       end
 
       def get(path, query: {}, objectify:)
         query = pack(query, objectify) # Adds access token, fields, etc.
-        FacebookAds.logger.debug "GET #{FacebookAds.base_uri}#{path}?#{query.to_query}"
-        response = HTTParty.get("#{FacebookAds.base_uri}#{path}", query: query).parsed_response
-        response = unpack(response, objectify: objectify)
+        uri = "#{FacebookAds.base_uri}#{path}?" + build_nested_query(query)
+        FacebookAds.logger.debug "GET #{uri}"
+        response = begin
+          RestClient.get(uri)
+        rescue RestClient::Exception => e
+          exception(:get, path, e)
+        end
+        unpack(response, objectify: objectify)
       end
 
       def post(path, query: {}, objectify:)
         query = pack(query, objectify)
-        FacebookAds.logger.debug "POST #{FacebookAds.base_uri}#{path}?#{query.to_query}"
-        response = HTTMultiParty.post("#{FacebookAds.base_uri}#{path}", query: query).parsed_response
-        response = unpack(response, objectify: objectify)
+        uri = "#{FacebookAds.base_uri}#{path}"
+        FacebookAds.logger.debug "POST #{uri} #{query}"
+        response = begin
+          RestClient.post(uri, query)
+        rescue RestClient::Exception => e
+          exception(:post, path, e)
+        end
+        unpack(response, objectify: objectify)
       end
 
       def delete(path, query: {})
         query = pack(query, false)
-        FacebookAds.logger.debug "DELETE #{FacebookAds.base_uri}#{path}?#{query.to_query}"
-        response = HTTParty.delete("#{FacebookAds.base_uri}#{path}", query: query).parsed_response
-        response = unpack(response, objectify: false)
+        uri = "#{FacebookAds.base_uri}#{path}?" + build_nested_query(query)
+        FacebookAds.logger.debug "DELETE #{uri}"
+        response = begin
+          RestClient.delete(uri)
+        rescue RestClient::Exception => e
+          exception(:delete, path, e)
+        end
+        unpack(response, objectify: false)
       end
 
       def paginate(path, query: {})
+        query[:limit] ||= 100
+        limit = query[:limit]
         response = get(path, query: query.merge(fields: self::FIELDS.join(',')), objectify: false)
-        data = response['data'].present? ? response['data'] : []
-
-        while (paging = response['paging']).present? && (url = paging['next']).present?
-          FacebookAds.logger.debug "GET #{url}"
-          response = HTTParty.get(url).parsed_response # This should be raw since the URL has the host already.
-          data += response['data'] if response['data'].present?
+        data = response['data'].nil? ? [] : response['data']
+
+        if data.length == limit
+          while !(paging = response['paging']).nil? && !(url = paging['next']).nil?
+            FacebookAds.logger.debug "GET #{url}"
+            response = begin
+              RestClient.get(url)
+            rescue RestClient::Exception => e
+              exception(:get, url, e)
+            end
+            response = unpack(response, objectify: false)
+            data += response['data'] unless response['data'].nil?
+          end
         end
 
-        if data.present?
-          data.map { |hash| instantiate(hash) }
-        else
+        if data.nil?
           []
+        else
+          data.map { |hash| instantiate(hash) }
         end
       end
 
@@ -61,75 +84,98 @@ module FacebookAds
       def pack(hash, objectify)
         hash = hash.merge(access_token: FacebookAds.access_token)
         hash = hash.merge(fields: self::FIELDS.join(',')) if objectify
-        hash.compact
+        hash.delete_if { |_k, v| v.nil? }
       end
 
       def unpack(response, objectify:)
-        if response.nil? || !response.is_a?(Hash)
-          raise Exception, "Invalid response: #{response.inspect}"
+        raise Exception, 'Invalid nil response' if response.nil?
+        response = response.body if response.is_a?(RestClient::Response)
+
+        if response.is_a?(String)
+          response = begin
+            JSON.parse(response)
+          rescue JSON::ParserError
+            raise Exception, "Invalid JSON response: #{response.inspect}"
+          end
         end
 
-        if response['error'].present?
-          # Let's have different Exception subclasses for different error codes.
-          raise Exception, "#{response['error']['code']}: #{response['error']['message']} | #{response.inspect}"
-        end
+        raise Exception, "Invalid response: #{response.inspect}" unless response.is_a?(Hash)
+        raise Exception, "[#{response['error']['code']}] #{response['error']['message']} - raw response: #{response.inspect}" unless response['error'].nil?
+        return response unless objectify
 
-        if objectify
-          if response.key?('data') && (data = response['data']).is_a?(Array)
-            data.map { |hash| instantiate(hash) }
-          else
-            instantiate(response)
-          end
+        if response.key?('data') && (data = response['data']).is_a?(Array)
+          data.map { |hash| instantiate(hash) }
         else
-          response
+          instantiate(response)
         end
       end
 
-    end
-
-    def update(data)
-      if data.present?
-        response = self.class.post("/#{id}", query: data, objectify: false)
+      def escape(s)
+        URI.encode_www_form_component(s)
+      end
 
-        if response.is_a?(Hash) && response.key?('success')
-          response['success']
+      # https://github.com/rack/rack/blob/master/lib/rack/utils.rb
+      def build_nested_query(value, prefix = nil)
+        case value
+        when Array
+          value.map { |v| build_nested_query(v, "#{prefix}[]") }.join('&')
+        when Hash
+          value.map { |k, v| build_nested_query(v, prefix ? "#{prefix}[#{escape(k)}]" : escape(k)) }.reject(&:empty?).join('&')
+        when nil
+          prefix
         else
-          raise Exception, "Invalid response from update: #{response.inspect}"
+          raise ArgumentError, 'value must be a Hash' if prefix.nil?
+          "#{prefix}=#{escape(value)}"
         end
-      else
-        false
       end
-    end
 
-    def save
-      if changes.present?
-        data = {}
-        changes.keys.each { |key| data[key] = self[key] }
-
-        if update(data)
-          self.class.find(id)
+      def exception(verb, path, e)
+        if e.response.is_a?(String)
+          begin
+            hash    = JSON.parse(e.response)
+            error   = hash['error']
+            message = error.nil? ? hash.inspect : "#{error['type']} code=#{error['code']} message=#{error['message']}"
+          rescue JSON::ParserError
+            message = e.response.first(100)
+          end
         else
-          nil
+          message = e.response.inspect
         end
-      else
-        nil
+
+        FacebookAds.logger.error "#{verb.upcase} #{path} [#{e.message}] #{message}"
+        raise e
       end
     end
 
+    def update(data)
+      return false if data.nil?
+      response = self.class.post("/#{id}", query: data, objectify: false)
+      raise Exception, "Invalid response from update: #{response.inspect}" unless @response.is_a?(Hash) && response.key?('success')
+      response['success']
+    end
+
+    def save
+      return nil if changes.nil? || changes.length.zero?
+      data = {}
+      changes.keys.each { |key| data[key] = self[key] }
+      return nil unless update(data)
+      self.class.find(id)
+    end
+
     def destroy(path: nil, query: {})
       response = self.class.delete(path || "/#{id}", query: query)
-
-      if response.key?('success')
-        response['success']
-      else
-        raise Exception, "Invalid response from destroy: #{response.inspect}"
-      end
+      raise Exception, "Invalid response from destroy: #{response.inspect}" unless response.key?('success')
+      response['success']
     end
 
     protected
 
     attr_accessor :changes
 
+    def persisted?
+      !id.nil?
+    end
+
     private
 
     def []=(key, value)
@@ -146,6 +192,5 @@ module FacebookAds
 
       new_values
     end
-
   end
 end