facebook_ads 0.1.5

data/bin/console

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'facebook_ads'
+require 'awesome_print'
+require 'pry'
+
+FacebookAds.access_token = File.read('test_access_token').squish
+FacebookAds.logger = Logger.new(STDOUT)
+FacebookAds.logger.level = Logger::Severity::DEBUG
+
+AwesomePrint.pry!
+binding.pry

data/facebook_ads.gemspec

@@ -0,0 +1,26 @@
+# To release a new version:
+# gem build facebook_ads.gemspec
+# gem push facebook_ads-0.1.5.gem
+Gem::Specification.new do |s|
+  s.name        = 'facebook_ads'
+  s.version     = '0.1.5'
+  s.platform    = Gem::Platform::RUBY
+  s.licenses    = ['MIT']
+  s.authors     = ['Chris Estreich']
+  s.email       = 'cestreich@gmail.com'
+  s.homepage    = 'https://github.com/cte/facebook-ads-sdk-ruby'
+  s.summary     = "Facebook Marketing API SDK for Ruby."
+  s.description = "This gem allows to easily manage your Facebook ads via Facebook's Marketing API in ruby."
+
+  s.extra_rdoc_files = ['README.markdown']
+
+  s.files         = `git ls-files`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.required_ruby_version = '~> 2.0'
+
+  s.add_dependency 'activesupport', '~> 4.2'
+  s.add_dependency 'httmultiparty', '~> 0.3'
+  s.add_dependency 'hashie', '~> 3.4'
+end

data/lib/facebook_ads.rb

@@ -0,0 +1,46 @@
+# External requires.
+require 'active_support/all'
+require 'httmultiparty'
+require 'hashie'
+
+# Internal requires.
+require 'facebook_ads/base'
+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
+
+  def self.logger
+    unless defined?(@logger)
+      @logger       = Logger.new('/dev/null')
+      @logger.level = Logger::Severity::UNKNOWN
+    end
+
+    @logger
+  end
+
+  def self.base_uri=(base_uri)
+    @base_uri = base_uri
+  end
+
+  def self.base_uri
+    unless defined?(@base_uri)
+      @base_uri = 'https://graph.facebook.com/v2.6'
+    end
+
+    @base_uri
+  end
+
+  def self.access_token=(access_token)
+    @access_token = access_token
+  end
+
+  def self.access_token
+    @access_token
+  end
+
+end

data/lib/facebook_ads/ad.rb

@@ -0,0 +1,34 @@
+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)
+
+    # belongs_to ad_account
+
+    def ad_account
+      @ad_set ||= FacebookAds::AdAccount.find(account_id)
+    end
+
+    # belongs_to ad_campaign
+
+    def ad_campaign
+      @ad_set ||= FacebookAds::AdCampaign.find(campaign_id)
+    end
+
+    # belongs_to ad_set
+
+    def ad_set
+      @ad_set ||= FacebookAds::AdSet.find(adset_id)
+    end
+
+    # belongs_to ad_creative
+
+    def ad_creative
+      @ad_creative ||= FacebookAds::AdCreative.find(creative['id'])
+    end
+
+  end
+end

data/lib/facebook_ads/ad_account.rb

@@ -0,0 +1,126 @@
+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)
+
+    class << self
+      def all
+        get('/me/adaccounts', objectify: true)
+      end
+
+      def find_by(conditions)
+        all.detect do |ad_account|
+          conditions.all? do |key, value|
+            ad_account.send(key) == value
+          end
+        end
+      end
+    end
+
+    # has_many campaigns
+
+    def ad_campaigns(effective_status: ['ACTIVE'], limit: 100)
+      FacebookAds::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)
+    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)
+      else
+        FacebookAds::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)]
+      end.to_h
+
+      response = FacebookAds::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
+    end
+
+    # has_many ad_creatives
+
+    def ad_creatives(limit: 100)
+      FacebookAds::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)
+    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 })
+    end
+
+    # has_many ads
+
+    def ads(effective_status: ['ACTIVE'], limit: 100)
+      FacebookAds::Ad.paginate("/#{id}/ads", query: { effective_status: effective_status, limit: limit })
+    end
+
+    # has_many ad_insights
+
+    def ad_insights(range: Date.today..Date.today, level: 'ad', time_increment: 1)
+      ad_campaigns.map do |ad_campaign|
+        ad_campaign.ad_insights(range: range, level: level, time_increment: time_increment)
+      end.flatten
+    end
+
+    # has_many applications
+
+    def applications
+      self.class.get("/#{id}/advertisable_applications", objectify: false)
+    end
+
+  end
+end

