The Meta Conversions API Program for Online Conversions

For advertisers running campaigns on Facebook, the Meta Conversions API Program for Online Conversions (previously known as Facebook CAPI Adapter) offers an easy way to send conversion event data paired with an envelope. You can implement Meta Conversions API as part of ATS for Web through LiveRamp Console or directly with our API, to bypass the complexity of building a server-side integration with Meta.

While we recommend implementing Meta CAPI in Console for a more streamlined process, you can still send the events to our conversion API adapter by creating a specific HTTP POST request. The adapter will then parse the data and send the data to Facebook.

Requirements

Meta envelope: Contact our team to get Meta envelopes implemented for you. When applied, two envelopes will be returned on a given ATS request. One is a regular ATS identity envelope and the other is a Meta-encoded RampID, scoped for Meta.
Pixel ID: You must have a Pixel ID to use the Conversions API. If you’ve already set up a pixel for your website, we recommend that you use the same Meta pixel ID for your browser and server events.
Access token: To use the conversions API, you need an access token from Meta. There are two ways of getting your access token: via Events Manager (recommended) or using your own app.
Learn more about Meta's requirements and how to fulfil them here.

Set Up Meta CAPI Integration in Console

Before you begin, you must first set up the Meta CAPI integration in Console. Log in to Console and follow the steps to Set up Meta Conversions API Program Integration in Console.

Store the Meta-Scoped Envelopes

Storing Meta-scoped envelopes works the same way as storing regular ATS envelopes. When calling the ATS Envelope API with Facebook scoping applied, the response will look like the following:

{"envelopes":[{"type":19,"source":"envelopeLiveramp","value":"Alkc6LgKZzbqHvexyq4hyzxp0zQZnIztut2rFKjmcDtSBbM0rttk5pH2qb8iNkyxCO9kYAKg6oM2rt28dbWV6-lt9BxwoPCabDaOUXN3fr2C1qsCeV9H0qcW3wBPbbnTpxFWI0Wnh7WVPFYrCM8FgziDEBwSoYnUMO9wheayikvFSGX3Qsz1lr0QWnj2dHEMhx5V2QEbhkJ2iwH2zLEaKAt5oVa8EwAf59mOQepN3S_CwQk4C5OkgfZYiUXTYwxpDA","err":null},{"type":24,"source":"envelopeSource200","value":"BeEQ_c7DOKeu8XVIRImTEPB_qgHapbMhOo_zfVkhtJmD08omJsfnHOmAS_TK90J1k62hpwElJrDIkkVfC7lHgUmauzizRh5qAPRe8IBKAeMW0TW2RRFjxWk","err":null}]}

To store the Meta-scoped envelope:

Take the entire value of envelopeSource200 object:

BeEQ_c7DOKeu8XVIRImTEPB_qgHapbMhOo_zfVkhtJmD08omJsfnHOmAS_TK90J1k62hpwElJrDIkkVfC7lHgUmauzizRh5qAPRe8IBKAeMW0TW2RRFjxWk

Modify the result so it contains the envelope object:

{"envelope":"BeEQ_c7DOKeu8XVIRImTEPB_qgHapbMhOo_zfVkhtJmD08omJsfnHOmAS_TK90J1k62hpwElJrDIkkVfC7lHgUmauzizRh5qAPRe8IBKAeMW0TW2RRFjxWk"}

Encode the entire string to Base64 format:

eyJlbnZlbG9wZSI6IkJlRVFfYzdET0tldThYVklSSW1URVBCX3FnSGFwYk1oT29femZWa2h0Sm1EMDhvbUpzZm5IT21BU19USzkwSjFrNjJocHdFbEpyRElra1ZmQzdsSGdVbWF1eml6Umg1cUFQUmU4SUJLQWVNVzBUVzJSUkZqeFdrIn0=

Take the Base64-encoded value of envelopeSource200 and store it (with a timestamp) in a first-party cookie or local storage called _lr_fb_env.

