facebook_ads 0.1.5 → 0.1.7

data/lib/facebook_ads.rb

@@ -1,7 +1,8 @@
 # External requires.
-require 'active_support/all'
-require 'httmultiparty'
+require 'json'
+require 'rest-client'
 require 'hashie'
+require 'logger'
 
 # Internal requires.
 require 'facebook_ads/base'
@@ -9,7 +10,6 @@ Dir[File.expand_path('../facebook_ads/*.rb', __FILE__)].each { |f| require f }
 
 # The primary namespace for this gem.
 module FacebookAds
-
   def self.logger=(logger)
     @logger = logger
   end
@@ -28,10 +28,7 @@ module FacebookAds
   end
 
   def self.base_uri
-    unless defined?(@base_uri)
-      @base_uri = 'https://graph.facebook.com/v2.6'
-    end
-
+    @base_uri = 'https://graph.facebook.com/v2.8' unless defined?(@base_uri)
     @base_uri
   end
 
@@ -43,4 +40,11 @@ module FacebookAds
     @access_token
   end
 
+  def self.business_id=(business_id)
+    @business_id = business_id
+  end
+
+  def self.business_id
+    @business_id
+  end
 end

data/lib/facebook_ads/ad.rb

@@ -2,33 +2,31 @@ 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)
-    STATUSES = %w(ACTIVE PAUSED DELETED PENDING_REVIEW DISAPPROVED PREAPPROVED PENDING_BILLING_INFO CAMPAIGN_PAUSED ARCHIVED ADSET_PAUSED)
+    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
 
     def ad_account
-      @ad_set ||= FacebookAds::AdAccount.find(account_id)
+      @ad_set ||= AdAccount.find(account_id)
     end
 
     # belongs_to ad_campaign
 
     def ad_campaign
-      @ad_set ||= FacebookAds::AdCampaign.find(campaign_id)
+      @ad_set ||= AdCampaign.find(campaign_id)
     end
 
     # belongs_to ad_set
 
     def ad_set
-      @ad_set ||= FacebookAds::AdSet.find(adset_id)
+      @ad_set ||= AdSet.find(adset_id)
     end
 
     # belongs_to ad_creative
 
     def ad_creative
-      @ad_creative ||= FacebookAds::AdCreative.find(creative['id'])
+      @ad_creative ||= AdCreative.find(creative['id'])
     end
-
   end
 end

data/lib/facebook_ads/ad_account.rb

@@ -2,8 +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 last_used_time)
+    FIELDS = %w(id account_id account_status age created_time currency name).freeze
 
     class << self
       def all
@@ -11,9 +10,9 @@ module FacebookAds
       end
 
       def find_by(conditions)
-        all.detect do |ad_account|
+        all.detect do |object|
           conditions.all? do |key, value|
-            ad_account.send(key) == value
+            object.send(key) == value
           end
         end
       end
@@ -22,90 +21,63 @@ module FacebookAds
     # has_many campaigns
 
     def ad_campaigns(effective_status: ['ACTIVE'], limit: 100)
-      FacebookAds::AdCampaign.paginate("/#{id}/campaigns", query: { effective_status: effective_status, limit: limit })
+      AdCampaign.paginate("/#{id}/campaigns", query: { effective_status: effective_status, limit: limit })
     end
 
     def create_ad_campaign(name:, objective:, status: 'ACTIVE')
-      raise Exception, "Objective must be one of: #{FacebookAds::AdCampaign::OBJECTIVES.to_sentence}" unless FacebookAds::AdCampaign::OBJECTIVES.include?(objective)
-      raise Exception, "Status must be one of: #{FacebookAds::AdCampaign::STATUSES.to_sentence}" unless FacebookAds::AdCampaign::STATUSES.include?(status)
-      campaign = FacebookAds::AdCampaign.post("/#{id}/campaigns", query: { name: name, objective: objective, status: status }, objectify: true)
-      FacebookAds::AdCampaign.find(campaign.id)
+      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)
+      campaign = AdCampaign.post("/#{id}/campaigns", query: { name: name, objective: objective, status: status }, objectify: true)
+      AdCampaign.find(campaign.id)
     end
 
     # has_many ad_images
 
     def ad_images(hashes: nil, limit: 100)
