Facebook Marketing API SDK for Ruby

This gem allows you to manage your Facebook Ads using a ruby interface. It allows you to list, create, update and destroy Facebook Ad objects (campaigns, ad sets, ads, etc) and get real-time insights about the performance of Facebook Ads.

Install

gem install facebook_ads

Or, add the following to your Gemfile:

gem 'facebook_ads', '~> 0.7'

Permissions

You'll need an Access Token with ads_management permissions in order to use Facebook's Marketing API.

FacebookAds.access_token = '[YOUR_ACCESS_TOKEN]'

You can also optionally include an App Secret if you need one for your application.

FacebookAds.app_secret = '[YOUR_APP_SECRET]'

API Version

This gem currently defaults v3.2 of the Marketing API. You can change the version as desired with the following:

FacebookAds.base_uri = 'https://graph.facebook.com/[desired-version-here]'

Console

This gem provides a console using Pry and AwesomePrint for you to test & debug. It reads the Access Token from a file called test_access_token.

echo [YOUR_ACCESS_TOKEN] > test_access_token
bin/facebook_ads_console

Usage Examples

A strong understanding of the Facebook Ads object structure will greatly help you use this gem.

The basic object structure:

In total, there are 7 Facebook Ads objects that can be interacted with via this gem: AdAccount, AdCampaign, AdImage, AdCreative, AdSet, Ad and AdInsight.

The typical flow is as follows:

1. Create an AdCampaign for an AdAccount.
2. Create AdImages for an AdAccount.
3. Create an AdCreative for an AdAccount using the AdImages from #2.
4. Create ad AdSet for the AdCampaign from #1.
5. Create an Ad for the AdSet from #4 using the AdCreative from #3.
6. Monitor the performance of the Ad from #5 using AdInsights.
7. Update the daily budget of the AdSet from #4 as needed.

You'll find usage examples for each of these 7 objects below.

Ad Accounts (Fetch, Find, Update)

Fetch all accounts that can be accessed using your access token:

accounts = FacebookAds::AdAccount.all

Find an account by ID:

account = FacebookAds::AdAccount.find('act_1132789356764349')

Find an account by name:

account = FacebookAds::AdAccount.find_by(name: 'ReFuel4')

Update an account (using both .save() and .update()):

account.name = 'ReFuel4 [Updated]'
account = account.save # Returns the updated object.
account.update(name: 'ReFuel4') # Returns a boolean.

The list of fields that can be updated is here.

Ad Campaigns (Fetch, Find, Create, Update, Destroy)

Fetch all active campaigns:

campaigns = account.ad_campaigns

Fetch all paused campaigns (can pass multiple statuses in the array):

campaigns = account.ad_campaigns(effective_status: ['PAUSED'])

See FacebookAds::AdCampaign::STATUSES for a list of all statuses.

Fetch all campaigns:

campaigns = account.ad_campaigns(effective_status: nil)

Create a new campaign for website conversions that is initially paused:

campaign = account.create_ad_campaign(
  name: 'Test Campaign',
  objective: 'CONVERSIONS',
  status: 'PAUSED'
)

See FacebookAds::AdCampaign::OBJECTIVES for a list of all objectives.

Find a campaign by ID:

campaign = FacebookAds::AdCampaign.find(campaign.id)

Update a campaign (using both .save() and .update()):

campaign.status = 'ACTIVE'
campaign = campaign.save # Returns the updated object.
campaign.update(status: 'PAUSED') # Returns a boolean.

The list of fields that can be updated is here.

Destroy a campaign:

campaign.destroy

Ad Images (Fetch, Find, Create, Destroy)

Notes:

• Images cannot be updated.
• You can upload the same image multiple times and Facebook will de-duplicate them server side.
• An image will always generate the same hash on Facebook's end - even across ad accounts.
• Image uploading via a URL currently assumes a *nix system (Mac OS, linux). It likely will fail on Windows. A cross-platform tempfile-based solution is in the works.
• You can't destroy an image if its being used by a creative. You have to destroy the creative first.

Fetch all images owned by an account:

ad_images = account.ad_images

Create images using an array of URLs:

ad_images = account.create_ad_images([
  'https://d38eepresuu519.cloudfront.net/485674b133dc2f1d66d20c9d52c62bec/original.jpg',
  'https://d38eepresuu519.cloudfront.net/3977d2a47b584820969e2acf4d923e33/original.jpg'
])

Find images using their hash values:

ad_images = account.ad_images(hashes: ad_images.map(&:hash))

Destroy images:

ad_images.map(&:destroy)

Ad Creatives (Fetch, Find, Create, Update, Destroy)

Notes:

• I'd like to add a configuration object that allows you to specify the Facebook Page, Instagram account, website, iOS app and/or Android app that you will be advertising. This is needed when creating both Ad Creative objects and Ad Set objects.

Fetch all creatives owned by an account:

ad_creatives = account.ad_creatives

Create a carousel creative driving installs for an Android app:

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.first.hash, title: 'Image #1 Title' },
    { hash: ad_images.second.hash, title: 'Image #2 Title' }
  ],
  call_to_action_type: 'SHOP_NOW',
  multi_share_optimized: true,
  multi_share_end_card: false
}, creative_type: 'carousel')

See FacebookAds::AdCreative::CALL_TO_ACTION_TYPES for a list of all call to action types.

Create a single image creative advertising an Android app:

