Facebook LeadAds
- Marcus Beckerle (Unlicensed)
What are Facebook Lead Ads?
Facebook Lead Ads enable you to create forms that collect data such as addresses, first names, last names, etc. and call Facebook users to action, e.g. to subscribe to your newsletter. These forms are assigned to a Facebook page and can be shown as advertisements to a large group of users.
For further information regarding Facebook Lead Ads, please refer to:
How does automatic submission work?
Facebook allows the downloading of leads as files but in order to submit such leads to your Maileon newsletter account automatically, Facebook relies on a system that notifies Maileon about new leads. To protect data, Facebook only sends some of the required data in the form of abstract IDs. Maileon must then contact Facebook, authorize and collect leads data.
To authenticate the authorization, Facebook uses a standard called OAuth. A user with administrative privileges can log in using his private credentials and create an abstract token. With this token, a third-party application can then contact the Facebook API and authorize API calls “in the name of” the original user without having his username and password. The tokens can be assigned an expiration date and can be instantly revoked by the user.
In Maileon, the generation of the aforementioned tokens is done by going to “Settings” (1) “Lists & Contacts: Plugins” (2) and clicking on the “Load Facebook configuration” button (3), see Figure 1.
Once you have clicked on the button, you will be directed to a Facebook login page. If you are already logged into your account in the same browser and there is a session saved, you do not need to log in separately. The popup is the login mask from Facebook, created by the Facebook SDK, none of your login data is saved within Maileon. The popup will then ask you for the following permissions to access leads of your page:
All permissions are required for the full working app and are defined as follows, including technical detail, also see technical documentation for retrieving ads: Leads - Webhooks from Meta - Documentation - Meta for Developers
Manage accounts, settings and webhooks for a Page
Technical name: pages_manage_metadata
Description: The pages_manage_metadata permission allows your app to subscribe and receive webhooks about activity on the Page, and to update settings on the Page.
Reason: We need this permission to register the webhook that notifies Maileon about new leads. We DO NOT manage pages any further and we DO NOT collect any further data about your pages.
Documentation: Permissions Reference - Graph API - Documentation - Meta for DevelopersShow a list of the Pages you manage
Technical name: pages_show_list
Description: The pages_show_list permission allows your app to access the list of Pages a person manages.
Reason: We need this permission to read the list of pages to add them to Maileon
Documentation: Permissions Reference - Graph API - Documentation - Meta for DevelopersAccess leads for your Pages
Technical name: leads_retrieval
Description: The leads_retrieval permission allows your app to retrieve and read all information captured by a lead ads form associated with an ad created in Ads Manager or the Marketing API.
Reason: We need this permission to retrieve details of a lead, e.g. the email address
Documentation: Permissions Reference - Graph API - Documentation - Meta for DevelopersRead content posted on the Page
Technical name: pages_read_engagement
Description: The pages_read_engagement permission allows your app to read content (posts, photos, videos, events) posted by the Page, read followers data (including name, PSID), and profile picture, and read metadata and other insights about the Page.
Reason: The option to read posts of the pages can be disabled, it comes along with asking for managing pages but is not required.
Documentation: Permissions Reference - Graph API - Documentation - Meta for Developers
Once authenticated with Facebook, Maileon will generate a token that allows communication with Facebook and connect the pages of which you are the administrator. You can remove pages from your account at any time which coincidentally, would also unsubscribe the Lead Ad app from your pages. Once completed, Maileon will save a long living page token for each page to be able to access the lead details at a later point in time. The token originally created (with the “manage_pages” and “retrieve_leads” permission) is not saved and if you want to add a new page, you would need to log in again.
Figure 2 illustrates an overview of the process of when a new lead is registered. First, Facebook sends a notification to the Maileon webhook. The notification contains an ID for the lead and the source (ID of the page) of the registration. Maileon then resolves the page ID to the page token and asks Facebook for more details regarding the lead, e.g. the E-mail address, the first and last name. Per your configuration, Maileon then creates the contact in Maileon and if properly configured, sends a DOI mail.
Setting up the connection in Maileon
The previous chapter explains the general process, while this chapter will guide you through the setup process inside Maileon more in detail.
Under “Settings” “Lists & Contacts: Plugins” click on the “Load Facebook configuration” button (Figure 3).
A new window will open that comes from Facebook and asks for credentials of the user that has permissions to retrieve leads from the page you want to add (Figure 1).
After accepting the permissions, the pages will be linked with your Maileon account and you will get a confirmation showing which pages have been linked (Figure 4). You can delete pages that you do not want to ling, afterwards.
Now you should see the page as being added in the overview on the bottom (Figure 5).
Once added, the status should be set to „valid“. If this is not the case, please contact our customer support: service@xqueue.com.
On top of the table, you see the settings how contacts should be added to your Maileon account. In Germany the DOI process should be selected but for other countries it might be legal to add a contact without sending a DOI, as well (Figure 6).
Creating a form in Facebook
Log in into your Facebook account and open the configuration of your page by selecting it using the Dropdown on the upper right. Now select “Publishing Tools” (in German “Beitragsoptionen”) from right menu, see Figure 7. If you haven’t pinned the “Instant Forms” tool to your menu, go to “all tools” and search for the forms tool, see Figure 8. Either create a new form or copy/edit an existing form. Now you can set up the fields of your form and if you are done make sure to also set up a correct mapping, as Facebook names the fields in the “current” language, so if Maileon expects a field called “country” and you created the form with German UI, it will be called “land” instead and Maileon will not be able to find it as there is no mapping for all available languages.
The following table defines the valid field names. Please ensure, that the field for the E-Mail is called “email” otherwise the contact cannot be created. As we saw lots of customers using other names, we extended the service to also accept “e-mail”, “e-mail-address” or “e-mail-adresse”. The table below shows the list of field names that are predefined by Facebook (bold) as well as a list of alternatively recognized names for each entry.
Field | Allowed Field Name (Default used by Facebook is marked bold) |
email, e-mail, e-mail-adresse, e-mail-address | |
Full name | full_name, fullname |
First Name | first_name, firstname, vorname |
Last Name | last_name, lastname, nachname |
Street | street_address, street, streetaddress, straße, strasse |
ZIP-Code | post_code, postcode, zip, postleitzahl |
City | city, stadt |
Province | province, bundesland |
Country | country, land |
Organization | company_name, companyname, unternehmen, organization, organisation |
Gender* | gender*, geschlecht |
Date of Birth | date_of_birth**, birthday, geburtstag, geburtsdatum |
*For gender valid case insensitive values: m, male, mann, männlich, f, female, frau, w, weiblich.
** Allowed date formats: MM/dd/yyyy, from 17.11.2023 also yyyy-MM-dd and yyyyMMdd
Submitted Meta-Information
Along with the contact data a set of customfields is created that provides details about where the contact came from.
Customfield | Description |
fbla_src | Static marker, currently fixed to value: Facebook Lead Ads |
fbla_subscription_form | The ID of the subscription form |
fbla_subscription_page | The name of the subscription page |
Example:
Testing Facebook Lead Ads
Once you have set up a page, Lead Ad form and a connection to Maileon, you will then be able to navigate to the Lead Ad testing page (login required): https://developers.facebook.com/tools/lead-ads-testing. Select your page and the form you would like to test. If you added the page in the Maileon configuration, you should now be able to see a webhook subscription for the page with our app with ID “776876729133097”, see Figure 10.
You are now able to directly create a contact by clicking on “create lead” with the default data (the default E-mail is test@fb.com) or by clicking on “Preview Form” to fill in your own data. It is important to make sure that there is no lead yet. If there is one, Facebook will inform you to click the “Delete Lead” button first as the testing tool can only manage one test lead.
After you have created the lead, you can the select “Track Status.” This may take a few seconds and if the process continues to lag, click on the “Track Status” option again until the status is no longer “pending.” Figure 11 depicts a successful run. It also shows that the data initially submitted to Maileon contains no private data. Please disregard the second App, as it is just a test app and is okay if it fails, you will not see that app in your account…
Now that you have confirmed that the connection functions technically, you can go to your Maileon Account and have a look at your new contact, see Figure 12. For this contact, the quick “create lead” button with some default data was used.
Troubleshooting
Occasionally we experienced problems with not properly working integrations and for now we identified the following problems
If the user that added Facebook to Maileon changes his/her password or access to the page the form belongs to is removed, the access token is invalidated by Facebook and Maileon cannot access leads any longer
If the user does not log in into Facebook for three months after adding Facebook to Maileon, data access will be denied by Facebook
Some customers seemed to have everything correctly set up but we experienced Facebooks' API telling us permission problems. Since the permission handling on the side of Facebook can be very complex, those customers had to contact Facebook customer support and eventually found the problems. One customer reported the user adding Facebook to Maileon required “complete admin access on the Business-Manager”.