facebook_ads 0.4 → 0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7450bd7b5cbf0923d6fd31c81789dbb4a41c6a6e
-  data.tar.gz: 4a96fdf4cd1940418b414a4b35f1d9dd16b7faf5
+  metadata.gz: a57756116ad7b5abac5c48ce3ac5d6f249f069e1
+  data.tar.gz: 5f4577a436b3e3b3099802a05eb4cfe1f2ec6280
 SHA512:
-  metadata.gz: 9aea51760cc15a61efcb50b2ba823162b56d6f5a7426efb803627913d586cc050405dede1c737e2f47e34ed34431bde4bb1d81cd0f26f4d4d8701aa6c859cd9d
-  data.tar.gz: a4835643fae536365837cf1071b5d6df228317aca5dbc28e15d1d82a51ec65f1ae733dcca4bfee00b86d5ba6fbe83c327516a35e13e39feb8e32b3c5bd9511bb
+  metadata.gz: c1bfa9b506e7321f4647f9ed61d7e1031a0f72543e13386ab21c1715edd098574f8c466394dba4e5a52338ef7f87330cc25052b3c7d8010970efa9a2a2db264b
+  data.tar.gz: 27f49b9e0bd2c6f09138a43f984b9b766b771320aa3ec155f933d9c67e3fd13e4d758c620eacf19e3a922ac9d1463dc801a19cc888fa881ee2ae393101304b68

data/.gitignore

@@ -7,3 +7,4 @@
 
 /test_access_token
 /test_business_id
+.idea

data/README.md

@@ -36,10 +36,10 @@ FacebookAds.app_secret = '[YOUR_APP_SECRET]'
 
 ## 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:
+This gem currently uses v2.9 of the Marketing API (2.10 is released as of 7/18/2017). You can change the version as desired with the following:
 
 ```ruby
-FacebookAds.base_uri = 'https://graph.facebook.com/v2.9'
+FacebookAds.base_uri = 'https://graph.facebook.com/v2.10'
 ```
 
 ## Console
@@ -210,7 +210,7 @@ carousel_ad_creative = account.create_ad_creative({
   call_to_action_type: 'SHOP_NOW',
   multi_share_optimized: true,
   multi_share_end_card: false
-}, carousel: true)
+}, creative_type: 'carousel')
 ```
 See FacebookAds::AdCreative::CALL_TO_ACTION_TYPES for a list of all call to action types.
 
@@ -224,8 +224,20 @@ image_ad_creative = account.create_ad_creative({
   link_title: 'A link title.',
   image_hash: ad_images.first.hash,
   call_to_action_type: 'SHOP_NOW'
-}, carousel: false)
+}, creative_type: 'image')
 ```
+
+Create a single creative for a web link:
+```ruby
+image_ad_creative = account.create_ad_creative({
+  title: 'Test Link Title', 
+  body: 'Link Description Text', 
+  object_url: 'www.example.com/my-ad-link', 
+  link_url: 'www.example.com/my-ad-link',
+  image_hash: ad_images.first.hash,
+}, creative_type: 'link')
+```
+
 The options will be different depending on the thing being advertised (Android app, iOS app or website).
 
 Find a creative by ID:
