facebookads 0.0.1 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6a07d30ce302a0f97e845a894449cbdbd6d25cff
-  data.tar.gz: 47edb0889a1434afc6f44a64859808faf253241e
+  metadata.gz: b5aa03ab8b6c47b81656efca672e6341fc9d76c4
+  data.tar.gz: be8de8a6fea10fda4584841141eb8aeb5398a439
 SHA512:
-  metadata.gz: fe8e6ee424ae6ece43b4a3fd93fa6eb1600e930bdafed74704726eebeea370f8e5175b780a11c2e386f8e4a5867c7c6ecf4fe18eef5170028ac6e22410273320
-  data.tar.gz: 6f4e4ee85b25bc27c02a33d481b97b9e9455660956a7b8f9a792e516154f9ace81af69489eb49596a8de85fcf12aefa14e1e8ba66349f6666e5f7b4e53eb5580
+  metadata.gz: 4b607cad195d7498d0e72f06a3aeafc6b6abdda6eebf11d9d42d0b33db7a00f9f0ad6a6629859e1f920ba59e7061f4bebcc9d4dd1e88ddaef3b84338d6466cfa
+  data.tar.gz: 3bfd0ee8fa82d92f00cfed0cf28e3e764aff8d311e446f25ac42ca0c30e0bfdddd3773f472ddbe973ebd0920f186bddd38500a61e8e0d79c58938e30d8ec4bde

data/LICENSE.txt

