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 permissions entitled “manage_pages” and “retrieve_leads”. While especially the option “manage_pages” may sound critical at first glance, the naming of this permission is a bit of a poor choice for us as Maileon only needs to list your pages and subscribe the Lead Ad app to your pages to allow Facebook to send new leads through the app to our webhook. We DO NOT manage any pages any further and we DO NOT collect any further data about your pages.
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.
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.
