Managing Facebook Offline Conversions via APIs

Uploading offline events to your Facebook Business Manager using Python SDK

Nicolò Gasparini

--

What are Facebook Offline Events?

Offline events are, as the name suggests, actions that your customers will take in-store or at an event. Facebook has no way to track it so it lets you upload them. There are 9 kinds of events you can track: ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other
We will focus on the most important one: the purchase, or conversion.

Why and when should I use them?

Facebook campaigns might lead to real-world events that the ad platform is unable to associate with, but knowing if the users that saw your ads actually purchased something will help you understand the effectiveness of every campaign.

Ads on Facebook will often lead users to in-store purchases

The complexity of evaluating an online ad campaign is a difficult process, the customer journey is always a complex path that has many unclear steps. The only reliable metrics for online events were website pixels, before offline conversions.

You can also create a Facebook audience based on the pool of users that made some offline actions. If you’re tracking leads, you can target this audience with a different campaign or, if you are tracking purchases, you can choose not to display ads for this kind of audience, knowing they wouldn’t buy again your products.

In short, you should use them to validate and improve the efficiency of your campaigns.

How does the matching work?

Facebook offline events work by syncing people that saw your ad with people that made an offline action. Once you upload an event, you must submit some match_keys, such as email, phone number, name, or last name. Facebook will then use this data to match people in their databases. If a Facebook user saw your ad and made an offline action, the match is complete!

It is quite a simple connection, the complexity of this comes from the amount of data Facebook has to process in order to create a successful and trustworthy match.

Let’s upload some data!

1. Setup

To use Facebook APIs, you need a Facebook App.
You can create one in the Facebook Developers portal, after that you can perform the authentication first flow with your Facebook user, keep in mind this user must have the rights to create an Offline Event Set and upload events.

For this article I will assume the authentication as done, you can find here a complete setup guide using python SDK, or you can get an access token from the graph explorer tool and use that to try this code.

2. Create an Offline Event Set

The Event Set will be the events container connected to your ad account. It will link your campaigns with the offline events uploaded.

Find the event sets in ‘Event Manager’ > ‘Offline Events’

You can create one manually from the Business Manager.

Simply click on Add New Data Source and Offline Event Set, you will be prompted to select an account to sync data with.

If you wish to create one through APIs instead, this snippet will allow you to create a data set and get its ID:

3. Upload the events

This step depends entirely on your source of the event list. This example will reflect my case, which was a .csv file, with every line representing an event.

I used pandas to read the .csv file and transform its elements in a list of python dictionaries, each of which containing only the match keys provided in the event row.

Keep in mind that hashing is required for every match_key you send, except for ‘third party user IDs’ and ‘lead IDs from lead ads’. In this case, the .csv file had every field already hashed.

With the function above, we’ll only send the match keys we actually have, a single event will have the following structure, the email and phone fields will be lists because more values can be sent to improve the matching possibilities:

{ 'currency': 'EUR',
'event_name': 'Purchase',
'event_time': '1562112000',
'match_keys': {
"email": ["hashed_email"],
"phone": ["hashed_phone"],
"fn": "hashed_first_name",
"ln": "hashed_last_name"
},
'order_id': '123XXX',
'value': 19.99}

Once you complete the iteration, visit the dataset page in the Business Manager, you will probably see something like this graph, with the processing warning. When the system ends matching the users to your events, you will see the match rate and attribution rate.

You will see a Processing warning soon after your data is uploaded

Now you can schedule an automated job to upload periodically your events, Facebook guidelines recommend uploading your events at least every 48 hours.

Here, have some more tips

I collected some useful tips discovered while working with offline events that I thought could be useful:

  • Create an event set to an ad-account and switch on auto-sync before starting the campaigns. The events won’t be associated retroactively
  • Include an order ID to every Purchase event, this will help Facebook’s deduplication process in understanding if an event is in fact a duplicate
  • Try not to upload the same event two times, as the deduplication process only consider the last 7 days to check for duplicated events. Once you upload an event, you cannot erase it
  • Follow the advice you will see on the diagnostic page of your Offline Event Set, this will tell you if your process is working nicely or if it needs some retouch
some diagnostic advice from Facebook

--

--

Nicolò Gasparini

Software Engineer and full stack developer 💻 based in Italy — /in/nicologasparini/