Skip to main content

Implement LiveRamp Online Conversions API Program with ATS for Web

With ATS for Web (ATS.js), you can capture and send web conversion data to subscribed CAPI programs in a single workflow via LiveRamp's Conversions API connector. In this article, you will learn how to integrate your ATS configuration with the CAPI programs and define the events you want to send to your partner platforms.

LiveRamp’s Online Conversions API connector supports sending online web events to the following platforms:

  • Meta

  • Pinterest

  • Snapchat

  • TikTok

Tip

LiveRamp is continuously expanding its partnership with more platforms. Check the "Release Notes and System Information" page periodically to stay updated when a new CAPI program becomes available.

LiveRamp also supports sending offline events through the Offline Conversions API programs. To learn more about the supported platforms and how to implement them, see “Conversions API Programs”.

To send events via direct API calls to the universal CAPI connector, see "The Online Conversions API Connector for API Implementation".

View the Universal Events and Parameters

LiveRamp’s Online Conversion Program utilizes unified schema parameters with a mapping system that translates our parameters to each platform’s specific parameters.

To view the list of supported event types, their parameters, and how they are mapped, see "Universal Events and Parameters".

Requirements

During the integration process, you will be required to provide the following details from the platform you want to send events to:

  • Authentication/Access token

  • Account ID

For the Meta Conversions API, you are required to enable Meta-scoped envelopes in addition to the requirements above. To learn more, see "Platform-Specific Requirements".

Create an Online Conversions API Integration

Once you have obtained the platform-specific requirements, you can create the integration in Console's CAPI Hub.

Procedure. To create an online CAPI integration:

  1. Create a new ATS configuration.

  2. From the navigation pane, select ATS → Web.

  3. Select the Integration tab and click New.

  4. Select "Conversions API".

  5. Select your ATS implementation method.

  6. Enter the required account IDs for the platforms you want to send events to and the corresponding access tokens.

    Unified_CAPI_IDs_andTokens.png

  7. If you are implementing CAPI via ATS API, click Add and then Publish. See "LiveRamp Online Conversions API Program for API Implementation" to learn how to create the request to send events.

Set Up an Event for Online Conversions API

Once you have completed the steps to create a CAPI Integration, you can proceed to configure the events you want to send to your platform partners in the Conversions API Hub. This includes the event type, any additional parameters, and how the data should be collected.

