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 | Destination Platforms | Available for Web Events | Available for App Events |
|---|---|---|---|---|
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 | Destination Platforms | Available for Web Events | Available for App Events |
|---|---|---|---|---|
content_ids Array of string Optional | The product IDs (or SKUs) associated with the event. |
|
|
|
content_category Array of string Optional | The category of the product. |
|
|
|
content_name Array of string Optional | The name of the product. |
|
|
|
content_type Array of string Optional | Used to indicate what the keys the content IDs represent; individual items or multiple items in group. |
|
|
|
currency Array of string Required for purchase events | ISO 4217 code of the currency associated with the value. |
|
|
|
Array of string Recommended | The user's email address. |
|
|
|
num_items Array of string Optional | The number of items the user has during checkout. |
|
|
|
order_id Array of string Optional | A string of ID for this specific transaction. |
|
|
|
description Array of string Optional | A string description of the product. |
|
|
|
phone_number Array of string Recommended | The user's phone number. |
|
|
|
predicted_ltv Array of string (stringified float) Optional | The predicted lifetime value of a conversion event. |
|
|
|
search_string Array of string Optional | The text that was used for the search event. |
|
|
|
value Array of string (stringified float) Required for purchase events | Total value of items with item_price attribute within the "contents" object (i.e. basket-level value). |
|
|
|
content_brand Array of string Optional | The brand associated with the content ID. |
|
|
|
event_tag Array of string Optional | Custom event set label. |
|
|
|
shop_id Array of string Optional | The shop ID. |
|
|
|
first_name Array of string Recommended | The user's first name. |
|
|
|
last_name Array of string Recommended | The user's last name. |
|
|
|
zip_code Array of string Recommended | The user's zip code. |
|
|
|
date_of_birth Array of string Recommended | The user's date of birth. |
|
|
|
gender Array of string Recommended | The user's gender. |
|
|
|
city Array of string Recommended | The city associated with the event. |
|
|
|
country Array of string Optional | The country associated with the event. |
|
|
|
state Array of string Optional | The state associated with the event. |
|
|
|
fb_login_id Array of string Optional | The ID issued by Meta when a person first logs into an instance of an app. This is also known as App-Scoped ID. |
|
|
|
lead_id Array of string Optional | The ID associated with a lead. |
|
|
|
subscription_id Array of string Optional | The subscription ID of the user in the event. |
|
|
|
anon_id Array of string Optional | Unique application install ID. |
|
|
|
limited_data_use Array of string Optional | Set this field to specify when data should be processed in compliance with various US state privacy regulations. Value can be set to |
|
|
|
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 | Destination Platforms | Available for Web Events | Available for App Events |
|---|---|---|---|---|
item_id array of string Required if | Unique ID of the individual item. |
|
|
|
item_price array of string (stringified float) Optional | Price of the individual item. |
|
|
|
item_quantity array of string (stringified integer) Optional | Quantity of the individual item. |
|
|
|
item_name array of string Optional | Name of the individual item or page. |
|
|
|
item_brand array of string Optional | Brand of the individual item. |
|
|
|
item_brand_id array of string Optional | Brand ID of the individual item. |
|
|
|
item_category array of string Optional | Product category of an individual item. |
|
|
|
item_subcategory array of string Optional | 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.
Universal Key | Description | Applicable for Web Events | Applicable for App Events |
|---|---|---|---|
event_name string Required | The event type key from the list all universal event types. |
|
|
event_id string Required | A unique string that identifies the event and can be used for deduplication between events. |
|
|
event_time integer Required |
|
|
|
event_source_url string Required | The browser URL when the event happened. |
|
|
event_source string Required | 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 Recommended | Identity envelope value. If pulled from storage, the value must be Base64-decoded before sending. |
|
|
fb_envelope string Recommended | Facebook-scoped envelope value. If pulled from storage, the value must be Base64-decoded before sending. |
|
|
gaid string Recommended | Advertising identifier for Android devices. |
|
|
idfa string Recommended | Advertising identifier for iOS devices. |
|
|
idvf string Recommended | Vendor identifier assigned to apps on iOS devices. |
|
|
user_agent string Recommended | 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 Recommended | 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.
Universal Key | Description | Destination Platforms |
|---|---|---|
fb_click string Recommended | The Facebook click ID value stored in the See Meta's article "Managing fbc and fbp Parameters" for more info. | Meta |
fb_view string Recommended | The Facebook browser ID value stored in the See Meta's article "Managing fbc and fbp Parameters" for more info. | Meta |
pin_click string Recommended | The This parameter is mapped to See Pinterest’s article “Managing Click ID Parameters” for more info. | |
sc_click string Recommended | 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 |
sc_view string Recommended | 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. | Snapchat |
tt_click string Recommended | 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 |
tt_view string Recommended | 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. | TikTok |
ttd_view string Recommended | The Trade Impression ID, appended to the landing page URL at ad bid time. | The Trade Desk |
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.
All fields in the following tables are required, but not all require values to be included. You can pass empty string on fields that don't require values, for example:
{
"extinfo": {
"extinfo_version": "a2",
"app_pack_name": "",
"short_version": "",
"long_version": "1.0 long",
"os_version": "13.4.1"
}
}Every key listed below must be present as an object to share app information with the conversions API. If a specific data point is missing or unavailable, pass an explicit empty string ("") as the value.
Universal Key | Value Required? | Description | Destination Platforms |
|---|---|---|---|
advertiser_tracking_enabled boolean Required | Yes | 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 Required | Yes | Use this field to specify user's choice regarding tracking on an app level. Use 0 for disabled, 1 for enabled. |
|
app_id string Required | Optional | The unique ID assigned for a given application. |
|
app_name string Required | Optional | Name of the app. |
|
device_type string Required | Optional | Type of the user device. |
|
device_brand string Required | Optional | Brand of the user device. |
|
language string Required | Optional | Two-character ISO-639-1 language code indicating the user's language. |
|
wifi boolean Required | Optional | Whether the event occurred when the user device was connected to wifi. |
|
Every key listed below must be present in the extinfo object payload. If a specific data point is missing or unavailable, pass an explicit empty string ("") as the value.
Universal Key | Value Required? | Description | Destination Platforms |
|---|---|---|---|
extinfo_version string Required | Yes | Device version, value can be a2 for Android and i2 for iOS. |
|
app_pack_name string Required | Optional | App package name. Example: com.liveramp.sdk |
|
short_version string Required | Optional | App version (short). Example: 1.0 |
|
long_version string Required | Optional | App version (long). Example: 1.0 long |
|
os_version string Required | Yes | The OS version. Example: 13.4.1 |
|
device_model string Required | Optional | Device model name. Example: iPhone13 |
|
locale string Required | Optional | The device's region. Example: En_US |
|
timezone_abbr string Required | Optional | Timezone abbreviation. Example: PDT |
|
carrier string Required | Optional | The device data carrier. Example: AT&T |
|
screen_width string Required | Optional | The device's screen width. Example: 320 |
|
screen_height string Required | Optional | The device's screen height. Example: 568 |
|
screen_density string Required | Optional | The device's screen density. Example: 2 |
|
cpu_core string Required | Optional | The CPU core Example: 2 |
|
ext_storage_size string Required | Optional | The external storage size in GB. Example: 13 |
|
free_space string Required | Optional | The free space on the external storage in GB. Example: 8 |
|
device_timezone string Required | Optional | The device's time zone. Example: USA/New York |
|
form_factor string Required | Optional | Device form factor. Example: cellphone |
|
os_family string Required | Optional | The device's OS family. Example: ios |
|
network_type string Required | Optional | The device's network type or capability. Example: 4G, 5G |
|