Meta Conversions API extension overview

Last update: July 24, 2024

Topics:
Tags

CREATED FOR:

Developer

The Meta Conversions API allows you to connect your server-side marketing data to Meta technologies in order to optimize your ad targeting, decrease cost per action, and measure results. Events are linked to a Meta Pixel ID and are processed in a similar way to client-side events.

Using the Meta Conversions API extension, you can leverage the API’s capabilities in your event forwarding rules to send data to Meta from the Adobe Experience Platform Edge Network. This document covers how to install the extension and use its capabilities in an event forwarding rule.

Demo

The following video is intended to support your understanding of the Meta Conversions API.

Prerequisites

It is strongly recommended to use Meta Pixel and the Conversions API to share and send the same events from the client side and server side, respectively, since this may help recover events that were not picked up by Meta Pixel. Before installing the Conversions API extension, see the guide on the Meta Pixel extension for steps on how to integrate it in your client-side tag implementations.

NOTE

The section on event deduplication later in this document covers the steps to ensure the same event is not used twice, as it may be received from both the browser and the server.

In order to use the Conversions API extension, you must have access to event forwarding and have a valid Meta account with access to Ad Manager and Event Manager. Specifically, you must copy the ID of an existing Meta Pixel (or create a new Pixel instead) so the extension can be configured to your account.

INFO

If you’re planning to use this extension with mobile app data, or if you also work with offline event data in your Meta campaigns, you’ll need to create your dataset through an existing app and select Create from a pixel ID when prompted. See the article Decide which dataset creation option is right for your business for details. Refer to the Conversions API for App Events document for all the required and optional app tracking parameters.

Install the extension

To install the Meta Conversions API extension, navigate to the Data Collection UI or Experience Platform UI and select Event Forwarding from the left navigation. From here, select a property to add the extension to, or create a new property instead.

Once you have selected or created the desired property, select Extensions in the left navigation, then select the Catalog tab. Search for the Meta Conversions API card, then select Install.

The Install option being selected for the Meta Conversions API extension in the Data Collection UI.

In the configuration view that appears, you must provide the Pixel ID you copied earlier to link the extension to your account. You can paste the ID directly into the input, or you can use a data element instead.

You also need to provide an access token to use the Conversions API specifically. Refer to the Conversions API documentation on generating an access token for steps on how to obtain this value.

When finished, select Save

The Pixel ID provided as a data element in the extension configuration view.

The extension is installed and you can now employ its capabilities in your event forwarding rules.

Integration with the Facebook and Instagram extension

The integration using the Facebook and Instagram extension allows you to quickly authenticate into your Meta Business Account. This then auto-populates your Pixel ID and the Meta Conversions API Access Token, making it easier to install and configure the Meta Conversions API.

A dialogue prompt to authenticate in Facebook and Instagram appears when installing the Meta Conversions API extension.

The Meta Conversions API Extension installation page highlighting Connect to Meta.

A dialogue prompt to authenticate in Facebook and Instagram also appears in the quick start workflow UI within event forwarding.

The quick start workflow UI highlighting Connect to Meta.

Integration with Event Quality Match Score (EMQ)

The integration with Event Quality Match Score (EMQ) allows you to easily view the effectiveness of your implementation by showing EMQ scores. This integration minimizes context switching and helps you improve the success of your Meta Conversions API implementations. These event scores appear in the Meta Conversions API extension configuration screen.

The Meta Conversions API Extension configuration page highlighting View EMQ Score.

Integration with LiveRamp (Alpha)

LiveRamp customers who have LiveRamp’s Authenticated Traffic Solution (ATS) deployed on their sites may opt to share RampIDs as a customer information parameter. Please work with your Meta account team to join the Alpha program for this feature.

The Meta event forwarding Rule configuration page highlighting Partner Name (alpha) and Partner ID (alpha).

Configure an event forwarding rule

This section covers how to use the Conversions API extension in a generic event forwarding rule. In practice, you should configure several rules in order to send all accepted standard events via Meta Pixel and Conversions API. For mobile app data, please see the required fields, app data fields, customer information parameters, and custom data details here.

NOTE

Events should be sent in real time or as close to real time as possible for better ad campaign optimization.