-      if hashes.present?
-        FacebookAds::AdImage.get("/#{id}/adimages", query: { hashes: hashes }, objectify: true)
+      if !hashes.nil?
+        AdImage.get("/#{id}/adimages", query: { hashes: hashes }, objectify: true)
       else
-        FacebookAds::AdImage.paginate("/#{id}/adimages", query: { limit: limit })
+        AdImage.paginate("/#{id}/adimages", query: { limit: limit })
       end
     end
 
     def create_ad_images(urls)
-      files = urls.collect do |url|
-        pathname = Pathname.new(url)
-        name = "#{pathname.dirname.basename}.jpg"
-        data = HTTParty.get(url).body
-        file = File.open("/tmp/#{name}", 'w') # Assume *nix-based system.
-        file.binmode
-        file.write(data)
-        file.close
-        [name, File.open(file.path)]
+      files = urls.map do |url|
+        name, path = download(url)
+        [name, File.open(path)]
       end.to_h
 
-      response = FacebookAds::AdImage.post("/#{id}/adimages", query: files, objectify: false)
+      response = AdImage.post("/#{id}/adimages", query: files, objectify: false)
       files.values.each { |file| File.delete(file.path) }
-
-      if response['images'].present?
-        hashes = response['images'].map { |key, hash| hash['hash'] }
-        ad_images(hashes: hashes)
-      else
-        []
-      end
+      !response['images'].nil? ? ad_images(hashes: response['images'].map { |_key, hash| hash['hash'] }) : []
     end
 
     # has_many ad_creatives
 
     def ad_creatives(limit: 100)
-      FacebookAds::AdCreative.paginate("/#{id}/adcreatives", query: { limit: limit })
+      AdCreative.paginate("/#{id}/adcreatives", query: { limit: limit })
     end
 
     def create_ad_creative(creative, carousel: true)
-      optional = %i(instagram_actor_id)
-
-      required = if carousel
-        %i(name page_id link message assets call_to_action_type multi_share_optimized multi_share_end_card)
-      else
-        %i(name page_id message link link_title image_hash call_to_action_type)
-      end
-
-      if (keys = required - creative.keys).present?
-        raise Exception, "Creative is missing the following: #{keys.to_sentence}"
-      end
-
-      raise Exception, "Creative call_to_action_type must be one of: #{FacebookAds::AdCreative::CALL_TO_ACTION_TYPES.to_sentence}" unless FacebookAds::AdCreative::CALL_TO_ACTION_TYPES.include?(creative[:call_to_action_type])
-
-      query = if carousel
-        FacebookAds::AdCreative.carousel(creative)
-      else
-        FacebookAds::AdCreative.photo(creative)
-      end
-
-      creative = FacebookAds::AdCreative.post("/#{id}/adcreatives", query: query, objectify: true) # Returns a FacebookAds::AdCreative instance.
-      FacebookAds::AdCreative.find(creative.id)
+      carousel ? create_carousel_ad_creative(creative) : create_image_ad_creative(creative)
     end
 
     # has_many ad_sets
 
     def ad_sets(effective_status: ['ACTIVE'], limit: 100)
-      FacebookAds::AdSet.paginate("/#{id}/adsets", query: { effective_status: effective_status, limit: limit })
+      AdSet.paginate("/#{id}/adsets", query: { effective_status: effective_status, limit: limit })
     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
+
+    # has_many ad_audiences
+
+    def ad_audiences
+      AdAudience.paginate("/#{id}/customaudiences")
     end
 
     # has_many ad_insights
@@ -122,5 +94,44 @@ module FacebookAds
       self.class.get("/#{id}/advertisable_applications", objectify: false)
     end
 