@@ -0,0 +1,17 @@
+Copyright (c) 2017-present, Facebook, Inc. All rights reserved.
+
+You are hereby granted a non-exclusive, worldwide, royalty-free license to use,
+copy, modify, and distribute this software in source code or binary form for use
+in connection with the web services and APIs provided by Facebook.
+
+As with any software that integrates with the Facebook platform, your use of
+this software is subject to the Facebook Platform Policy
+[http://developers.facebook.com/policy/]. This copyright notice shall be
+included in all copies or substantial portions of the software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,222 @@
+# Facebook Ads API SDK for Ruby
+
+## Pre-requisites
+### Ruby Version
+We developed this SDK using Ruby 2.0, and supports Ruby 2.0+, however, the SDK is not thread-safe at the moment.
+
+### App
+To get started with the SDK you must have a Facebook app registered on [developers.facebook.com](https://developers.facebook.com).
+
+**IMPORTANT**: Enable all migrations in the App's Settings->Migrations page.
+
+**IMPORTANT**: To have better security, we recommend you to turn on 'App Secret Proof for Server API calls' in your app's Settings->Advanced page.
+
+## Installation
+The SDK is available as a RubyGem. To use the gem, you can add the following to Gemfile
+
+```ruby
+gem 'facebookads'
+```
+
+or install it using command line
+
+```bash
+gem install facebookads
+```
+
+and then in your code
+
+```ruby
+require 'facebook_ads'
+```
+
+
+## Configuration
+### Access Token
+There are several ways to configure access token and app secret. If you only use one access token and app secret (example: an internal app managing only your own assets). You can set a global access token and app secret will will be used across all requests
+
+```ruby
+FacebookAds.configure do |config|
+  config.access_token = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+  config.app_secret = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+end
+```
+
+Another way is to configure using environment variables, which will be picked up by the SDK as the default
+
+```bash
+FB_ACCESS_TOKEN=asdsadasds
+FB_APP_SECRET=asdasdsa
+```
+
+Or you can create a session object for particular object
+
+```ruby
+# Create a Session object to be reused
+session = FacebookAds::Session.new(access_token: <ACCESS_TOKEN>, app_secret: <APP SECRET>)
+ad_account = FacebookAds::AdAccount.get('act_12334', 'name', session)
+
+# Or a using shortcut during object instantiation
+ad_account = FacebookAds::AdAccount.get('act_12334', 'name', {
+    access_token: <ACCESS_TOKEN>, app_secret: <APP SECRET>
+})
+```
+
+## Basic Operations
+
+### Reading a node
+The SDK contains ad object files auto generated from our API metadata, each node type has its own corresponding Ruby class under the `FacebookAds` module. For example, to fetch an AdAccount
+
+```ruby
+ad_account = FacebookAds::AdAccount.get('act_1234567', 'name')
+print "Ad Account Name: #{ad_account.name}"
+```
+
+The `#get` method doesn't trigger the `GET` request immeidately. The API request for `GET` is fired on-demand. In the example above, API request won't fire until `ad_account.name` is executed.
+
+### Updating a node
+To update a node, you can use the `#save` method of ad object classes.
+
+```ruby
+ad_account = FacebookAds::AdAccount.get('act_1234567', 'name')
+ad_account.name = "New Ad Account"
+ad_account.save
+
+# Fetch it again
+ad_account.reload!
+ad_account.name
+=> "New Ad Account"
+```
+
+### Deleting a node
+To delete a node, you can use the `#destroy` method.
+
+```ruby
+campaign = FacebookAds::Campaign.get('<CAMPAIGN_ID>')
+campaign.destroy
+```
+
+### Reference
+You can refer to our [Marketing API reference](https://developers.facebook.com/docs/marketing-api/reference/) or look inside `lib/facebook_ads/ad_objects` directory of the code base to see the complete list of available ad objects.
+
+## Interacting with Edges
+
+To interact with an edge, you first need to instantiate the parent node. Since, as mentioned above, `GET` request of a node is triggered on-demand, so you don't need to worry about consuming unnecessary API quota.
+
+### Fetching Edges (GET)
+
+Iterating edges is easy, instantiate the parent nodes and then simply iterate with `#each`. The edge is an  `Enumerable` so a bunch of handy methods such as `#map`, `#select`, `#find` etc. come for free!
+
+```ruby
+ad_account = FacebookAds::AdAccount.get('act_1234567', 'name')
+
+# Printing all campaign names
+ad_account.campaigns(fields: 'name').each do |campaign|
+  print campaign.name
+end
+
+# Getting all campaign names
+ad_account.campaigns(fields: 'name').map(&:name)
+
+```
+
+### Creating new nodes (POST)
+To `POST` to a edge, you can use the `#create` method on the edge and supply parameter if needed
+
+```ruby
+campaign = ad_account.campaigns.create({
+  name: "My First campaign",
+  objective: "CONVERSIONS",
+})
+```
+
+### Removing from edge (DELETE)
+To `DELETE` an edge, you can use the `#destroy` method on the edge and supply parameter if needed
+
+```ruby
+# Deleting an AdImage by its hash
+ad_account.adimages.destroy({hash: 'abcd1234'})
+```
+
+## Images/Videos
+The SDK supports image/video uploads. Just supply a parameter of `File` type.
+
+Image upload example:
+
+```ruby
+# AdImage supports multiple images upload
+ad_account.adimages.create({
+  'logo1.png' => File.open('./assets/logo1.jpg'),
+  'logo2.png' => File.open('./assets/logo2.jpg'),
+})
+=> [#<FacebookAds::AdImage {:hash=>"..."}>, #<FacebookAds::AdImage {:hash=>"..."}>]
+```
+
+Video upload example:
+
+```ruby
+ad_account.advideos.create({
+  name: 'My first video',
+  source: File.open(File.expand_path("../video_ad_example.mp4", __FILE__))
+})
+```
+
+## Batch API
+
+[Batch API](https://developers.facebook.com/docs/marketing-api/asyncrequests) allows you to make API calls in a batch. You can collect a bunch of API requests and fire them all at once to reduce wait time. To create a batch, just wrap operations with a block to `FacebookAds::Batch#with_batch`
+
+```ruby
+ad_account = FacebookAds::AdAccount.get('act_<ACT_ID>')
+
+batch = FacebookAds::Batch.with_batch do
+  10.times.map do |n|
+    ad_account.campaigns.create({
+      name: 'My Test Campaign #' + n,
+      objective: 'CONVERSIONS',
+      status: 'PAUSED',
+    })
+  end
+end
+
+batch.execute
+```
+
+### Dependencies within a batch (Experimental)
+Dependencies between requests is supported, the SDK simplifies the use of JSONPath references between batched operations.
+
+```ruby
+ad_account = FacebookAds::AdAccount.get('act_12334')
+
+batch = FacebookAds::Batch.with_batch do
+  # This won't be sent out immediately!
+  campaign = ad_account.campaigns.create({
+    name: 'My Test Campaign',
+    objective: 'CONVERSIONS',
+    status: 'PAUSED',
+  })
+
+  # Even the request above is not being sent yet, reference to campaign.id still works
+  ad_accounts.adsets.create({
+    name: 'My AdSet',
+    campaign_id: campaign.id, # campaign.id here will return {result=create-campaign:$.id}
+    ...
+    ...
+    ...
+  })
+end
+```
+
+## Logging
+
+```ruby
+FacebookAds.configure do |config|
+  # Logger for debugger
+  config.logger = ::Logger.new(STDOUT).tap { |d| d.level = Logger::DEBUG }
+
+  # Log Http request & response to logger
+  config.log_api_bodies = true
+end
+```
+
+## Reporting Bugs/Feedback
+Please raise any issue on Github.

data/lib/facebook_ads/ad_object.rb

@@ -0,0 +1,177 @@
+# Copyright (c) 2017-present, Facebook, Inc. All rights reserved.
+#
+# You are hereby granted a non-exclusive, worldwide, royalty-free license to use,
+# copy, modify, and distribute this software in source code or binary form for use
+# in connection with the web services and APIs provided by Facebook.
+#
+# As with any software that integrates with the Facebook platform, your use of
+# this software is subject to the Facebook Platform Policy
+# [http://developers.facebook.com/policy/]. This copyright notice shall be
+# included in all copies or substantial portions of the software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'json'
+require 'facebook_ads/api_request'
+require 'facebook_ads/api_response'
+require 'facebook_ads/helpers/node_helpers'
+require 'facebook_ads/helpers/edge_helpers'
+
+module FacebookAds
+  class AdObject
+    attr_reader :attributes, :fields, :last_api_response
+    attr_accessor :deserializer
+    attr_accessor :last_saved, :last_destroyed
+
+    include Fields
+    include GraphNodes
+    include GraphEdges
+
+    def initialize(attributes, *args)
+      if attributes.empty?
+        raise InvalidParameterError, 'Invalid attributes. Must include at least one attribute'
+      end
+
+      update_attributes(attributes)
+      # assume object with only id in the attributes as not loaded
+
+      # is next arg a list of fields?
+      fields = (args[0].is_a?(Array) || args[0].is_a?(String)) ? args.shift : []
+      fields = fields.split(',') if fields.is_a?(String)
+      session = args.shift
+
+      self.fields = fields + attributes.keys
+      self.session = session
+    end
+
+    def self.get(id, *args)
+      obj = new({id: id}, *args)
+      yield obj if block_given?
+      obj
+    end
+
+    def id
+      self[:id]
+    end
+
+    def update_attributes(attrs)
+      @attributes ||= {}
+      @attributes.merge!(
+        self.class.deserializer ?
+          self.class.deserializer.deserialize(symbolize_keys_shallow(attrs)) :
+          symbolize_keys_shallow(attrs)
+      )
+      self
+    end
+
+    def [](attr_name)
+      @attributes[attr_name.to_sym]
+    end
+
+    def to_hash
+      @attributes.merge(changes)
+    end
+
+    def as_json(*opts)
+      to_hash
+    end
+
+    def to_json(*a)
+      as_json.to_json(*a)
+    end
+
+    def inspect
+      "#<#{self.class.name} #{to_hash.inspect}>"
+    end
+
+    def fields_as_string
+      @fields.to_a.join(',')
+    end
+
+    def fields=(fields)
+      @fields = Set.new((fields.is_a?(String) ? fields.split(',') : fields.map(&:to_s)).map(&:to_sym))
+    end
+
+    def loaded?
+      (@fields - attributes.keys).empty?
+    end
+
+    def load!
+      get(graph_params) do |attrs|
+        update_attributes(attrs)
+      end
+    end
+
+    def reload!
+      # delete all attribute except id
+      @attributes = @attributes.keep_if { |k,_| k == :id }
+    end
+
+    # TODO refactor this to somewhere
+    def graph_params
+      {fields: fields_as_string}
+    end
+
+    [:get, :post, :delete].each do |verb|
+      define_method(verb) do |params = {}, &block|
+        params, options = extract_options(params)
+        APIRequest.new(verb, self.id, session: session, params: params, options: options).execute do |api_response|
+          @last_api_response = api_response
+          block ? block[api_response.result] : api_response
+        end
+      end
+
+      define_method("#{verb}_edge") do |edge_name, params = {}, &block|
+        params, options = extract_options(params)
+        path = "#{self.id}/#{edge_name}"
+        APIRequest.new(verb, path, session: session, params: params, options: options).execute do |api_response|
+          @last_api_response = api_response
+          block ? block[api_response.result] : api_response
+        end
+      end
+    end
+
+    def save(params = {})
+      post(graph_params.merge(changes).merge(params)) do |attrs|
+        update_attributes(attrs)
+        @changes = {}
+        self.last_saved = Time.now
+      end
+    end
+
+    def destroy(params = {})
+      delete(params) do |attrs|
+        self.last_destroyed = Time.now if attrs['success']
+      end
+    end
+
+    def changes
+      @changes ||= {}
+    end
+
+    def session
+      @session || Session.default_session
+    end
+
+    def session=(session)
+      @session = session.is_a?(Hash) ? Session.new(session) : session
+    end
+
+    private
+    def symbolize_keys_shallow(hash)
+      Hash[hash.map { |k,v| [k.to_sym,v] }]
+    end
+
+    def extract_options(params)
+      option_keys = [:batch_opts]
+      options = {}
+      option_keys.each { |k| options[k] = params.delete(k) if params.has_key?(k) }
+      [params, options]
+    end
+  end
+end

data/lib/facebook_ads/ad_objects/ad.rb

@@ -0,0 +1,215 @@
+# Copyright (c) 2017-present, Facebook, Inc. All rights reserved.
+#
+# You are hereby granted a non-exclusive, worldwide, royalty-free license to use,
+# copy, modify, and distribute this software in source code or binary form for use
+# in connection with the web services and APIs provided by Facebook.
+#
+# As with any software that integrates with the Facebook platform, your use of
+# this software is subject to the Facebook Platform Policy
+# [http://developers.facebook.com/policy/]. This copyright notice shall be
+# included in all copies or substantial portions of the software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+# FB:AUTOGEN
+
+module FacebookAds
+  # This class is auto-genereated.
+
+  # For any issues or feature requests related to this class, please let us know
+  # on github and we'll fix in our codegen framework. We'll not be able to accept
+  # pull request for this class.
+
+  class Ad < AdObject
+    BID_TYPE = [
+      "CPC",
+      "CPM",
+      "MULTI_PREMIUM",
+      "ABSOLUTE_OCPM",
+      "CPA",
+    ]
+
+    CONFIGURED_STATUS = [
+      "ACTIVE",
+      "PAUSED",
+      "DELETED",
+      "ARCHIVED",
+    ]
+
+    EFFECTIVE_STATUS = [
+      "ACTIVE",
+      "PAUSED",
+      "DELETED",
+      "PENDING_REVIEW",
+      "DISAPPROVED",
+      "PREAPPROVED",
+      "PENDING_BILLING_INFO",
+      "CAMPAIGN_PAUSED",
+      "ARCHIVED",
+      "ADSET_PAUSED",
+    ]
+
+    STATUS = [
+      "ACTIVE",
+      "PAUSED",
+      "DELETED",
+      "ARCHIVED",
+    ]
+
+    DATE_PRESET = [
+      "today",
+      "yesterday",
+      "this_month",
+      "last_month",
+      "this_quarter",
+      "lifetime",
+      "last_3d",
+      "last_7d",
+      "last_14d",
+      "last_28d",
+      "last_30d",
+      "last_90d",
+      "last_week_mon_sun",
+      "last_week_sun_sat",
+      "last_quarter",
+      "last_year",
+      "this_week_mon_today",
+      "this_week_sun_today",
+      "this_year",
+    ]
+
+    EXECUTION_OPTIONS = [
+      "validate_only",
+      "synchronous_ad_review",
+      "include_recommendations",
+    ]
+
+    OPERATOR = [
+      "ALL",
+      "ANY",
+    ]
+
+
+    field :account_id, 'string'
+    field :ad_review_feedback, 'AdgroupReviewFeedback'
+    field :adlabels, { list: 'AdLabel' }
+    field :adset, 'AdSet'
+    field :adset_id, 'string'
+    field :bid_amount, 'int'
+    field :bid_info, 'map<string, unsigned int>'
+    field :bid_type, { enum: -> { BID_TYPE }}
+    field :campaign, 'Campaign'
+    field :campaign_id, 'string'
+    field :configured_status, { enum: -> { CONFIGURED_STATUS }}
+    field :conversion_specs, { list: 'ConversionActionQuery' }
+    field :created_time, 'datetime'
+    field :creative, 'AdCreative'
+    field :effective_status, { enum: -> { EFFECTIVE_STATUS }}
+    field :id, 'string'
+    field :last_updated_by_app_id, 'string'
+    field :name, 'string'
+    field :recommendations, { list: 'AdRecommendation' }
+    field :status, { enum: -> { STATUS }}
+    field :tracking_specs, { list: 'ConversionActionQuery' }
+    field :updated_time, 'datetime'
+    field :adset_spec, 'AdSet'
+    field :date_format, 'string'
+    field :display_sequence, 'int'
+    field :execution_options, { list: { enum: -> { EXECUTION_OPTIONS }} }
+    field :redownload, 'bool'
+
+    has_edge :adcreatives do |edge|
+      edge.get 'AdCreative'
+    end
+
+    has_edge :adlabels do |edge|
+      edge.delete do |api|
+        api.has_param :adlabels, { list: 'object' }
+        api.has_param :execution_options, { list: { enum: -> { AdLabel::EXECUTION_OPTIONS }} }
+      end
+      edge.post 'AdLabel' do |api|
+        api.has_param :adlabels, { list: 'object' }
+        api.has_param :execution_options, { list: { enum: -> { AdLabel::EXECUTION_OPTIONS }} }
+      end
+    end
+
+    has_edge :insights do |edge|
+      edge.get 'AdsInsights' do |api|
+        api.has_param :action_attribution_windows, { list: { enum: -> { AdsInsights::ACTION_ATTRIBUTION_WINDOWS }} }
+        api.has_param :action_breakdowns, { list: { enum: -> { AdsInsights::ACTION_BREAKDOWNS }} }
+        api.has_param :action_report_time, { enum: -> { AdsInsights::ACTION_REPORT_TIME }}
+        api.has_param :breakdowns, { list: { enum: -> { AdsInsights::BREAKDOWNS }} }
+        api.has_param :date_preset, { enum: -> { AdsInsights::DATE_PRESET }}
+        api.has_param :default_summary, 'bool'
+        api.has_param :export_columns, { list: 'string' }
+        api.has_param :export_format, 'string'
+        api.has_param :export_name, 'string'
+        api.has_param :fields, { list: { enum: -> { AdsInsights::SUMMARY }} }
+        api.has_param :filtering, { list: 'object' }
+        api.has_param :level, { enum: -> { AdsInsights::LEVEL }}
+        api.has_param :product_id_limit, 'int'
+        api.has_param :sort, { list: 'string' }
+        api.has_param :summary, { list: { enum: -> { AdsInsights::SUMMARY }} }
+        api.has_param :summary_action_breakdowns, { list: { enum: -> { AdsInsights::SUMMARY_ACTION_BREAKDOWNS }} }
+        api.has_param :time_increment, 'string'
+        api.has_param :time_range, 'object'
+        api.has_param :time_ranges, { list: 'object' }
+      end
+      edge.post 'AdReportRun' do |api|
+        api.has_param :action_attribution_windows, { list: { enum: -> { AdsInsights::ACTION_ATTRIBUTION_WINDOWS }} }
+        api.has_param :action_breakdowns, { list: { enum: -> { AdsInsights::ACTION_BREAKDOWNS }} }
+        api.has_param :action_report_time, { enum: -> { AdsInsights::ACTION_REPORT_TIME }}
+        api.has_param :breakdowns, { list: { enum: -> { AdsInsights::BREAKDOWNS }} }
+        api.has_param :date_preset, { enum: -> { AdsInsights::DATE_PRESET }}
+        api.has_param :default_summary, 'bool'
+        api.has_param :export_columns, { list: 'string' }
+        api.has_param :export_format, 'string'
+        api.has_param :export_name, 'string'
+        api.has_param :fields, { list: { enum: -> { AdsInsights::SUMMARY }} }
+        api.has_param :filtering, { list: 'object' }
+        api.has_param :level, { enum: -> { AdsInsights::LEVEL }}
+        api.has_param :product_id_limit, 'int'
+        api.has_param :sort, { list: 'string' }
+        api.has_param :summary, { list: { enum: -> { AdsInsights::SUMMARY }} }
+        api.has_param :summary_action_breakdowns, { list: { enum: -> { AdsInsights::SUMMARY_ACTION_BREAKDOWNS }} }
+        api.has_param :time_increment, 'string'
+        api.has_param :time_range, 'object'
+        api.has_param :time_ranges, { list: 'object' }
+      end
+    end
+
+    has_edge :keywordstats do |edge|
+      edge.get 'AdKeywordStats' do |api|
+        api.has_param :date, 'datetime'
+      end
+    end
+
+    has_edge :leads do |edge|
+      edge.get 'Lead'
+    end
+
+    has_edge :previews do |edge|
+      edge.get 'AdPreview' do |api|
+        api.has_param :ad_format, { enum: -> { AdPreview::AD_FORMAT }}
+        api.has_param :end_date, 'datetime'
+        api.has_param :height, 'int'
+        api.has_param :locale, 'string'
+        api.has_param :place_page_id, 'int'
+        api.has_param :post, 'object'
+        api.has_param :product_item_ids, { list: 'string' }
+        api.has_param :start_date, 'datetime'
+        api.has_param :width, 'int'
+      end
+    end
+
+    has_edge :targetingsentencelines do |edge|
+      edge.get 'TargetingSentenceLine'
+    end
+
+  end
+end