Universal Events and Parameters for Online Conversions API Program
LiveRamp’s Online Conversion API program utilizes unified schema parameters with a mapping system that translates our parameters to each platform’s specific ones.
This article lists the following:
Available event types and the platforms that support them
Custom data parameters for passing additional data related to the event
Contents parameters for passing SKU-level data
Required parameters for API implementation
For instructions on implementing the Online Conversions API for ATS for Web, see "Implement Online CAPI"
For instructions on implementing the Online Conversions API with ATS API calls, see "Online Conversions API Program for API Implementation".
Note
The tables in this article will continue to expand as LiveRamp works with additional platforms. Stay up-to-date by regularly checking the "Release Notes and System Information" page to be notified when a new platform is supported.
Tip
If an event or parameter is not supported by one of your enabled CAPI platforms, the event data will still be sent to other platforms that do support it.
For example, you've enabled Meta, Pinterest, Snapchat, and TikTok in your CAPI integration. You then create an Add Payment Info event, which is only supported by Meta and TikTok. When the specified event takes place, the conversion data will be sent to Meta and TikTok only.
Caution
The Trade Desk Online Conversions API connectors are currently in limited availability. If you're interested in being considered to participate, contact your LiveRamp representative.
Tips on Using This Article
Learn which information is relevant depending on your implementation method and event source.
For ATS.js implementation (web): Use the following tables to check which platforms each event type supports, and our recommendations on passing additional data.
For API implementation (web and app): In addition to the tables above, refer to the tables below for info on required parameters and additional data you can pass to enrich your event.
Important
Check the Universal Key columns from each table and copy the desired key to use in your payload.
Event Types
The table below lists the conversion events you can send, the platforms that can receive them, and the supported event source.
App-only events can only be passed through API calls, while web events can be passed via ATS.js as well as direct API calls.
Universal Key | Description | Supported Platforms | Web Event Support | App Event Support |
|---|---|---|---|---|
AchieveLevel | A user reaches a certain level that you have defined in your game. |
|
|
|
AchievementUnlocked | A user unlocks a certain achievement that you have defined in your app. |
|
|
|
AdClick | A user clicks an ad. |
|
|
|
AdView | A user views an ad. |
|
|
|
AddBilling | A user configures their payment information. |
|
|
|
AddPaymentInfo | A user adds their payment information at checkout. |
|
|
|
AddToCart | A user adds a product to the shopping cart. |
|
|
|
AddToWishlist | A user adds a product the wishlist. |
|
|
|
AppInstall | A user installs your app. |
|
|
|
AppOpen | A user opens your app. |
|
|
|
ApplicationApproval | An application submitted by a user is approved. |
|
|
|
Checkout | A user is ready to check out an order in your app. |
|
|
|
CompleteRegistration | A user signs up or creates an account by completing a registration form. |
|
|
|
CompleteTutorial | A user completes a tutorial. |
|
|
|
Contact | A user contacts your business via chat, email, telephone, etc, |
|
|
|
ConvertedLead | A user completes a step in the (pre-defined) lead conversion process. |
|
|
|
CreateGroup | A user creates a group or team in your game. |
|
|
|
CreateRole | A user creates a role or character in your game. |
|
|
|
CustomizeProduct | A user customizes a product. |
|
|
|
Donate | A user donates to your organization or a cause. |
|
|
|
Download | A user downloads something from your websites. |
|
|
|
Engagement | A user performs an action that indicates engagement. |
|
|
|
FindLocation | A user searches for a location on your website, such as looking for the location of a physical store. |
|
|
|
GenerateLead | A user leaves contact information, such as a phone number or email, in your app. |
|
|
|
ImportedLead | A user has been qualified as a lead from an external source. |
|
|
|
InAppAdClick | A user clicks on an advertisement displayed in your app. |
|
|
|
InAppAdImpr | A user views an advertisement displayed in your app. |
|
|
|
InitiateCheckout | A user starts the checkout flow to purchase items. |
|
|
|
Invite | A user invites another user. |
|
|
|
JoinGroup | A user joins a group or team in your game. |
|
|
|
Lead | A user completes a form (sign up) to get more information. |
|
|
|
LevelComplete | A user completes a level. |
|
|
|
ListView | A user views a list. |
|
|
|
LoanApplication | A user applies for a loan in your app. |
|
|
|
LoanApproval | A user receives approval for a loan in your app. |
|
|
|
LoanDisbursal | A user successfully receives a loan in your app. |
|
|
|
Login | A user logs into your app. |
|
|
|
Other | A user performs actions that don't fit the definition of the standard conversion types. |
|
|
|
OutboundClick | A user clicks on a link to an external website. |
|
|
|
PageView | When a user visits a product or article page. |
|
|
|
Purchase | A user completes the checkout flow or a purchase. |
|
|
|
QualifiedLead | A user performs an action that qualifies them as a lead. |
|
|
|
Rate | A user rates a product or a service. |
|
|
|
Registration | A user registers in your app. |
|
|
|
RequestQuote | A user requests a quote. |
|
|
|
Reserve | A user makes a reservation. |
|
|
|
Save | A user saves content, product, or offer to revisit later. |
|
|
|
Schedule | A user schedules an appointment to visit your business. |
|
|
|
SearchCategory | A user searches for a category. |
|
|
|
Search | A user searches or uses the search bar. |
|
|
|
Share | A user shares content such as posts, products, or promotions. |
|
|
|
SpentCredits | A user spends credits, such as in-app currency, in your app. |
|
|
|
StartTrial | A user begins a free trial to use a product or service your business offers |
|
|
|
StoreSale | A user makes a purchase at your physical store. |
|
|
|
StoreVisit | A user physically visits your store |
|
|
|
SubmitApplication | A user applies for something that your business offers. |
|
|
|
SubmitForm | A user submits a form or application. |
|
|
|
Subscribe | A user subscribes to content on your website, including paid subscription. |
|
|
|
ViewCategory | A user views a product category page. |
|
|
|
ViewCart | A user views the contents of the shopping cart. |
|
|
|
ViewContent | A user visits a specific page related to your business, such as a product page or landing page. |
|
|
|
WatchVideo | A user watches a video. |
|
|
|
Custom Data
Parameters marked as "Recommended" mean that including them will help create more accurate and higher quality conversion data. Parameters marked as "Optional" mean that including them can provide more context in your conversion data.
We highly suggest including as many recommended parameters as possible when you set up your event in Console or when you are constructing you request payload.
For API implementations, you can pass the following data as part of the custom_data object for both web or app events. For ATS for Web (ATS.js) implementations, you can include the parameters by enabling "Add Custom Data Parameters" in your event's setting.
Universal Key | Description | Recommendation | Supported Platforms |
|---|---|---|---|
content_ids Array of string | The product IDs (or SKUs) associated with the event. | Optional |
|
content_category Array of string | The category of the product. | Optional |
|
content_name Array of string | The name of the product. | Optional |
|
content_type Array of string | Used to indicate what the keys the content IDs represent; individual items or multiple items in group. | Optional |
|
currency Array of string | ISO 4217 code of the currency associated with the value. | Required for Purchase events |
|
Array of string | The user's email address. | Recommended |
|
num_items Array of string | The number of items the user has during checkout. | Optional |
|
order_id Array of string | A string of ID for this specific transaction. | Optional |
|
description Array of string | A string description of the product. | Optional |
|
phone_number Array of string | The user's phone number. | Recommended |
|
predicted_ltv Array of string (stringified float) | The predicted lifetime value of a conversion event. | Optional |
|
search_string Array of string | The text that was used for the search event. | Optional |
|
value Array of string (stringified float) | Total value of items with item_price attribute within the "contents" object (i.e. basket-level value). | Required for Purchase events |
|
content_brand Array of string | The brand associated with the content ID. | Optional |
|
event_tag Array of string | Custom event set label. | Optional |
|
shop_id Array of string | The shop ID. | Optional |
|
first_name Array of string | The user's first name. | Recommended |
|
last_name Array of string | The user's last name. | Recommended |
|
zip_code Array of string | The user's zip code. | Recommended |
|
date_of_birth Array of string | The user's date of birth. | Recommended |
|
gender Array of string | The user's gender. | Recommended |
|
city Array of string | The city associated with the event. | Recommended |
|
country Array of string | The country associated with the event. | Recommended |
|
state Array of string | The state associated with the event. | Recommended |
|
fb_login_id Array of string | The ID issued by Meta when a person first logs into an instance of an app. This is also known as App-Scoped ID. | Optional |
|
lead_id Array of string | The ID associated with a lead. | Optional |
|
subscription_id Array of string | The subscription ID of the user in the event. | Optional |
|
anon_id App events only Array of string | Unique application install ID. | Optional |
|
limited_data_use Array of string | Data processing options to enable for specific events. You can set this parameter to help comply with various US state privacy regulations. | Optional |
|
Content Properties
Include the optional parameters in the following table to provide more context on every individual item in an event.
For API implementations, you can pass the following data as part of the contents object. For ATS for Web implementations, you can include the parameters by enabling "Add Contents" in your event setting.
Universal Key | Description | Supported Platforms |
|---|---|---|
item_id Required if array of string | Unique ID of the individual item. |
|
item_price array of string (stringified float) | Price of the individual item. |
|
item_quantity array of string (stringified integer) | Quantity of the individual item. |
|
item_name array of string | Name of the individual item or page. |
|
item_brand array of string | Brand of the individual item. |
|
item_brand_id array of string | Brand ID of the individual item. |
|
item_category array of string | Product category of an individual item. |
|
item_subcategory array of string | Sub-category of an individual item. |
|
Additional Parameters for API Implementations
Customers calling the CAPI connector API should pass additional event and user-level data in their request payload to ensure events can be accurately matched to ad exposures, and support reliable measurement and optimization.
Do not send conversions that occurred more than 7 days ago.
Do not send conversions with a conversion date in the future.
Note
For ATS.js implementations, the data below would be provided by customers directly in Console or automatically obtained and passed by ATS.js.
Required Event Data
When sending web and app events via API calls, you are required to include all the parameters below in your request payload.
Parameter Name | Universal Key | Description |
|---|---|---|
Event Name string | event_name | The event type key from the list all universal event types. |
Event ID string | event_id | A unique string that identifies the event and can be used for deduplication between events. |
Event Time integer | event_time |
|
Event Source URL string | event_source_url | The browser URL when the event happened. |
Event Source string | event_source | Where the event occurred, value must be set to either |
User Data Keys
When sending web and app events via API calls, we recommend always adding the following identifier data to enrich your events and improve match rates. Especially with upper-funnel events such as Page View, View Content, or Search, which often lack identifiers.
Universal Key | Description | Applicable for Web Events | Applicable for App Events |
|---|---|---|---|
envelope string | Identity envelope value. If pulled from storage, the value must be Base64-decoded before sending. |
|
|
fb_envelope string | Facebook-scoped envelope value. If pulled from storage, the value must be Base64-decoded before sending. |
|
|
gaid string | Advertising identifier for Android devices. |
|
|
idfa string | Advertising identifier for iOS devices. |
|
|
idvf string | Vendor identifier assigned to apps on iOS devices. |
|
|
user_agent string | The user agent from the user's device where the event occurred. CautionIf the user_agent parameter is not present in your API payload, the adapter retrieve user agent from the request header. |
|
|
ip_address string | The IP address of the user's device. CautionIf the ip_address parameter is not present in your API payload, the adapter will automatically retrieve IP address from the request header. |
|
|
Provider Data for Web Events
When sending web events via API calls, we recommend to include the following provider data keys so platforms can directly tie each conversion back to the exact ad click or view that generated it.
Platform | Provider Data | Universal Key | Description |
|---|---|---|---|
Meta | Facebook Click ID | fb_click | The Facebook click ID value stored in the See Meta's article "Managing fbc and fbp Parameters" for more info. |
Facebook View ID | fb_view | The Facebook browser ID value stored in the See Meta's article "Managing fbc and fbp Parameters" for more info. | |
Pinterest Click ID | pin_click | The This parameter is mapped to See Pinterest’s article “Managing Click ID Parameters” for more info. | |
Snapchat | Snapchat Click ID | sc_click | The ID value stored in the landing page URL’s This parameter is mapped to See Snapchat’s article “Managing Click ID and View ID Parameters” for more info. |
Snapchat View ID | sc_view | The 1st party cookie if you are using the Pixel SDK, which can be accessed by looking at the This parameter is mapped to See Snapchat’s article “Managing Click ID and View ID Parameters” for more info. | |
TikTok | TikTok Click ID | tt_click | TikTok Click ID, a data connection parameter appended to a landing page URL whenever a user clicks on an ad on TikTok. The value can be found in the This parameter is mapped to Send TikTok's article "Send TikTok Click ID" for more info. |
TikTok View ID | tt_view | Cookie ID. If you also use Pixel SDK and have enabled cookies, Pixel SDK automatically saves a unique identifier in the This parameter is mapped to See TikTok's article “Send TikTok Cookie” for more info. | |
The Trade Desk | The Trade Desk Impression ID | ttd_view | The Trade Impression ID, appended to the landing page URL at ad bid time. |
Required Parameters for App Events
In addition to the required event data parameters above, customers passing app events must include additional fields about the application and device where the event occurred.
Caution
All fields are required, but only a few require values to be passed.
Use these keys to share app information with the conversions API. All fields are required, but only a few require values to be included.
Universal Key | Description | Value Required? | Supported Platforms |
|---|---|---|---|
advertiser_tracking_enabled boolean | Use this field to specify ATT permission on an iOS 14.5+ device. Set to 0 for disabled or 1 for enabled. |
|
|
application_tracking_enabled boolean | Use this field to specify user's choice regarding tracking on an app level. Use 0 for disabled, 1 for enabled. |
|
|
app_id string | The unique ID assigned for a given application. |
|
|
app_name string | Name of the app. |
|
|
device_type string | Type of the user device. |
|
|
device_brand string | Brand of the user device. |
|
|
language string | Two-character ISO-639-1 language code indicating the user's language. |
|
|
wifi boolean | Whether the event occurred when the user device was connected to wifi. |
|
|
Pass the data below as part of the extinfo object to send device information such as screen width and height.
Universal Key | Description | Value Required? | Supported Platforms |
|---|---|---|---|
extinfo_version string | Device version, value can be a2 for Android and i2 for iOS. |
|
|
app_pack_name string | App package name. Example: com.liveramp.sdk |
|
|
short_version string | App version (short). Example: 1.0 |
|
|
long_version string | App version (long). Example: 1.0 long |
|
|
os_version string | The OS version. Example: 13.4.1 |
|
|
device_model string | Device model name. Example: iPhone13 |
|
|
locale string | The device's region. Example: En_US |
|
|
timezone_abbr string | Timezone abbreviation. Example: PDT |
|
|
carrier string | The device data carrier. Example: AT&T |
|
|
screen_width string | The device's screen width. Example: 320 |
|
|
screen_height string | The device's screen height. Example: 568 |
|
|
screen_density string | The device's screen density. Example: 2 |
|
|
cpu_core string | The CPU core Example: 2 |
|
|
ext_storage_size string | The external storage size in GB. Example: 13 |
|
|
free_space string | The free space on the external storage in GB. Example: 8 |
|
|
device_timezone string | The device's time zone. Example: USA/New York |
|
|
form_factor string | Device form factor. Example: cellphone |
|
|
os_family string | The device's OS family. Example: ios |
|
|
network_type string | The device's network type or capability. Example: 4G, 5G |
|
|