+    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)
+
+      unless (keys = required - creative.keys).length.zero?
+        raise Exception, "Creative is missing the following: #{keys.to_sentence}"
+      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])
+      query = AdCreative.carousel(creative)
+      creative = AdCreative.post("/#{id}/adcreatives", query: query, objectify: true) # Returns an AdCreative instance.
+      AdCreative.find(creative.id)
+    end
+
+    def create_image_ad_creative(creative)
+      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}"
+      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])
+      query = AdCreative.photo(creative)
+      creative = AdCreative.post("/#{id}/adcreatives", query: query, objectify: true) # Returns an AdCreative instance.
+      AdCreative.find(creative.id)
+    end
+
+    def download(url)
+      pathname = Pathname.new(url)
+      name = "#{pathname.dirname.basename}.jpg"
+      # @FIXME: Need to handle exception here.
+      data = RestClient.get(url).body
+      file = File.open("/tmp/#{name}", 'w') # Assume *nix-based system.
+      file.binmode
+      file.write(data)
+      file.close
+      [name, file.path]
+    end
   end
 end

data/lib/facebook_ads/ad_audience.rb

@@ -0,0 +1,22 @@
+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
+
+    # belongs_to ad_account
+
+    def ad_account
+      @ad_account ||= AdAccount.find("act_#{account_id}")
+    end
+
+    # actions
+
+    def share(account_id)
+      query = {
+        share_with_object_id: account_id,
+        share_with_object_type: 'Account'
+      }
+      AdAccount.post("/#{id}/share_with_objects", query: query, objectify: false)
+    end
+  end
+end

data/lib/facebook_ads/ad_campaign.rb

@@ -2,53 +2,57 @@ 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)
-    STATUSES   = %w(ACTIVE PAUSED DELETED PENDING_REVIEW DISAPPROVED PREAPPROVED PENDING_BILLING_INFO CAMPAIGN_PAUSED ARCHIVED ADSET_PAUSED)
-    OBJECTIVES = %w(CONVERSIONS MOBILE_APP_INSTALLS) # %w(BRAND_AWARENESS CANVAS_APP_ENGAGEMENT CANVAS_APP_INSTALLS CONVERSIONS EVENT_RESPONSES EXTERNAL LEAD_GENERATION LINK_CLICKS LOCAL_AWARENESS MOBILE_APP_ENGAGEMENT MOBILE_APP_INSTALLS OFFER_CLAIMS PAGE_LIKES POST_ENGAGEMENT PRODUCT_CATALOG_SALES REACH VIDEO_VIEWS)
+    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
 
     # belongs_to ad_account
 
     def ad_account
-      @ad_account ||= FacebookAds::AdAccount.find("act_#{account_id}")
+      @ad_account ||= AdAccount.find("act_#{account_id}")
     end
 
     # has_many ad_sets
 
     def ad_sets(effective_status: ['ACTIVE'], limit: 100)
-      FacebookAds::AdSet.paginate("/#{id}/adsets", query: { effective_status: effective_status, limit: limit })
+      AdSet.paginate("/#{id}/adsets", query: { effective_status: effective_status, limit: limit })
     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: #{FacebookAds::AdSet::OPTIMIZATION_GOALS.to_sentence}" unless FacebookAds::AdSet::OPTIMIZATION_GOALS.include?(optimization_goal)
-      raise Exception, "Billing event must be one of: #{FacebookAds::AdSet::BILLING_EVENTS.to_sentence}" unless FacebookAds::AdSet::BILLING_EVENTS.include?(billing_event)
+      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)
 
-      targeting.validate! # Will raise if invalid.
+      if targeting.is_a?(Hash)
+        # NOP
+      else
+        targeting.validate! # Will raise if invalid.
+        targeting = targeting.to_hash
+      end
 
