Ad Campaigns

The Basics

If you have questions regarding how advertising works on Facebook and Google, including the structure of ad campaigns on those ad platforms, we recommend that you start by reviewing our Advertising Fundamentals documentation here.

Data Model

ToneDen provides an API that allows you to easily create advertising campaigns on either Facebook or Google. Our simple API abstracts away many of the difficult and time-consuming procedures involved in creating the components of these campaigns on their respective advertising platforms. Our ad campaign model represents the complexities of these ad campaigns using a platform-agnostic schema which is visible in the documentation for the POST /advertising/campaigns endpoint.

Core Concepts

Below you will find an explanation of how the ToneDen data model represents the core components of ad campaigns on Facebook and Google.

Objective

In order to create an ad campaign, you must first decide what the goal of the campaign will be. The target_type field specifies what type of campaign to run, and the target field specifies what the object to promote is. Below is a table of the different available target types.

target_type Valuetarget FormatAvailable PlatformsDescription
conversionURLFacebookOptimize the campaign for the conversion event specified in the optimization_id field. Users will be sent to the URL specified in the target field.
eventFacebook event IDFacebookOptimize the campaign to drive users to RSVP to the specified Facebook event.
likesFacebook page IDFacebookOptimize the campaign to drive users to like the specified Facebook page.
linkURLFacebook, GoogleOptimize the campaign to drive users to the specified URL.
post_engagementFacebook post IDFacebookOptimize the campaign to get users to interact with the specified Facebook post. Note that the creatives field is ignored for this campaign type.
video_viewsFacebook video IDFacebookOptimize the campaign to get users to watch the specified Facebook video.

Creative

An essential part of creating an ad campaign is determining how it will look to users who see it. Each ad platform has different sets of fields that define the look and feel of the ads in a campaign. A detailed description of which fields can be specified for different ad platforms can be found under the 'creatives' field in the documentation for the POST /advertising/campaigns endpoint.

The creatives field is where the look and feel of the ads in a campaign are specified in the ToneDen ad campaign model. Each field of the creative is an array– when multiple values for a field are specified, we will automatically create variations of the creative using each individual value and test those variations against each other to determine which ads are most effective. For example, if you run a Facebook ad with 3 items in the creatives.text array and 2 items in the creatives.display_asset array, you will end up with 6 different creative variations being tested against each other. This is known as "creative A/B testing," and is key to creating performant ad campaigns.

Audiences

Audiences determine who sees the ads in an ad campaign. An ad campaign can have one or many audiences, which are simply groups of targeting settings that have their own budgets and performance data. An "audience" in a ToneDen ad campaign will translate directly to an adset in Facebook, and an adgroup in Google.

In the ToneDen ad campaign model, audiences are represented by the audiences field, which is an array of JSON audience objects. There are many different types of audiences available in the ToneDen interface, and the type of the audience is determined by the values of the data_source_platform and data_source audience fields. Below is a table of all audience types available.

Audience Type Namedata_source_platformdata_sourceAvailable PlatformsAudience-Specific Fields (* = optional)DescriptionCan Create Lookalike (Y/N)?
Facebook Custom AudiencefacebookallFacebookTarget members of one or more Facebook custom audiences.Y
Interest AudiencefacebookinterestsFacebookTarget people interested in a Facebook interest.N
Everyone in a Locationfacebookeveryone-in-a-locationFacebookTarget everyone in a specific location.N
People Who Engaged With Your Eventfacebookevent-engagersFacebookevent_ids (array of Facebook event IDs)Target people who engaged with one or more Facebook events.Y
People Who Viewed Your Videosfacebookvideo-viewersFacebookpage_ids (array of Facebook page IDs)Target people who viewed videos belonging to one or more pages.Y
People Who Engaged With Your Pagefacebookpage-engagersFacebookpage_ids (array of Facebook page IDs)Target people who engaged with one or more Facebook pages.Y
Facebook Page Likesfacebookpage-likesFacebookpage_ids (array of Facebook page IDs)Target people who liked one or more Facebook pages.Y
Friends of People Who Like a Pagefacebookfriends-of-page-likesFacebookpage_ids (array of Facebook page IDs)Target friends of people who liked one or more Facebook pages.Y
Pixel Event AudiencefacebookeventFacebookevent_id (ID of Facebook conversion event)

pixel_id* (ID of Facebook pixel)
Target people who performed a specific Facebook conversion event.Y
Grouped Remarketing Audiencefacebookgrouped-remarketingFacebookinstagram_business_account* (array of IG business account IDs)

pixel_id* (ID of Facebook pixel)

page_ids* (array of Facebook page IDs)

list_id* (MailChimp list ID)
A combination of our most popular remarketing audiences. Includes the Instagram Account Engagers, Website Visitors, Facebook Event Engagers, Facebook Page Engagers, and Mailchimp List audiences.N
Instagram Profile Visitors and EngagersinstagramallFacebookinstagram_business_account (array of IG business account IDs)Targets everyone who has interacted with an Instagram account.Y
Mailchimp ListmailchimplistFacebooklist_id (ID of a Mailchimp list)Targets all members of a Mailchimp list.Y
Mailchimp Best SubscribersmailchimpopenersFacebooklist_id (ID of a Mailchimp list)Targets the most-engaged members of a selected Mailchimp list.Y
Mailchimp Top Listmailchimptop-listFacebookTargets the user's most-engaged Mailchimp list.Y
Website Visitorspixelwebsite-visitorsFacebook, GoogleTargets everyone who has visited websites that have the advertiser's pixel (Facebook pixel or Google conversion tag) installed.
Fanlink VisitorstonedenfanlinkFacebookfanlink_id* (ID of a ToneDen link)Targets everyone who visited a selected ToneDen link, or all of the user's links if no fanlink_id property is specified.
Google Search Keywordgooglesearch-keywordGooglekeywords (array of keyword strings)Targets everyone who has searched for one of the selected keywords or similar keywords.

Budget

The budget of an ad campaign is how much money the advertiser will be paying the ad platform to deliver ads in the campaign. Facebook campaigns can specify either a daily or a lifetime budget (determined by the value of the budget_type field), and Google campaigns can only have a daily budget. The budget is specified in the lowest denomination of the currency that the selected ad account uses– cents for US dollars and Euros. The daily or lifetime budget of the campaign is specified in the budget_amount field.

Schedule

Ad campaigns can be scheduled to start immediately or at some time in the future, and can specify an end time or run indefinitely. The schedule of an ad campaign is determined by the start_timestamp, end_timestamp, and is_continuous fields. The start_timestamp is the date/time the campaign will start, represented as a UNIX timestamp, and the end_timestamp is the date/time the campaign will end. If the is_continuous Boolean is set to true, the end_timestamp field is ignored and the campaign will run until paused.

Note that Google ad campaigns cannot specify a start time, only a start date, so they will start spending at 12:01 AM on the day of the start_timestamp value. The same goes for the end_timestamp.