@@ -300,7 +312,8 @@ ad_set = campaign.create_ad_set(
   optimization_goal: 'OFFSITE_CONVERSIONS',
   daily_budget: 500, # This is in cents, so the daily budget here is $5.
   billing_event: 'IMPRESSIONS',
-  status: 'PAUSED'
+  status: 'PAUSED',
+  is_autobid: true
 )
 ```
 See FacebookAds::AdSet::OPTIMIZATION_GOALS for a list of all optimization goals.

data/facebook_ads.gemspec

@@ -2,10 +2,10 @@
 
 # To publish the next version:
 # gem build facebook_ads.gemspec
-# gem push facebook_ads-0.4.gem
+# gem push facebook_ads-0.5.gem
 Gem::Specification.new do |s|
   s.name        = 'facebook_ads'
-  s.version     = '0.4'
+  s.version     = '0.5'
   s.platform    = Gem::Platform::RUBY
   s.licenses    = ['MIT']
   s.authors     = ['Chris Estreich']

data/lib/facebook_ads.rb

@@ -29,10 +29,19 @@ module FacebookAds
   end
 
   def self.base_uri
-    @base_uri = 'https://graph.facebook.com/v2.8' unless defined?(@base_uri)
+    @base_uri = "https://graph.facebook.com/v#{api_version}" unless defined?(@base_uri)
     @base_uri
   end
 
+  def self.api_version=(api_version)
+    @api_version = api_version
+  end
+
+  def self.api_version
+    @api_version = '2.9' unless defined?(@api_version)
+    @api_version
+  end
+
   def self.access_token=(access_token)
     @access_token = access_token
   end

data/lib/facebook_ads/ad.rb

@@ -28,5 +28,16 @@ module FacebookAds
     def ad_creative
       @ad_creative ||= AdCreative.find(creative['id'])
     end
+
+    # has_many ad_insights
+
+    def ad_insights(range: Date.today..Date.today, level: 'ad', time_increment: 1)
+      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_account.rb

@@ -66,8 +66,19 @@ module FacebookAds
       AdCreative.paginate("/#{id}/adcreatives", query: { limit: limit })
     end
 
-    def create_ad_creative(creative, carousel: true)
-      carousel ? create_carousel_ad_creative(creative) : create_image_ad_creative(creative)
+    def create_ad_creative(creative, creative_type: nil, carousel: false)
+      # Support old deprecated carousel param
+      return create_carousel_ad_creative(creative) if carousel
+      case creative_type
+      when 'carousel'
+        create_carousel_ad_creative(creative)
+      when 'link'
+        create_link_ad_creative(creative)
+      when 'image'
+        create_image_ad_creative(creative)
+      else
+        create_image_ad_creative(creative)
+      end
     end
 
     # has_many ad_sets
@@ -115,6 +126,25 @@ module FacebookAds
       self.class.get("/#{id}/reachestimate", query: query, objectify: false)
     end
 
+    def delivery_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,
+        optimization_goal: optimization_goal,
+        currency: currency
+      }
+      self.class.get("/#{id}/delivery_estimate", query: query, objectify: false)
+    end
+
     # has_many applications
 
     def applications
@@ -179,6 +209,18 @@ module FacebookAds
       AdCreative.find(result['id'])
     end
 
+    def create_link_ad_creative(creative)
+      required = %i[name title body object_url link_url image_hash]
+
+      unless (keys = required - creative.keys).length.zero?
+        raise Exception, "Creative is missing the following: #{keys.join(', ')}"
+      end
+
+      query = AdCreative.link(creative)
+      result = AdCreative.post("/#{id}/adcreatives", query: query)
+      AdCreative.find(result['id'])
+    end
+
     def download(url)
       pathname = Pathname.new(url)
       name = "#{pathname.dirname.basename}.jpg"

data/lib/facebook_ads/ad_campaign.rb

@@ -60,7 +60,7 @@ module 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: nil, bid_amount: nil)
+    def create_ad_set(name:, promoted_object: {}, targeting:, daily_budget: nil, lifetime_budget: nil, end_time: nil, optimization_goal:, billing_event: 'IMPRESSIONS', status: 'ACTIVE', is_autobid: nil, bid_amount: nil)
       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)
 
@@ -77,12 +77,21 @@ module FacebookAds
         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,
         bid_amount: bid_amount
       }
+
+      if daily_budget && lifetime_budget
+        raise Exception 'Only one budget may be set between daily_budget and life_budget'
+      elsif daily_budget
+        query[:daily_budget] = daily_budget
+      elsif lifetime_budget
+        query[:lifetime_budget] = lifetime_budget
+        query[:end_time] = end_time
+      end
+
       result = AdSet.post("/act_#{account_id}/adsets", query: query)
       AdSet.find(result['id'])
     end
@@ -93,7 +102,7 @@ module FacebookAds
       query = {
         level: level,
         time_increment: time_increment,
-        time_range: { 'since': range.first.to_s, 'until': range.last.to_s }
+        time_range: { since: range.first.to_s, until: range.last.to_s }
       }
       AdInsight.paginate("/#{id}/insights", query: query)
     end

data/lib/facebook_ads/ad_creative.rb

@@ -2,15 +2,17 @@ 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].freeze
+    CALL_TO_ACTION_TYPES = %w[SHOP_NOW INSTALL_MOBILE_APP USE_MOBILE_APP SIGN_UP DOWNLOAD BUY_NOW NO_BUTTON].freeze
 
     class << self
-      def photo(name:, page_id:, instagram_actor_id: nil, message:, link:, app_link: nil, link_title:, image_hash:, call_to_action_type:)
+      def photo(name:, page_id:, instagram_actor_id: nil, message:, link:, app_link: nil, link_title:, image_hash:, call_to_action_type:, link_description: nil)
         object_story_spec = {
           'page_id' => page_id, # 300664329976860
           'instagram_actor_id' => instagram_actor_id, # 503391023081924
           'link_data' => {
+            'name' => link_title,
+            'description' => link_description,
             '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,
@@ -19,8 +21,7 @@ module FacebookAds
               'value' => {
                 # 'application' =>,
                 'link' => link,
-                'app_link' => app_link,
-                'link_title' => link_title
+                'app_link' => app_link
               }
             }
           }
@@ -89,6 +90,17 @@ module FacebookAds
           product_set_id: product_set_id
         }
       end
+
+      def link(name:, title:, body:, object_url:, link_url:, image_hash:)
+        {
+          name: name,
+          title: title,
+          body: body,
+          object_url: object_url,
+          link_url: link_url,
+          image_hash: image_hash
+        }
+      end
     end
   end
 end

data/lib/facebook_ads/ad_set.rb

@@ -72,8 +72,8 @@ module FacebookAds
       Ad.paginate("/#{id}/ads", query: { effective_status: effective_status, limit: limit })
     end
 
-    def create_ad(name:, creative_id:)
-      query = { name: name, adset_id: id, creative: { creative_id: creative_id }.to_json }
+    def create_ad(name:, creative_id:, status: 'PAUSED')
+      query = { name: name, adset_id: id, creative: { creative_id: creative_id }.to_json, status: status }
       result = Ad.post("/act_#{account_id}/ads", query: query)
       Ad.find(result['id'])
     end

data/lib/facebook_ads/ad_targeting.rb

@@ -14,20 +14,30 @@ module FacebookAds
     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
+    attr_accessor :genders, :age_min, :age_max, :countries, :user_os, :user_device, :app_install_state, :custom_locations, :income
 
     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.app_install_state = NOT_INSTALLED
+      self.income = [] # An a rray of objects with 'id' and optional 'name'
+    end
+
+    def geo_locations
+      if custom_locations
+        { custom_locations: custom_locations }
+      elsif countries
+        { countries: countries }
+      else
+        { countries: ['US'] }
+      end
     end
 
     def validate!
-      { gender: genders, countries: countries, user_os: user_os, user_device: user_device }.each_pair do |key, array|
+      { gender: genders, countries: countries, user_os: user_os, user_device: user_device, custom_locations: custom_locations }.each_pair do |key, array|
         if !array.nil? && !array.is_a?(Array)
           raise Exception, "#{self.class.name}: #{key} must be an array"
         end
@@ -49,10 +59,11 @@ module FacebookAds
         genders: genders,
         age_min: age_min,
         age_max: age_max,
-        geo_locations: { countries: countries },
+        geo_locations: geo_locations,
         user_os: user_os,
         user_device: user_device,
-        app_install_state: app_install_state
+        app_install_state: app_install_state,
+        income: income
       }.reject { |_k, v| v.nil? }
     end
   end

data/spec/facebook_ads/ad_account_spec.rb

@@ -65,6 +65,26 @@ describe FacebookAds::AdAccount do
     end
   end
 
+  describe '.create_ad_creative' do
+    it 'creates carousel ad creative', :vcr do
+      ad_images = account.create_ad_images(%w[https://img0.etsystatic.com/108/1/13006112/il_570xN.1047856494_l2gp.jpg https://img1.etsystatic.com/143/0/13344107/il_570xN.1141249285_xciv.jpg])
+      carousel_ad_creative = account.create_ad_creative({
+                                                          name: 'Test Carousel Creative',
+                                                          page_id: '300664329976860', # Add your Facebook Page ID here.
+                                                          link: 'http://play.google.com/store/apps/details?id=com.tophatter', # Add your Play Store ID here.
+                                                          message: 'A message.',
+                                                          assets: [
+                                                            { hash: ad_images[0].hash, title: 'Image #1 Title' },
+                                                            { hash: ad_images[1].hash, title: 'Image #2 Title' }
+                                                          ],
+                                                          call_to_action_type: 'SHOP_NOW',
+                                                          multi_share_optimized: true,
+                                                          multi_share_end_card: false
+                                                        }, creative_type: 'carousel')
+      expect(carousel_ad_creative.id).to eq('120330000008134415')
+    end
+  end
+
   describe '.ad_sets' do
     it 'lists ad sets', :vcr do
       ad_sets = account.ad_sets

data/spec/facebook_ads/ad_campaign_spec.rb

@@ -2,14 +2,54 @@ require 'spec_helper'
 
 # FACEBOOK_ACCESS_TOKEN=... rspec spec/facebook_ads/ad_campaign_spec.rb
 describe FacebookAds::AdCampaign do
+  let(:campaign) do
+    FacebookAds::AdCampaign.new(
+      id: '120330000008134915',
+      account_id: '10152335766987003',
+      buying_type: 'AUCTION',
+      can_use_spend_cap: true,
+      configured_status: 'PAUSED',
+      created_time: '2017-08-25T15:47:51-0700',
+      effective_status: 'PAUSED',
+      name: 'Test Campaign',
+      objective: 'CONVERSIONS',
+      start_time: '1969-12-31T15:59:59-0800',
+      updated_time: '2017-08-25T15:47:51-0700'
+    )
+  end
+
+  let(:targeting) do
+    targeting = FacebookAds::AdTargeting.new
+    targeting.genders = [FacebookAds::AdTargeting::WOMEN]
+    targeting.age_min = 29
+    targeting.age_max = 65
+    targeting.countries = ['US']
+    targeting.user_os = [FacebookAds::AdTargeting::ANDROID_OS]
+    targeting.user_device = FacebookAds::AdTargeting::ANDROID_DEVICES
+    targeting.app_install_state = FacebookAds::AdTargeting::NOT_INSTALLED
+    targeting
+  end
+
   xdescribe '.ad_sets' do
   end
 
-  xdescribe '.create_ad_set' do
+  describe '.create_ad_set' do
+    it 'creates_valid_ad_set', :vcr do
+      ad_set = campaign.create_ad_set(
+        name: 'Test Ad Set',
+        targeting: targeting,
+        optimization_goal: 'IMPRESSIONS',
+        daily_budget: 500, # This is in cents, so the daily budget here is $5.
+        billing_event: 'IMPRESSIONS',
+        status: 'PAUSED',
+        is_autobid: true
+      )
+      expect(ad_set.id).to eq('120330000008135715')
+    end
   end
 
   describe '.destroy' do
-    it 'creates a new ad campaign', :vcr do
+    it 'sets effective status to deleted', :vcr do
       ad_campaign = FacebookAds::AdCampaign.find('6076262142242')
       expect(ad_campaign.destroy).to be(true)
       ad_campaign = FacebookAds::AdCampaign.find(ad_campaign.id)

data/spec/facebook_ads/ad_targeting_spec.rb

@@ -1,4 +1,24 @@
 require 'spec_helper'
 
 describe FacebookAds::AdTargeting do
+  let(:targeting) { FacebookAds::AdTargeting.new }
+
+  describe '#geo_locations' do
+    let(:custom_locations) { [{ radius: 10, distance_unit: 'mile', address_string: '1601 Willow Road, Menlo Park, CA 94025' }] }
+    let(:countries) { ['JP'] }
+
+    it 'should return custom locations if specified' do
+      targeting.custom_locations = custom_locations
+      expect(targeting.geo_locations).to eq(custom_locations: custom_locations)
+    end
+
+    it 'should return countries if specified' do
+      targeting.countries = countries
+      expect(targeting.geo_locations).to eq(countries: countries)
+    end
+
+    it 'should default to US if nothing is specified' do
+      expect(targeting.geo_locations).to eq(countries: ['US'])
+    end
+  end
 end