Facebook CAPI Adapter

The ATS Facebook CAPI Adapter offers an easy way to send both conversion event data paired with an envelope. You can implement Facebook CAPI Adapter as part of ATS.js through LiveRamp Console or directly with our API, to bypass the complexity of building a server-side integration with Facebook.

While we recommend implementing Facebook CAPI with ATS.js for a more streamlined process, you can still send the events to our Facebook CAPI Adapter by creating a specific HTTP POST request. The adapter will then parse the data and sends the data to Facebook.

Requirements

Facebook Envelope: Contact our team to get Facebook 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 Facebook-encoded RampID, scoped for Facebook.
Meta Pixel ID: You must obtain a Meta 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.
Facebook access Token: To use the Conversions API, you need an access token. There are two ways of getting your access token: via Events Manager (recommended) or using your own app.
Learn more about Facebook's requirements and how to obtain them here.

Set up Facebook CAPI Integration in Console

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

Store the Facebook-Scoped Envelopes

Storing Facebook-scoped envelopes works the same way as storing regular ATS envelopes. When calling the ATS Envelope API with Facebook scoping applied, two envelopes will be returned: One is a regular ATS identity envelope and the other is a Facebook-encoded RampID, scoped for Facebook.

The response can 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 Facebook-scoped envelope:

Take the entire envelopeSource200 value 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:

eyJlbnZlbG9wZSI6WyJCZUVRX2M3RE9LZXU4WFZJUkltVEVQQl9xZ0hhcGJNaE9vX3pmVmtodEptRDA4b21Kc2ZuSE9tQVNfVEs5MEoxazYyaHB3RWxKckRJa2tWZkM3bEhnVW1hdXppelJoNXFBUFJlOElCS0FlTVcwVFcyUlJGanhXayJdfQ==

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

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 call requires an ATS configuration ID. To retrieve this ID, go to Console > ATS > Web. Select a configuration, and select select the Admin tab. You can find the Configuration ID in the Configuration Details area.

The following endpoint doesn’t require an authorization token. To signify the event as a test, enter the test ID from Facebook's Test Event tool as a test_event_code (as illustrated in the example below).

Method: POST

Path:

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

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":{
           "client_user_agent": <client_user_agent>,
           "partner_id": <envelope_data>,
           "partner_name": <partner_name>,
           "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": "first_name",
              "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":{
           "client_user_agent":"Mozilla/5.0 (X11; Linux x86_64) Chrome/98.0.4758.102 Safari/537.36",
           "partner_name": "liveramp",
           "partner_id": "BVOBHAIrEaLRRbGFuikzEyEOEGKVZ0kNPCgRDSoujeTtkmK2OQEGwW7F1KUkQebcPAgAKK58m5A88",
           "fbp": "fb.1.1596403881668.1116446470",
           "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 Facebook-Scoped Envelope

Existing Facebook-scoped 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 Facebook-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 Facebook and learn more about their best practices that can help you with your implementation.