Start creating a new event forwarding rule and configure its conditions as desired. When selecting the actions for the rule, select Meta Conversions API Extension for the extension, then select Send Conversions API Event for the action type.

The Send Page View action type being selected for a rule in the Data Collection UI.

Controls appear that allow you to configure the event data that will be sent to Meta via the Conversions API. These options can be entered directly into the provided inputs, or you can select existing data elements to represent the values instead. The config options are divided into four main sections as outlined below.

Config section

Description

Server Event Parameters

General information about the event, including the time it occurred and the source action that triggered it. Refer to the Meta developer documentation for more information on the standard event parameters accepted by the Conversions API.

If you are using both Meta Pixel and the Conversions API to send events, make sure to include both an Event Name (event_name) and Event ID (event_id) with every event, since these values are used for event deduplication.

You also have the option to Enable Limited Data Use to help comply with customer opt-outs. See the Conversions API documentation on data processing options for details on this feature.

Customer Information Parameters

User identity data that is used to attribute the event to a customer. Some of these values must be hashed before they can be sent to the API.

To ensure a good common API connection and high event match quality (EMQ), it is recommended that you send all accepted customer information parameters alongside server events. These parameters should also be prioritized based on their importance and impact on EMQ.

Custom Data

Additional data to be used for ads delivery optimization, provided in the form of a JSON object. Refer to the Conversions API documentation for more information on the accepted properties for this object.

If you are sending a purchase event, you must use this section to provide the required attributes currency and value.

Test Event

This option is used to verify whether your configuration is causing server events to be received by Meta as expected. To use this feature, select the Send as Test Event checkbox, and then provide a test event code of your choice in the input below. Once the event forwarding rule is deployed, if you configured the extension and action correctly you should seeing activities appearing within the Test Events view in Meta Events Manager.

When finished, select Keep Changes to add the action to the rule configuration.

Keep Changes being selected for the action configuration.

When you are satisfied with the rule, select Save to Library. Finally, publish a new event forwarding build to enable the changes made to the library.

Event deduplication

As mentioned in the prerequisites section, it is recommended that you use both the Meta Pixel tag extension and the Conversions API event forwarding extension to send the same events from the client and server in a redundant setup. This can help recover events that were not picked up by one extension or the other.

If you are sending different event types from the client and server with no overlap between the two, then deduplication is not necessary. However, if any single event is shared by both Meta Pixel and the Conversions API, you must ensure that these redundant events are deduplicated so that your reporting is not adversely affected.

When sending shared events, make sure that you are including an event ID and name with every event that you send from both the client and server. When multiple events with the same ID and name are received, Meta automatically employs several strategies to deduplicate them and keep the most relevant data. See the Meta documentation on deduplication for Meta Pixel and Conversions API events for details on this process.

Quick start workflow: Meta Conversions API Extension (Beta)

IMPORTANT

The quick start feature is available to customers who have purchased the Real-Time CDP Prime and Ultimate package. Please contact your Adobe representative for more information.
This feature is for net new implementations and does not currently support auto installing extensions and configurations on existing tags and event forwarding properties.

NOTE

Any existing client can use the quick start workflows to create a reference implementation that can be used for the following:

Use it as the start of a brand new implementation.
Take advantage of it as a reference implementation that you can examine to see how it has been configured and then replicate in your current production implementations.

The quick start feature helps you get set up with ease and efficiency with the Meta Conversions API and the Meta Pixel extensions. This tool automates multiple steps that are performed in Adobe tags and event forwarding, significantly reducing the set up time.

This feature automatically installs and configures both the Meta Conversions API and the Meta Pixel extensions on a newly auto-generated tags and event forwarding property with the necessary rules and data elements. Additionally, it also auto installs and configures the Experience Platform Web SDK and Datastream. Lastly, the quick start feature auto-publishes the library to the designated URL in a development environment, which enables client side data collection and server side event forwarding in real-time via Event Forwarding and Experience Platform Edge Network.

The following video provides an introduction to the quick start feature.

video poster

https://video.tv.adobe.com/v/3416939?quality=12&learn=on

Install quick start feature

NOTE

This feature is designed to help you get started with an event forwarding implementation. It will not deliver an end to end, fully functional implementation that accommodates all use cases.