-      ad_set = FacebookAds::AdSet.post("/act_#{account_id}/adsets", query: { # Returns a FacebookAds::AdSet instance.
+      query = {
         campaign_id: id,
         name: name,
-        targeting: targeting.to_hash.to_json,
+        targeting: targeting.to_json,
         promoted_object: promoted_object.to_json,
         optimization_goal: optimization_goal,
         daily_budget: daily_budget,
         billing_event: billing_event,
         status: status,
         is_autobid: is_autobid
-      }, objectify: true)
-
-      FacebookAds::AdSet.find(ad_set.id)
+      }
+      ad_set = AdSet.post("/act_#{account_id}/adsets", query: query, objectify: true) # Returns an AdSet instance.
+      AdSet.find(ad_set.id)
     end
 
     # has_many ad_insights
 
     def ad_insights(range: Date.today..Date.today, level: 'ad', time_increment: 1)
-      FacebookAds::AdInsight.paginate("/#{id}/insights", query: {
+      query = {
         level: level,
         time_increment: time_increment,
         time_range: { 'since': range.first.to_s, 'until': range.last.to_s }
-      })
+      }
+      AdInsight.paginate("/#{id}/insights", query: query)
     end
-
   end
 end

data/lib/facebook_ads/ad_creative.rb

@@ -2,12 +2,10 @@ 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)
-    CALL_TO_ACTION_TYPES = %w(SHOP_NOW INSTALL_MOBILE_APP USE_MOBILE_APP SIGN_UP DOWNLOAD BUY_NOW) # %w(OPEN_LINK LIKE_PAGE SHOP_NOW PLAY_GAME INSTALL_APP USE_APP INSTALL_MOBILE_APP USE_MOBILE_APP BOOK_TRAVEL LISTEN_MUSIC WATCH_VIDEO LEARN_MORE SIGN_UP DOWNLOAD WATCH_MORE NO_BUTTON CALL_NOW BUY_NOW GET_OFFER GET_OFFER_VIEW GET_DIRECTIONS MESSAGE_PAGE SUBSCRIBE SELL_NOW DONATE_NOW GET_QUOTE CONTACT_US RECORD_NOW VOTE_NOW OPEN_MOVIES)
+    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:)
         object_story_spec = {
           'page_id' => page_id, # 300664329976860
@@ -26,13 +24,14 @@ module FacebookAds
             }
           }
         }
+
         {
           name: name,
           object_story_spec: object_story_spec.to_json
         }
       end
 
-      # https://developers.facebook.com/docs/marketing-api/guides/carousel-ads/v2.6
+      # https://developers.facebook.com/docs/marketing-api/guides/videoads
       def carousel(name:, page_id:, instagram_actor_id: nil, link:, message:, assets:, call_to_action_type:, multi_share_optimized:, multi_share_end_card:)
         object_story_spec = {
           'page_id' => page_id, # 300664329976860
@@ -41,7 +40,7 @@ module FacebookAds
             'link' => link, # https://tophatter.com/, https://itunes.apple.com/app/id619460348, http://play.google.com/store/apps/details?id=com.tophatter
             'message' => message,
             'call_to_action' => { 'type' => call_to_action_type },
-            'child_attachments' => assets.collect { |asset|
+            'child_attachments' => assets.collect do |asset|
               {
                 'link' => link,
                 'image_hash' => asset[:hash],
@@ -49,18 +48,17 @@ module FacebookAds
                 # 'description' => asset[:title],
                 'call_to_action' => { 'type' => call_to_action_type } # Redundant?
               }
-            },
+            end,
             'multi_share_optimized' => multi_share_optimized,
             'multi_share_end_card' => multi_share_end_card
           }
         }
+
         {
           name: name,
           object_story_spec: object_story_spec.to_json
         }
       end
-
     end
-
   end
 end

data/lib/facebook_ads/ad_image.rb

@@ -3,11 +3,10 @@ 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)
+    FIELDS = %w(id hash account_id name permalink_url original_width original_height).freeze
 
     class << self
-      def find(id)
+      def find(_id)
         raise Exception, 'NOT IMPLEMENTED'
       end
     end
@@ -16,13 +15,12 @@ module FacebookAds
       self[:hash]
     end
 
-    def update(data)
+    def update(_data)
       raise Exception, 'NOT IMPLEMENTED'
     end
 
     def destroy
       super(path: "/act_#{account_id}/adimages", query: { hash: hash })
     end
-
   end
 end