facebookbusiness 0.3.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a17922edffc590a7659c5ea3d636d17d80ebc6bb41288b261f79012c73a8a9c
+  data.tar.gz: 132894d87cf48e72cc1a82558c5e4f35d8d5c99802664eb5464eac3f7b6b2fc6
+SHA512:
+  metadata.gz: 9321bcea3ff10630d2275d0d442601677fe87c93b46878ddc901eddba880102df592bb57494c6cd1a8a1b559e3fc4a36beeb62df3a99857b86c76ddec2a93286
+  data.tar.gz: 6b04d771533a1526fbe4e403a21fb4c383c3b725f6cd7eb12030e067ac7f59aa98f05aae7018e3e9ae2b5ff8c9de1c88e3bda5d77a74aee006f408bfa68f3d79

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,256 @@
+# Facebook Business SDK for Ruby
+
+### Introduction
+
+The Facebook <a href="https://developers.facebook.com/docs/business-sdk" target="_blank">Business SDK</a> is a one-stop shop to help our partners better serve their businesses. Partners are using multiple Facebook API's to server the needs of their clients. Adopting all these API's and keeping them up to date across the various platforms can be time consuming and ultimately prohibitive. For this reason Facebook has developed the Business SDK bundling many of its APIs into one SDK to ease implementation and upkeep. The Business SDK is an upgraded version of the Marketing API SDK that includes the Marketing API as well as many Facebook APIs from different platforms such as Pages, Business Manager, Instagram, etc.
+
+## Quick Start
+
+Business SDK <a href="https://developers.facebook.com/docs/business-sdk/getting-started" target="_blank">Getting Started Guide</a>
+
+## 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.
+
+### Register An App
+
+To get started with the SDK, you must have an app
+registered on <a href="https://developers.facebook.com/" target="_blank">developers.facebook.com</a>.
+
+To manage the Marketing API, please visit your
+<a href="https://developers.facebook.com/apps/<YOUR APP ID>/dashboard"> App Dashboard </a>
+and add the <b>Marketing API</b> product to your app.
+
+**IMPORTANT**: For security, it is recommended that you turn on 'App Secret
+Proof for Server API calls' in your app's Settings->Advanced page.
+
+### Obtain An Access Token
+
+When someone connects with an app using Facebook Login and approves the request
+for permissions, the app obtains an access token that provides temporary, secure
+access to Facebook APIs.
+
+An access token is an opaque string that identifies a User, app, or Page.
+
+For example, to access the Marketing API, you need to generate a User access token
+for your app and ask for the ``ads_management`` permission; to access Pages API,
+you need to generate a Page access token for your app and ask for the ``manage_page`` permission.
+
+Refer to our
+<a href="https://developers.facebook.com/docs/facebook-login/access-tokens" target="_blank">
+Access Token Guide</a> to learn more.
+
+For now, we can use the
+<a href="https://developers.facebook.com/tools/explorer" target="_blank">Graph Explorer</a>
+to get an access token.
+
+## 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')
+puts "Ad Account Name: #{ad_account.name}"
+```
+
+The `#get` method doesn't trigger the `GET` request immediately. 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|
+  puts 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.rb

@@ -0,0 +1,72 @@
+# 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 'facebook_ads/version'
+require 'facebook_ads/helpers/shortcuts'
+
+module FacebookAds
+  DEFAULT_API_VERSION = 'v' + API_VERSION
+  DEFAULT_HOST = 'graph.facebook.com'
+
+  extend self
+  extend Shortcuts
+
+  def with_session(access_token, secret = nil, api_version = DEFAULT_API_VERSION)
+    original_session = Session.current_session
+    Session.current_session = Session.new(access_token, secret, api_version)
+    yield
+    Session.current_session = original_session
+  end
+
+  def configure
+    @config ||= Config.new
+    yield @config if block_given?
+    @config
+  end
+
+  alias_method :config, :configure
+
+  require 'facebook_ads/ruby2patch'
+
+  require 'facebook_ads/config'
+  require 'facebook_ads/errors'
+  require 'facebook_ads/session'
+  require 'facebook_ads/fields'
+  require 'facebook_ads/edge'
+  require 'facebook_ads/param_set'
+  require 'facebook_ads/ad_object'
+  require 'facebook_ads/field_types'
+
+  require 'facebook_ads/utils/utils'
+  require 'facebook_ads/videos/video_io'
+
+  require 'facebook_ads/batch_api/batch'
+  require 'facebook_ads/batch_api/batch_proxy'
+
+  # Autoload Ab Objects Helpers
+  Dir.glob(File.expand_path(File.join(__FILE__, '..', 'facebook_ads', 'ad_objects', 'helpers', '*.rb'))).each do |file|
+    class_name = File.basename(file, '.rb').split('_').map(&:capitalize).join.to_sym
+    autoload class_name, file
+  end
+
+  # Autoload AdObjects
+  Dir.glob(File.expand_path(File.join(__FILE__, '..', 'facebook_ads', 'ad_objects', '*.rb'))).each do |file|
+    class_name = File.basename(file, '.rb').split('_').map(&:capitalize).join.to_sym
+    autoload class_name, file
+  end
+end

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, :__all_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.__all_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
+      @__all_fields.to_a.join(',')
+    end
+
+    def __all_fields=(fields)
+      @__all_fields = Set.new((fields.is_a?(String) ? fields.split(',') : fields.map(&:to_s)).map(&:to_sym))
+    end
+
+    def loaded?
+      (@__all_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