The event data can be collected via CSS selectors, URL, or through data layer detection. LiveRamp's data layer detection is able to collect conversion and event data already stored in any existing website data layers, including those outside of Google or Adoble.

  1. Under "Events List", click Create New.

    Meta_Create_New_Event.png

  2. Enter an Event Name and select the Event Type.

  3. Select how you want the event data to be detected from the Event Detection Method drop-down list. The following options are available:

    • Page Elements: Event data are obtained from visible HTML elements using parameters you manually add and configure in the CAPI Hub in Console. You can configure how a parameter should be obtained using one of the following detection methods:

      • CSS selectors: Allow you to obtain a parameter by targeting a specific HTML element on your page. We recommend using only ID selector to limit errors. For example; #product-value, #ItemValue, #OrderNumber.

      • URL query parameters: You provide a URL parameter which is added at the end of a URL after the ‘?’ symbol. For example; currency or product-currency.

      • Hardcoded values: You enter a value you want to pass for the parameter. For example, if the transactions on your website are always in US dollars, you may want to set the value to "USD" for the Currency parameter.

    • Data Layer: Event data are obtained from the data layer using parameters from an HTML tag. A code snippet will be provided with all possible parameters included by default, which you can then modify to your preference.

      To detect and send events with Data Layer:

      1. Select the preferred implementation tag to run the ATS CAPI integration. You can select one of the following:

        • Via an ATS standalone tag: Implement the CAPI as a standalone tag. This option is the default method if your ATS configuration is not integrated with LaunchPad.

        • Via a LaunchPad tag: Implement the CAPI using a tag that is linked to a LaunchPad configuration. This option will only be displayed if you install your ATS configuration with LaunchPad.

          Data_Layer_V2_Implementation_tag.png

      2. Under "Trigger", select how to initiate the sending of events:

        • Automatically (recommended): Events are automatically sent at the end of each user session. This can be either when the user closes the page or switches tabs.

        • Manually: You trigger the JavaScript function when you know all the information is obtained. This can be done by calling ats.sendConversionApiEvents().

      3. Then, select how to initiate the detection of data layer events:

        • Automatically: Data layer events are automatically detected.

          Note

          If you select "Automatically" as the data layer detection method, you can still trigger the detection manually (i.e. for debugging purposes) by calling the ats.detectDataLayerEvents() function.

        • Manually: You trigger the detection manually by calling ats.detectDataLayerEvents() function when you know the event data have been stored on data layer. Make sure to call the function on every single page where you want ATS.js to detect the event.

      4. Copy the displayed code and modify it to your preference by removing the parameters you want to exclude for this event.

      5. Click Save. You can skip the remaining steps in this procedure.

  4. In the "Custom Data" section, select how the event ID should be obtained and for which identifier. The event ID is used to eliminate duplicate events by assigning a unique identifier to each event. In the example below, we are using the Order Number as the Event ID.

    Unified_CAPI_EventID.png

    Warning

    You cannot set hardcoded values for event ID.

  5. If you are creating a purchase event and set Page Elements as the event detection method, you must provide additional parameters for the currency and value, and choose how to obtain them. Select URL or CSS Selector for each parameter and provide the required data.

    Note

    If you want to pass predefined values, you can also select Hardcoded Value and enter a value you want to pass for the parameter. For example, if the transactions on your website are always in US dollars, you may want to set the value to "USD" for the Currency parameter.

    You cannot set hardcoded values for Event ID.

  6. Select Add Custom Data Parameters to include additional parameters such as first and last name, country, order ID, and others. Click the plus button to add another parameter or select the minus button to remove. To learn more about custom data parameters, see "Custom Data".

    uNIFIED_CAPI_CustomData.png

    Tip

    To fully enrich your event data and support user matching across the funnel, we recommend including the following parameters:

    • First name

    • Last name

    • City

    • State

    • Zip code

    • Country

  7. Select Add Contents to include the following parameters about a particular item:

    • Item ID

    • Item price

    • Item quantity

    • Item name

    • Item brand

    • Item category

  8. Under "Trigger", select how to initiate the sending of events:

    • Automatically (recommended): Events are automatically sent at the end of each user session. This can be either when the user closes the page or switches tabs.

      Note

      You can still call the function ats.sendConversionApiEvents() to send the event manually, even if you set the trigger option to "Automatically".

    • Manually: You trigger the JavaScript function when you know all the information is obtained.

      • To trigger the sending of all events, call the function ats.sendConversionApiEvents().

      • To send a specific event, call the function by specifying the event type. For example, ats.sendConversionApiEvents("Purchase").

      • To send multiple events, call the function by specifying all the event types. For example, ats.sendConversionApiEvents(["Purchase", "Page View"]).

    Note

    For non-purchase events, we recommend setting up a trigger event only on some pages to make sure they are not fired on every page load.

  9. If you selected Page Elements as the event detection method (see step 5), you can specify to have the trigger added to all pages by selecting "Always", or in specific pages by selecting "On Some Pages". If you choose the latter, you must provide the page URL and a domain identifier to specify when the module should start detection to obtain all conversion data from the page. Click the plus button to add multiple pages.

    FB_CAPI_Trigger_URL.png

  10. Click Add.

Once you've set up all the necessary events, publish the ATS configuration to push the changes to live. You can verify if your setup is working correctly by going to your platform partner's events manager. After the specified events occur on your websites, in some cases, you should be able to see them within 20 minutes.

In this section: