Lead Ads Form Builder

On Wednesday, Facebook launched lead ads to all advertisers and developers. Lead ads are ad units that give people a quick and privacy-safe way to sign up to receive information from businesses, like newsletters, quotes and offers. Alongside the product, we have also launched a set of complementing APIs and a new method in the Facebook JS SDK that will invoke the form builder.

The form builder is a core component to the lead ads product. An advertiser can use the form builder to specify which fields they want to request, select from a list of pre-defined questions, or even create their own custom questions.

This blog post will detail how to use the form builder JS and how to handle its callback. If you are looking for step-by-step instructions on creating a lead ad, check out our documentation here.

The form builder dialog can be called using the following JavaScript. It's important to note that creating popups should only be done after a click event, as modern browsers will block pop-ups that don't look like they were intentionally requested by the user.

<script type="text/javascript">
$('#fb-form-builder').click(function() {
FB.ui({
method: 'lead_gen',
page_id: <PAGE_ID>,
ad_account_id: <AD_ACCOUNT_ID>, // Note: This does NOT contain 'act_'
}, handleFormResponse);
});
</script>

<a href="javascript:void(0);" id="fb-form-builder">Launch Form Builder</a>

When the click event is fired on the #fb-form-builder element, the following popup will be deployed on your platform:

Note that the FB.ui method's second parameter is a callback function (handleFormResponse). This function is called after the user has completed filling out the form builder with the following payload sent into it:

{
follow_up_action_text: "<FOLLOW_UP_ACTION_TEXT>",
follow_up_action_url: "<FOLLOW_UP_ACTION_URL>",
formID: <FORM_ID>,
form_url: "<FORM_URL>",
is_tcpa_compliant: false,
name: "My+Form",
pageID: <PAGE_ID>,
privacy_policy_url: "<PRIVACY_POLICY_URL>",
status: "success"
}

Here's an example of how you might implement handleFormResponse.

function handleFormResponse(payload) {
// Pull the data you'll need out of the payload.
var formID = payload.formID;
var formURL = payload.form_url;
var pageID = payload.pageID;
var formName = payload.name;

console.log("You just created a new form named " + formName + "!");

// Use these two new parameters to construct an
// object_story_spec for building a creative.
var object_story_spec = {
"page_id": pageID,
"link_data": {
"call_to_action": {
"type": "SIGN_UP",
"value": {
"lead_gen_form_id": formID
}
},
"name": "Ad Creative for " + formName,
"link": formURL,
"caption": "Fill out my form!",
"description": "This is my description!",
"image_hash": "<IMAGE_HASH>"
}
};

// Abstracted the actual ads creative creation.
createAdCreative(object_story_spec);
}

Here are other posts and articles that may be helpful:

• Lead Ads Documentation
• Realtime Updates
• Setting up an endpoint to ingest Realtime Updates