data/lib/facebook_ads/ad_campaign.rb

@@ -0,0 +1,54 @@
+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)
+
+    # belongs_to ad_account
+
+    def ad_account
+      @ad_account ||= FacebookAds::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 })
+    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)
+
+      targeting.validate! # Will raise if invalid.
+
+      ad_set = FacebookAds::AdSet.post("/act_#{account_id}/adsets", query: { # Returns a FacebookAds::AdSet instance.
+        campaign_id: id,
+        name: name,
+        targeting: targeting.to_hash.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)
+    end
+
+    # has_many ad_insights
+
+    def ad_insights(range: Date.today..Date.today, level: 'ad', time_increment: 1)
+      FacebookAds::AdInsight.paginate("/#{id}/insights", query: {
+        level: level,
+        time_increment: time_increment,
+        time_range: { 'since': range.first.to_s, 'until': range.last.to_s }
+      })
+    end
+
+  end
+end

data/lib/facebook_ads/ad_creative.rb

@@ -0,0 +1,66 @@
+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)
+
+    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
+          'instagram_actor_id' => instagram_actor_id, # 503391023081924
+          'link_data' => {
+            'link' => link, # https://tophatter.com/, https://itunes.apple.com/app/id619460348, http://play.google.com/store/apps/details?id=com.tophatter
+            'message' => message,
+            'image_hash' => image_hash,
+            'call_to_action' => {
+              'type' => call_to_action_type,
+              'value' => {
+                # 'application' =>,
+                'link' => link,
+                'link_title' => link_title
+              }
+            }
+          }
+        }
+        {
+          name: name,
+          object_story_spec: object_story_spec.to_json
+        }
+      end
+
+      # https://developers.facebook.com/docs/marketing-api/guides/carousel-ads/v2.6
+      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
+          'instagram_actor_id' => instagram_actor_id, # 503391023081924
+          'link_data' => {
+            '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|
+              {
+                'link' => link,
+                'image_hash' => asset[:hash],
+                'name' => asset[:title],
+                # 'description' => asset[:title],
+                'call_to_action' => { 'type' => call_to_action_type } # Redundant?
+              }
+            },
+            '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

@@ -0,0 +1,28 @@
+module FacebookAds
+  # An ad image belongs to an ad account.
+  # 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)
+
+    class << self
+      def find(id)
+        raise Exception, 'NOT IMPLEMENTED'
+      end
+    end
+
+    def hash
+      self[:hash]
+    end
+
+    def update(data)
+      raise Exception, 'NOT IMPLEMENTED'
+    end
+
+    def destroy
+      super(path: "/act_#{account_id}/adimages", query: { hash: hash })
+    end
+
+  end
+end

data/lib/facebook_ads/ad_insight.rb

@@ -0,0 +1,24 @@
+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
+  class AdInsight < Base
+
+    FIELDS = %w(ad_id objective impressions unique_actions cost_per_unique_action_type clicks cpc cpm ctr spend)
+
+    class << self
+      def find(id)
+        raise Exception, 'NOT IMPLEMENTED'
+      end
+    end
+
+    def update(data)
+      raise Exception, 'NOT IMPLEMENTED'
+    end
+
+    def destroy
+      raise Exception, 'NOT IMPLEMENTED'
+    end
+
+  end
+end

data/lib/facebook_ads/ad_set.rb

@@ -0,0 +1,35 @@
+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)
+
+    # belongs_to ad_account
+
+    def ad_account
+      @ad_set ||= FacebookAds::AdAccount.find(account_id)
+    end
+
+    # belongs_to ad_campaign
+
+    def ad_campaign
+      @campaign ||= FacebookAds::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 })
+    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)
+    end
+
+  end
+end