adparlor-facebook

Master (GitLab CI)

### Master (Solano CI)

Adparlor::Facebook

The adparlor-facebook gem is a ruby library for interacting with the Facebook ads API. Supporting both REST and batch requests.

Installation

Add this line to your application's Gemfile:

gem 'adparlor-facebook', git: 'https://gitlab.ak-networks.com/adparlor/facebook_ruby_ads_sdk.git'

or locally for development

bundle config local.adparlor-facebook ~/Projects/facebook_ruby_ads_sdk

gem 'adparlor-facebook', branch: 'master'

And then execute:

$ bundle

Usage

Graph API

Once an access token is obtained https://developers.facebook.com/docs/facebook-login/access-tokens you can begin making requests to the GraphApi.

#Get an ad account by the id
account = Adparlor::Facebook::GraphApi::AdAccount.get(account_id, access_token: 'access_token')
account.name #-> 'the account name'
account.account_status #-> 'the account status'

#Get an ad creative  by the id
creative = Adparlor::Facebook::GraphApi::AdCreative.get(creative_id, access_token: 'access_token')
creative.id #-> '11111111111111111'

#The Get method also takes the fields option like the graph api by default only returning the minimal fields
creative = Adparlor::Facebook::GraphApi::AdCreative.get(creative_id, access_token: 'access_token', fields: %w(body image_hash image_url ...))
#OR
creative = Adparlor::Facebook::GraphApi::AdCreative.get(creative_id, access_token: 'access_token', fields: Adparlor::Facebook::GraphApi::AdCreative.fields(:all))
creative.id #-> '11111111111111111'
creative.name #-> 'the creatives name'
creative.thumbnail_url #-> 'https://facebook.com/image...'

#You can also get objects by their edges as referred to in the Facebook documentation
#which returns a memoized array of object types.
account = Adparlor::Facebook::GraphApi::AdAccount.get(account_id, access_token: 'access_token')
account.adcreatives.all #-> [Adparlor::Facebook::GraphApi::AdCreative<...>, Adparlor::Facebook::GraphApi::AdCreative<...>, Adparlor::Facebook::GraphApi::AdCreative<...>, ...]
account.adimages.all #-> [Adparlor::Facebook::GraphApi::AdImage<...>, Adparlor::Facebook::GraphApi::AdImage<...>, Adparlor::Facebook::GraphApi::AdImage<...>, ...]
account.campaigns.all #-> [Adparlor::Facebook::GraphApi::Campaign<...>, Adparlor::Facebook::GraphApi::Campaign<...>, Adparlor::Facebook::GraphApi::Campaign<...>, ...]

#The all method also takes the fields option like the graph api by default only returning the minimal fields
account.adcreatives.all.first #-> Adparlor::Facebook::GraphApi::AdCreative<@id => '1111111111111111'>
account.adcreatives.all(Adparlor::Facebook::GraphApi::AdCreative.fields(:all))).first #-> Adparlor::Facebook::GraphApi::AdCreative<@id='1111111111111111', @body='...', @image_hash='...'>

#The edges also implement create and delete options
account.adimages.delete(hash: '6aec0dd976393abfad84e8f2511960a8') #-> response.body = {"success" => true}

account.adimages.create(source: 'http://www.example.com/url/to/image.png')
#OR
account.adimages.create(source: '/path/to/image.png') #-> response.body = :images => { :url => 'https://facebook.com/image/localtion.png', :hash => 'd0f7567af280e1f6760457ff4df782d8' }

Batch requests

If making large numbers of requests at the same time or requests that depend on each other the batch object can be used.

#The batch api requires an access token in the case some of the requests use different tokens
#or one is not supplied for fallback purposes.
account = Adparlor::Facebook::GraphApi::AdAccount.get(account_id, access_token: 'access_token')
response = account.batch do |batch|
  batch.get account.id, AdImage, fields: [:id, :name, :hash] # uses the parent objects token
  batch.get account.id, Campaign, access_token: account.access_token # uses the parent objects token but it is supplied
  batch.get account2.id, AdImage, access_token: account2.access_token, fields: [:id, :name, :height]
end
response #-> [[AdImage, AdImage, ...],[Campaign, Campaign, ...],[AdImage, AdImage, ...]]

#The object can also be created without an account if the requests are all different accounts or non account level objects
#This will use the access token of the first object to be the top level access token
response = Adparlor::Facebook::GraphObject.new.batch do |batch|
  batch.get nil, AdCreative, id: '6666666666666', access_token: 'access_token'
  batch.get nil, AdCreative, id: '7777777777777', access_token: 'access_token'
end

#Posting follows the same style request, files should be accompanied by the source key.
response = account.batch do |batch|
  batch.post account.id, AdImage, source: 'http://www.example.com/url/for/image.png' # uses the parent objects token
  batch.post account2.id, AdImage, source: 'http://www.example.com/url/for/othe-image.png', access_token: account2.access_token # uses its own token
end
response #-> [AdImage, AdImage]

#Deleting follows the same style request
response = account.batch do |batch|
  batch.delete account.id, AdImage, hash: 'bee06e2e03f9b5a32419855e2c7a4225'
  batch.delete account.id, AdImage, hash: 'd8ebd0caddecb512ec3b782ae9498e13'
end

#You can mix up requests
response = account.batch do |batch|
  batch.post account.id, AdImage, source: 'http://www.example.com/url/for/image.png'
  batch.post account2.id, AdImage, source: 'http://www.example.com/url/for/othe-image.png', access_token: account2.access_token
  batch.get account.id, AdImage, fields: [:id, :name, :hash]
  batch.get account.id, Campaign
end
response #-> [AdImage, AdImage, [AdImage, AdImage, ...],[Campaign, Campaign, ...]]

#You can post requests that are dependent on other requests
#In this case the post that another post is dependent on will supply a name to the options parameter
#which is then referred to in dependents posts appropriate column.
#in this case the campaign post gets the name 'create_campaign' the following request refers to it
#using the JSONPath expression format required by the batch api '{result=create_campaign:$.id}'
# for more information visit: https://developers.facebook.com/docs/marketing-api/batch-requests/v2.5
response = account.batch do |batch|
  batch.post account.id, Campaign,
             { name: 'A Test Campaign', objective: 'LOCAL_AWARENESS', status: 'PAUSED' },
             name: 'create_campaign'
  batch.post account.id, AdSet,
             name: 'A Test AdSet', daily_budget: 135, start_time: '00:05:00',
             campaign_id: '{result=create_campaign:$.id}', bid_amount: 150,
             billing_event: 'IMPRESSIONS', optimization_goal: 'REACH',
             targeting: {
               geo_locations: { cities: [{ key: '2418956', radius: 12, distance_unit: 'mile' }] },
               page_types: %w(desktopfeed mobilefeed)
             }, status: 'PAUSED',
             promoted_object: { page_id: your_page_id }
end
response #-> [null, AdSet]

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

License

The gem is available as open source under the terms of the MIT License.

TODO

• Create requests should probably return an instance of the object instead of the Faraday body
• ?Delete requests should return true if deleted or error message?
• Continue to add endpoints
• More configurable tests for testing live instead of the vcr cassettes.