In a first-party cookie:

function setCookieForRampIDEnvelope(envelopeSource200) {   
   document.cookie = '_lr_fb_env=' + encodeURIComponent(envelopeSource200);
}

In local storage:

function setLocalStorageForRampIDEnvelope(envelopeSource200) {   
   localStorage.setItem('_lr_fb_env' , envelopeSource200);
}

Create the Request

To send the events, make a POST request with the following path:

https://fb-capi.analytics.rlcdn.com/send-events/{ats-configuration-id}

To retrieve your ATS configuration ID, go to Console > ATS > Web. Select a configuration, and select the Admin tab. You can find the Configuration ID in the Configuration Details area.

If you have Pixel installed on the website, two cookies should appear: _fbp and _fbc. These cookies should be passed to the API in the user_data section. If cookies are not enabled, _fbc value can be found in the URL by searching for fbclid URL parameter.

The endpoint doesn’t require an authorization token. To signify the event as a test, enter the test ID from Meta's Test Event tool as a test_event_code.

Be sure to pass the envelope value from the envelopeSource200 object (without base64 encoding) in the partner_id parameter.

Example of body:

{
  "events":[
     {
        "event_name": <event_name>,
        "event_id": <event_id>,
        "event_time": <date_in_timestamp_format> ,
        "event_source_url": <event_source_url>,
        "user_data":{
           "partner_id": <envelope_data>,
           "fbp": <_fbp_cookie_value>,
           "fbc": <_fbc_cookie_value>,
        },
        "custom_data":[
           {
              "key": "currency",
              "value": <value>
           },
           {
              "key": "value",
              "value": <value>
           },
           {
              "key": "content_category",
              "value": <value>
           },
           {
              "key": "custom_properties",
              "value": { "<value>": "<value>", "<value>": "<value>" }
           }
        ],
        "customer_information":[
           {
              "key": "country",
              "value": <value>
           }
        ]
     }
  ],
  "partner_agent": <partner_agent_name>,
  "test_event_code": <value>
}

Example of body with data:

{
  "events":[
     {
        "event_name": "Purchase",
        "event_id": "1234",
        "event_time": 1646733199,
        "event_source_url": "https://demo.console.fktr.io/ats/nrfbcapitest.html?ats_debug=true",
        "user_data":{
           "partner_id": "BeEQ_c7DOKeu8XVIRImTEPB_qgHapbMhOo_zfVkhtJmD08omJsfnHOmAS_TK90J1k62hpwElJrDIkkVfC7lHgUmauzizRh5qAPRe8IBKAeMW0TW2RRFjxWk",
           "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890
",
         },
         "custom_data": [
            {
               "key": "content_category",
               "value": "grocery"
            },
            {
               "key": "currency",
               "value": "USD"
            },
            {
               "key": "value",
               "value": "14"
            },
            {
                "key": "custom_properties",
                "value": { "warehouse_location": "washington", "package_size": "L" }
            }
         ],
         "customer_information": [
            {
               "key": "first_name",
               "value": "Nemanja"
             }
         ]
      }
   ],
   "partner_agent": "liveramp",
   "test_event_code": "yEOEGKVZ0k"  
}

See list of supported keys to see all examples of supported events.

Refresh the Envelope

Existing envelopes can be exchanged for fresh envelopes by calling:

https://api.rlcdn.com/api/identity/v2/envelope/refresh?pid=[placement id]&it=[envelope type]&iv=[envelope value]&ct=[consent type]&cv=[consent string]

You must populate the it parameter with 24 to correspond to the Meta-scoped envelope type. This will reset the envelope expiration to the maximum allowed value.

To learn more about refreshing envelopes, see Implement the ATS Envelope Refresh API.

Best Practices

We recommend you make use of all standard events available and send them to Facebook to get the most out of the Conversion API adapter.

Click here to download a useful guide from Meta and learn more about their best practices.