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.
gem install facebook_ads
Or, add the following to your Gemfile:
gem 'facebook_ads', '~> 0.7'
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]'
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]'
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
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:
You'll find usage examples for each of these 7 objects below.
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.
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
Notes:
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)
Notes:
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
Notes:
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
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)
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
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)
List all product catalogs:
FacebookAds::AdProductCatalog.all
Create a new product catalog:
catalog = FacebookAds::AdProductCatalog.create(name: 'test')
Delete a product catalog:
catalog.destroy