image_ad_creative = account.create_ad_creative({
  name: 'Test Single Image Creative',
  page_id: '300664329976860', # Add your Facebook Page ID here.
  message: 'A message.',
  link: 'http://play.google.com/store/apps/details?id=com.tophatter', # Add your Play Store ID here.
  link_title: 'A link title.',
  image_hash: ad_images.first.hash,
  call_to_action_type: 'SHOP_NOW'
}, creative_type: 'image')

Create a single creative for a web link:

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:

ad_creative = FacebookAds::AdCreative.find(ad_creative.id)

Update a creative (using both .save() and .update()):

ad_creative.name = 'Test Carousel Creative [Updated]'
ad_creative = ad_creative.save # Returns the updated object.
ad_creative.update(name: 'Test Carousel Creative') # Returns a boolean.

The list of fields that can be updated is here.

Destroy a creative:

ad_creative.destroy

Ad Sets (Fetch, Find, Create, Update, Destroy)

Notes:

• It's important to make sure your targeting spec makes sense in the context of the promoted object. For example if the promoted object is an iOS app and the targeting spec specifies Android devices your ads are not likely to perform well since no one will be able to download your iOS app.

You interact with ad sets via a campaign:

campaign = account.ad_campaigns(effective_status: nil).first

Fetch all active ad sets for a campaign:

ad_sets = campaign.ad_sets

Fetch all paused ad sets for a campaign (can pass multiple statuses in the array):

ad_sets = campaign.ad_sets(effective_status: ['PAUSED'])

See FacebookAds::AdSet::STATUSES for a list of all statuses.

Fetch all ad sets for a campaign:

ad_sets = campaign.ad_sets(effective_status: nil)

Specify the audience targeted by this ad set:

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

A lot can be done with targeting. You can learn more about targeting specs here.

Create an ad set to drive installs to an Android app using the targeting above:

ad_set = campaign.create_ad_set(
  name: 'Test Ad Set',
  targeting: targeting,
  promoted_object: { # This can be an Android app, iOS app or pixel ID, plus an optional custom event.
    application_id: '295802707128640',
    object_store_url: 'http://play.google.com/store/apps/details?id=com.tophatter',
    custom_event_type: 'PURCHASE'
  },
  optimization_goal: 'OFFSITE_CONVERSIONS',
  daily_budget: 500, # This is in cents, so the daily budget here is $5.
  billing_event: 'IMPRESSIONS',
  status: 'PAUSED',
  bid_strategy: 'LOWEST_COST_WITHOUT_CAP'
)

See FacebookAds::AdSet::OPTIMIZATION_GOALS for a list of all optimization goals. See FacebookAds::AdSet::BILLING_EVENTS for a list of all billing events. See FacebookAds::AdSet::BID_STRATEGIES for a list of all bid strategies.

Find an ad set by ID:

ad_set = FacebookAds::AdSet.find(ad_set.id)

Update an ad set (using both .save() and .update()):

ad_set.status = 'ACTIVE'
ad_set.daily_budget = 400
ad_set = ad_set.save # Returns the updated object.
ad_set.update(status: 'PAUSED', daily_budget: 500) # Returns a boolean.

The list of fields that can be updated is here.

Destroy an ad set:

ad_set.destroy

Ad Set Activities (Fetch)

You interact with activities via an ad set:

ad_set = account.ad_sets(effective_status: nil).first

Fetch all activities in last 24 hours for an ad set:

activities = ad_set.activities

Fetch all activities in last 48 hours for an ad set:

activities = ad_set.activities(from: 2.days.ago, to: Date.today)

Ads (Fetch, Find, Create, Update, Destroy)

You interact with ads via an ad set:

ad_set = account.ad_sets(effective_status: nil).first

Fetch all active ads for an ad set:

ads = ad_set.ads

Fetch all paused ads for an ad set (can pass multiple statuses in the array):

ads = ad_set.ads(effective_status: ['PAUSED'])

See FacebookAds::Ad::STATUSES for a list of all statuses.

Fetch all ads for an ad set:

ads = ad_set.ads(effective_status: nil)

Fetch a creative that we'll use to create an ad:

ad_creative = account.ad_creatives.first

Create an ad:

ad = ad_set.create_ad(name: 'Test Ad', creative_id: ad_creative.id)

Find an ad by ID:

ad = FacebookAds::Ad.find(ad.id)

Update an ad (using both .save() and .update()):

ad.name = 'Test Ad [Updated]'
ad.status = 'ACTIVE'
ad = ad.save # Returns the updated object.
ad.update(name: 'Test Ad', status: 'PAUSED') # Returns a boolean.

The list of fields that can be updated is here.

Destroy an ad:

ad.destroy

Ad Insights (Fetch)

Fetch today's insights for an account:

account.ad_insights

Fetch yesterday's insights for an account:

account.ad_insights(range: Date.yesterday..Date.yesterday)

Fetch today's insights for a campaign:

account.ad_campaigns.last.ad_insights

Fetch yesterday's insights for a campaign:

account.ad_campaigns.last.ad_insights(range: Date.yesterday..Date.yesterday)

Product Catalogs

List all product catalogs:

FacebookAds::AdProductCatalog.all

Create a new product catalog:

catalog = FacebookAds::AdProductCatalog.create(name: 'test')

Delete a product catalog:

catalog.destroy

@TODO:

• Batch operations.