This setup auto installs both the Meta Conversions API and the Meta Pixel extensions. This hybrid implementation is recommended by Meta to collect and forward event conversions server side.
The quick setup feature is designed to help customers get started with an event forwarding implementation and is not intended to deliver an end to end, fully functional implementation that accommodates all use cases.

To install the feature, Select Get Started for Send Conversions Data to Meta on the Adobe Experience Platform Data Collection Home page.

Data collection home page showing conversions data to meta

Enter your Domain, then select Next. This domain will be used as a naming convention for your auto generated Tags and Event Forwarding properties, rules, data elements, datastreams, and so on.

Welcome screen requesting domain name

In the Initial Setup dialog enter your Meta Pixel ID, Meta Conversion API Access Token, and Data Layer Path, then select Next.

Initial setup dialog

Allow a few minutes for the initial setup process to complete, then select Next.

Initial setup complete confirmation screen

From the Add Code on Your Site dialog copy the code provided using the copy function and paste this into the <head> of your source website. Once implemented, select Start Validation

Add code on your site dialog

The Validation Results dialog displays the Meta extension implementation results. Select Next. You can also see additional validation results by selecting the Assurance link.

Test results dialog displaying implementation results

The Next Steps screen display confirms completion of setup. From here you have the option to optimize your implementation by adding new events, which are shown in the next section.

If you do not want to add additional events, select Close.

Next steps dialog

Adding Additional Events

To add new events, select Edit Your Tags Web Property.

Next steps dialog showing edit your tags web property

Select the rule that corresponds to the meta event that you would like to edit. For example, MetaConversion_AddToCart.

NOTE

If there is no event, this rule will not run. This is true for all rules, with the MetaConversion_PageView rule being the exception.

To add an event select Add under the Events heading.

Tag properties page showing no events

Select the Event Type. In this example, we have selected the Click event and configured it to trigger when the .add-to-cart-button is selected. Select Keep Changes.

Event configuration screen showing click event

The new event has been saved. Select Select a working library and select the library that you would like to build to.

Select a working library drop down

Next select the dropdown beside Save to Library and select Save to Library and Build. This will publish the change in the library.

Select save to library and build

Repeat these steps for any other meta conversion event you would like to configure.

Data Layer Configuration

IMPORTANT

The way you update this global data layer depends on your website architecture. A single page application will be different to a server-side rendering app. There is also the possibility that you will be wholly in charge of creating and updating this data inside the Tags product. In all instances the data layer will need to be updated in between running each of the MetaConversion_* rules. If you don’t update the data between rules, you may also run into a case where you are sending stale data from the last MetaConversion_* rule in the current MetaConversion_* rule.

During the configuration, you were asked where your data layer lives. By default, this would be window.dataLayer.meta, and inside the meta object, your data would be expected as shown below.

Data layer meta information

This is important to understand as every MetaConversion_* rule uses this data structure to pass the relevant pieces of data to the Meta Pixel extension and to the Meta Conversions API. Refer to the documentation on standard events for more information on what data different meta events require.

For example, if you wanted to use the MetaConversion_Subscribe rule, you would need to update window.dataLayer.meta.currency, window.dataLayer.meta.predicted_ltv, and window.dataLayer.meta.value as per the object properties described in the documentation on standard events.

Below is an example of what would need to be run on a website to update the data layer before the rule is executed.

Update data layer meta information

By default, the <datalayerpath>.conversionData.eventId will be randomly generated by the “Generate New Event Id” action on any of the MetaConversion_* rules.

For a local reference of how the data layer should look, you can open the custom code editor on the MetaConversion_DataLayer data element on your property.

Next steps

This guide covered how to send server-side event data to Meta using the Meta Conversions API extension. From here, it is recommended to expand your integration by connecting more Pixels and sharing more events when applicable. Doing either of the following can help further improve your ad performance:

Connect any other Pixels that are not yet connected to a Conversions API integration.
If you are sending certain events exclusively through Meta Pixel on the client side, send these same events to the Conversions API from the server side as well.

See the Meta documentation on best practices for the Conversions API for more guidance on how to effectively implement your integration. For more general information on tags and event forwarding in Adobe Experience Cloud, refer to the tags overview.

recommendation-more-help