# Amplitude Documentation — Data # Generated: 2026-09-08T23:39:57Z # Pages included: 81 of 81 # Source: https://amplitude.com/docs/llms.txt # Product feed: llms-data.txt > Data planning, sources, destinations, governance, warehouse-native, and CDP workflows. > For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`. ================================================================================ # Data URL: https://amplitude.com/docs/data ================================================================================ # Data Send data into Amplitude, organize and clean it, and activate it across your downstream tools. Connect sources, resolve identities across devices, govern your taxonomy, and stream behavioral data to the rest of your stack. **Outcome:** [Get every event into Amplitude](https://amplitude.com/docs/data/source-catalog) Stream activity from SDKs, servers, warehouses, and pre-built sources so no behavior goes uncounted. **Outcome:** [Activate insights in your stack](https://amplitude.com/docs/data/destination-catalog) Send behavioral data and cohorts to the marketing, ad, and warehouse tools your team already uses. **Outcome:** [See one user, not many](https://amplitude.com/docs/data/profiles) Stitch warehouse profile data to behavioral events so each person is the same user across devices. **Outcome:** [Trust the data your team queries](https://amplitude.com/docs/data/create-tracking-plan) Lock in a tracking plan, review changes, and keep events on-spec as your product evolves. **Outcome:** [Fix data without redeploying](https://amplitude.com/docs/data/transformations) Rename, redact, or reshape events on the way in instead of waiting on an instrumentation fix. **Outcome:** [Add the context analysts need](https://amplitude.com/docs/data/lookup-tables) Join reference data like plans, regions, or accounts to events so every chart has the full picture. ## Plan and collect data Start with an implementation plan that defines the events, users, and properties your team needs. - [Plan your implementation](https://amplitude.com/docs/get-started/plan-your-implementation) to connect product questions to the events you track. - [Create a tracking plan](https://amplitude.com/docs/data/create-tracking-plan) to document event names, properties, and ownership. - [Choose client-side or server-side tracking](https://amplitude.com/docs/data/client-side-vs-server-side) to match your product architecture. - [Use Autocapture](https://amplitude.com/docs/data/autocapture) to collect website interactions before you manually instrument every event. ## Govern and activate data Keep your taxonomy healthy, then send trusted data to the teams and tools that need it. - [Configure schema](https://amplitude.com/docs/data/configure-schema) to monitor event volume, property types, and unexpected changes. - [Transform incoming events](https://amplitude.com/docs/data/transformations) to rename, redact, or reshape data after ingestion. - [Manage data access controls](https://amplitude.com/docs/data/data-access-control) to limit access to sensitive events and properties. - [Forward data to destinations](https://amplitude.com/docs/data/destination-catalog) to activate behavioral data in downstream tools. ### [Get Started with Amplitude Data](https://academy.amplitude.com/getting-started-with-amplitude-data) Learn the fundamentals of Amplitude Data. ================================================================================ # Overview of Amplitude Data URL: https://amplitude.com/docs/data/data-overview ================================================================================ # Overview of Amplitude Data Amplitude Data governs the event taxonomy behind your Amplitude project. It defines events and properties in a shared plan, validates incoming data against that plan, and provides tools to clean, enrich, and monitor data after ingestion. Use it when multiple teams instrument the same product and you need one source of truth for what every event means. ## Planning and instrumentation - Create a plan directly in Amplitude. Define your events, properties, and taxonomy standards directly in Amplitude. This information appears when you select events and properties. Amplitude Analytics monitors this information to make sure your incoming data matches your spec. - Use the Ampli developer toolkit. Ampli uses your plan to generate a type-safe tracking library and lints code to ensure proper tracking of your events and properties. Planning directly in Amplitude Data gives you an up-to-date plan your company can use instead of one-off spreadsheets or wiki pages that can quickly become outdated. Refer to the walkthrough of the [complete planning workflow](https://amplitude.com/docs/data/data-planning-workflow) for the process from start to finish. ## Data management For data Amplitude has ingested: - Improve data discoverability by enriching the metadata on your events and properties. Ensure your company has a shared definition and understanding of all your tracking. - Clean up your data with tools to transform existing events and properties, drop incorrect data from your queries, and block or delete data you no longer want to collect. - Enrich your data by using your existing events and properties to create new custom events, map existing properties to values with lookup properties, and generate new derived properties based on formulas. - Monitor your data with observability, which monitors your incoming data and compares it to your plan in real time. Amplitude also provides Data Assistant, which recommends and automates changes that improve your data quality. ================================================================================ # Getting started with Amplitude URL: https://amplitude.com/docs/data/data-get-started ================================================================================ # Getting started with Amplitude Send data to Amplitude with one of the SDKs or a third-party integration like Segment, mParticle, or Tealium, then instrument events, user properties, and group types so charts reflect real product usage. Set up at least two projects (one for staging, one for production) before you ship instrumentation, because Amplitude can't retroactively rename or change historical event data. Start here if you're standing up a new Amplitude project from scratch. If you already send data and need to model it for analysis, go to the [Data Planning Playbook](https://amplitude.com/docs/data/data-planning-playbook) instead. ## Instrumentation best practices Follow these recommended best practices when instrumenting Amplitude: - **Always test your instrumentation**: Amplitude recommends having a testing project for every production project in your organization. A testing project gives you a reliable way to test your instrumentation before sending production data to Amplitude. - **Amplitude can't retroactively change historical data**: If your instrumentation is wrong, you can't clean up the data you collect later. - **Set up at least two Amplitude projects**: One for your development or staging environment, and one for your production environment. Two projects keep testing data separate from production data. - **Send the right keys**: If you send data server-side with the HTTP API, send a `session_id` and `insert_id` with each event. ## How Amplitude receives data You can send data to Amplitude through SDKs or through a third party: - [SDK Catalog](https://amplitude.com/docs/sdks/analytics). - A third party like [Segment](https://segment.com/), [mParticle](https://www.mparticle.com/), or [Tealium](https://tealium.com/). ## Amplitude APIs Amplitude has many APIs you can use with the platform. Refer to all the [API references](https://amplitude.com/docs/apis). ## Amplitude schema The [Data Planning Playbook](https://amplitude.com/docs/data/data-planning-playbook) explains how the Amplitude schema fits together. Refer to it for a deeper look at taxonomy design. ### Naming conventions for events After you instrument an event, you can never change the name of that event type in the raw data. For example, in v1.0 of your app, a developer instruments the following event type: `Amplitude.getInstance().logEvent('Play song');` Later, in v2.0 of your app, a developer instruments this event type: `Amplitude.getInstance().logEvent('play song');` Strings passed to Amplitude are case-sensitive, so Amplitude interprets these two event types as separate events. Make sure your event names follow a consistent syntax during instrumentation. ### Instrument user properties [User properties](https://amplitude.com/docs/data/user-properties-and-events) are attributes specific to individual users. Examples of user properties include location, language, account type, money spent, or player type. For recommendations on which user properties to track, refer to [the Data Planning Playbook](https://amplitude.com/docs/data/data-planning-playbook#properties). Amplitude SDKs include several user property operations you can use to update user property values: - **`set`**: Set or overwrite the property value. - **`setOnce`**: Set the value only if the value isn't already set. - **`unset`**: Unset the value to `null`. - **`add`**: Increment the numerical value by a specified number. - **`append`**: Append the value to the property array. - **`prepend`**: Prepend the value to the property array. You can also use the [Identify API](https://amplitude.com/docs/apis/analytics/identify) to update the values of a user's user properties without sending another event. The new values apply to the next event the user sends organically. ### Instrument group types To use Amplitude's [account-level reporting](https://amplitude.com/docs/analytics/account-level-reporting) feature, instrument group types. Account-level reporting lets you count by a distinct user property group, which lets you process data at the groups level instead of the individual users level. Amplitude allows a maximum of five group types. If you use a third-party tool to instrument Amplitude (mParticle, Segment, Tealium), this maximum threshold might be lower based on the partner's limitations. ## How Amplitude tracks unique users and sessions Amplitude tracks unique users through a system of user IDs, device IDs, and Amplitude IDs. To learn more, refer to [tracking unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users). In Amplitude, a session is a single continuous period of time a user is active within your product. Amplitude sends a session ID with every event, which lets it track sessions. For more information, refer to [tracking sessions in Amplitude](https://amplitude.com/docs/data/sources/instrument-track-sessions). ## Popular SDK configuration options This section details Amplitude SDK configuration options that users commonly modify. - **`minTimeBetweenSessions` (iOS/Android)**: The minimum time you must background your app before a new session begins. - **`sessionTimeout` (Web)**: The minimum time between events that must elapse before a new session begins. - **`batchEvents`**: Enabled by default for mobile SDKs and optional for Web. - **`eventUploadPeriodMillis`**: If `batchEvents` is enabled, this option sets the time between event batch uploads. - **`eventUploadThreshold`**: If `batchEvents` is enabled, this option sets the minimum number of events per batch. - **`optOut`**: When enabled, opts the current user out of tracking. - **`offline`**: Prevents the sending of events. - **`saveEvents`**: Enabled by default for all SDKs. Lets the SDK save unsent events onto the device. - **`savedMaxCount`**: The maximum number of unsent events saved on a device. The default is 1000. ## Backfilling data Consider backfilling data if: 1. **You want to analyze historic data in Amplitude**. For detailed instructions on backfilling data into Amplitude, refer to the [Data Backfill Guide](https://amplitude.com/docs/data/data-backfill). 2. **Your product already has existing users**. You want to accurately reflect when these [users were new](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-build) in Amplitude. ================================================================================ # Getting set up with Amplitude Data URL: https://amplitude.com/docs/data/amplitude-data-get-started ================================================================================ # Getting set up with Amplitude Data Setting up event tracking means designing a tracking plan, implementing it with typed SDK code, catching instrumentation drift in QA, and retiring events as your product changes. Amplitude Data covers this full data lifecycle: planning, instrumenting, validating, and deprecating the events your product sends to Amplitude. ## Get data into Amplitude Amplitude supports several methods for ingesting data. You can collect data from your app using [SDKs](https://amplitude.com/docs/get-started/get-data-in). ### Choose an ingestion method Consider these factors when deciding which ingestion method works best for your organization. #### Use Amplitude SDKs Amplitude SDKs are a good way to integrate if you're getting started with analytics. You can use Ampli to keep your instrumentation clean from the start while retaining the flexibility to send data to [various destinations](https://amplitude.com/docs/data/destination-catalog) later. When using Amplitude SDKs, decide whether to send events from front-end clients or back-end servers: - **Client-side tracking**: Add client-side SDKs to your web and mobile apps. This method can be more direct because you can use default event tracking and capture both client-side and server-side interactions with your application. However, events that span all your clients require deployment changes across all your apps. On mobile, updates can take time depending on how long it takes your customers to update their apps. - **Server-side tracking**: Send events directly from your servers to Amplitude. For example, when tracking an order completion, send the event from the back-end server that processes the order. This centralized approach is generally the most reliable because a single place in your control sends the events. You also don't have to wait for customers to update their app version. Amplitude recommends server-side tracking for events that require high precision and client-side tracking for everything else. #### Use cloud storage, warehouses, and event streaming If you already have a reliable data source, connecting to that source can be the fastest way to get started with Amplitude. Customers often use these methods to connect with current sources of truth and use Amplitude's self-serve capabilities to expand data access across their company. You can use Amplitude's data management capabilities even when you connect through an existing source. ## What to track Identifying and planning the events and properties you want to track is essential to maximizing your data. A solid tracking plan helps you answer business questions and prevents gaps in your analyses. Use these resources to help decide what to track: - To get started quickly, read about [what events you need](https://amplitude.com/docs/get-started/select-events). That article recommends events and properties commonly tracked in each industry. - Refer to the [data planning playbook](https://amplitude.com/docs/data/data-planning-playbook) for a deeper understanding of creating a taxonomy from scratch. - If you've identified events and properties to track and want to get them into Amplitude, refer to [creating your tracking plan](https://amplitude.com/docs/data/create-tracking-plan). ## Best practices These practices help ensure good results both initially and as you scale with Amplitude Data. ### Establish a naming convention Simple, self-explanatory names that follow a consistent convention make your plan understandable across your organization. Consistent naming also prevents data quality issues. Two events with different capitalizations, such as `Song Played` and `song played`, appear as two separate events. Set your naming convention in [Settings](https://amplitude.com/docs/data/amplitude-data-settings), and Amplitude Data prompts anyone who creates events to follow that convention. ### Use a separate environment for testing Keep your data clean by using separate projects for development and production. Separate projects let you test your implementation without affecting your final business reports. They're also a good place to try data management tools before applying them to production data. Refer to [creating a project in Amplitude](https://amplitude.com/docs/get-started/create-project). ================================================================================ # Autocapture URL: https://amplitude.com/docs/data/autocapture ================================================================================ # Autocapture Autocapture collects a predefined set of user interactions from your website or app with one SDK snippet, no event-by-event instrumentation. On web, it captures sessions, page views, clicks, form interactions, file downloads, marketing attribution, and page URL enrichment through the [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2); on iOS and Android, it captures installs, upgrades, sessions, and screen views through the [iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk) and [Android-Kotlin SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk). Turn it on when you want baseline product analytics quickly, before you scope custom event tracking. Use Autocapture when you want broad baseline coverage immediately with no instrumentation work. Use precision tracking when you need custom events or properties tied to specific business logic, such as purchases or feature-specific actions. The two work together, so most teams run both. On the web, you can also use visual labeling to navigate your site and create new events from the click information. ## Autocapture and precision tracking Amplitude offers two primary ways to capture events: - Autocapture automatically collects a predefined set of events and properties in a standardized taxonomy using Amplitude SDKs. - Precision tracking instruments events and properties specific to your business needs and analyses. From the moment you install the SDK, Amplitude automatically collects data to provide insights into feature usage, funnel conversion rates, and click analysis on the web. The Browser SDK also enriches all events with page URL information, including previous page tracking and page type classification. Autocapture minimizes setup time, so you can move straight to analysis. To investigate specific actions in your application that require additional metadata, or to track events such as a purchase event that may be core to your business, use precision tracking. Precision tracking in code sends these events with a robust set of properties for deeper analysis. For example, imagine you're releasing a new feature and don't have time to implement precision tracking. Autocapture can serve as a safety net for collecting baseline metrics and answering engagement questions. After you have these insights and want to go deeper, work with your team to implement precisely tracked events and get the best of both approaches. ## Optimize your event volume Autocapture provides several configuration options to help you adjust your implementation to your needs. You can turn individual Autocapture events on and off as needed and tune those events further to optimize your event volume. The default configuration provides the right balance of automatically capturing events that matter while excluding ones that don't. This balance is critical when capturing clicks. By default, Amplitude captures clicks on interactive elements (for example, links, text fields, dropdowns, and other form elements). Amplitude also captures clicks on elements that result in a change on the page (for example, a new visual element) or a navigation to a new page. This configuration excludes clicks on blank areas, text highlighting, and similar actions to ensure you don't pay for low-value user behaviors. Amplitude recommends monitoring your event volume (go to _Settings > Plans & Billing_) as you make changes to ensure it matches your expectations. You can change your configuration to capture clicks only on specified elements (or elements with certain classes), track only on specific pages, or turn click tracking off while still using other Autocapture data such as page views and sessions. ## Your taxonomy with Autocapture Keeping your taxonomy clean and organized ensures users can find what they need. When you enable Autocapture, you get a predefined set of event and property types for ingestion. For example, the SDK captures click interactions as two events ("Element Clicked" and "Element Changed") with a predefined set of properties rather than a stream of noisy user interactions. With [visual labeling](https://amplitude.com/docs/data/visual-labeling), users in your organization create events directly from the UI. Consider the following when you plan your taxonomy: - Set up the correct permissions for each user. Users with a Member role or higher can create labeled events. - Align your naming convention with your existing taxonomy for labeled events. - Add descriptions to your labeled events to help other users understand their purpose. Additional details about labeled events: - Labeled events have a separate tab in _Data > Events_ to help you manage them differently from your raw ingested events. This tab displays who created the labeled events and the creation date for each event. - Labeled events have a different icon in the event dropdown so you and your users can distinguish them from other events. ## Privacy and security For many organizations, data privacy, security, and personally identifying information (PII) are critical factors when setting up data collection. Business needs, the purpose of your digital products, and compliance requirements between jurisdictions may vary. There's no one-size-fits-all solution that works in every situation. Autocapture provides flexible configuration options to help you adhere to your company's privacy and security policies and requirements. While ensuring your use of Amplitude complies with your data privacy policies and requirements is your responsibility, these settings help you reach compliance. ### Default Autocapture protections You control what information Autocapture collects and sends to the Amplitude platform. To update the events that Autocapture sends to Amplitude, refer to [Browser SDK | Disable Autocapture](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#disable-autocapture). The following list describes Autocapture's default settings for capturing clicks and changes on page elements ("Element Clicked" and "Element Changed" events). The list also includes the following privacy and security considerations. You don't need to do anything to turn these protections on. They're always active. - For sensitive elements such as end user text inputs, selects, text area elements, and any HTML elements with `contenteditable="true"` as an attribute, the SDK only collects class names and the type attribute. Autocapture excludes any end user-inputted text. - Autocapture's default settings further restrict collection of sensitive input fields, such as passwords or form fields with the hidden attribute, and only capture class and type attribute values. Autocapture doesn't capture other details about these elements, including any content an end user populates in the input fields. - Autocapture captures the text your website or app displays. For example, the content (`textContent`) of the element clicked and its children. Amplitude doesn't recommend using Autocapture's element interaction tracking on pages that may contain sensitive information. Amplitude uses pattern matching to automatically mask any text content that looks like a credit card number, social security number, or email address. - The exception to these attribute collection rules is when an element has an explicit attribute added with the prefix `data-amp-track-`. This exception lets data in these attributes pass back to Amplitude intentionally. - Autocapture automatically removes value, event handlers, style, and react attributes. - Mask page titles in page view events by adding the `data-amp-mask` attribute to the `` element. This replaces the actual title with a masked value to protect sensitive information. For implementation details, refer to [Browser SDK page title masking](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#page-title-masking). ### Manual Autocapture protections Amplitude offers the following Autocapture protections if you choose to implement them. By default, Amplitude doesn't enable them. You can enable all or some of the protections listed below. For some of these protections, you must add an attribute to your elements. You enable some of these protections through the _Data Settings > Autocapture_ page. The documentation for each protection indicates how to enable it. #### Precise text masking Precise text masking redacts text capture from specific elements on the page. This attribute tracks clicks while redacting the text displayed in those elements. To mask an element's text, add the attribute `data-amp-mask` to it. For example, if you have the following on a button: ```html <div data-amp-mask>John Doe</div> ``` Autocapture still tracks the click on the div element. However, the text content "John Doe" appears as `*****` in the Autocapture data. This exclusion works at the SDK level. Precise text masking works recursively, so Autocapture masks any text contained in an element. For example: ```html <div data-amp-mask> John Doe <div>Jane Doe</div> </div> ``` In this example, Autocapture masks both names with `*****`. #### Precise attribute masking Precise attribute masking redacts specific HTML attributes from capture. When you define which attributes to mask, Autocapture tracks clicks while redacting those attributes in your HTML. Specifying attributes on an element masks that attribute on all child elements as well. For example, if you include the following attribute: ```html <div data-amp-mask-attributes="name"> <span name="John D">Account</span> </div> ``` on a button or link, Autocapture masks the name "John D" with `*****`. You can also use a list to specify more than one attribute to mask. When using a list, format the masking attributes as `data-amp-mask-attributes="name,ssn"`. > **Note:** > > You can't mask information from ID and Class attributes because of their importance for [visual labeling](https://amplitude.com/docs/data/visual-labeling). #### Pattern (RegEx) masking You can mask information based on patterns you specify (regular expressions or RegEx). If you aren't familiar with RegEx, review this page on [regular expressions](https://www.regular-expressions.info/quickstart.html). Specify a pattern of information for Autocapture to mask. This configuration occurs in the [SDK](https://amplitude.com/docs/sdks) and provides an additional layer of protection to the default patterns Amplitude uses to mask email, credit cards, and social security numbers. RegEx filters mask values in any fields where this data may appear, including both visible fields and hidden attributes on the page. For example, you can set a RegEx pattern to filter out credit card numbers such as `****-**** **** 1234`. In this example, you want to fully mask the credit card information, including the final four digits. Add the RegEx filter `/(?i)ends\s*in\s*[0-9]{4}/`. If Amplitude finds credit card information that matches the pattern, Autocapture masks those numbers as `*****`. Enable this through the _Data Settings > Autocapture > Element Interactions_ page. #### Page URL exclude and allow lists Use page URL exclude and allow lists to specify unique URL patterns to exclude from or include in Autocapture. Use these capabilities if your organization requires stronger restrictions or safeguards, or if your website or app may contain pages with highly sensitive data such as those in financial services, healthcare, and medical technologies. For example, you can exclude user activity from specific sub-domains on your URL, such as your user's account settings or URLs that only include testing data. If you host your site on multiple domains such as `.com` and `.co.uk`, specify that you only want to include data from the `.co.uk` domain. **Examples** Using the example of `.com` and `.co.uk` above, here are examples of the exclude and allow lists: **Exclude list** - Add `https://example.co.uk/account/*` as a glob pattern to the exclude list. This pattern captures everything on the `.co.uk` domain except for the account section. **Allow list** - Add `https://example.co.uk/*` as a glob pattern to the allow list. Amplitude only captures data from the `.co.uk` domain. Amplitude doesn't capture data from the `.com` domain. > **Note:** > > The exclude list always takes priority over the allow list. This priority prevents you from capturing data that you don't want. If you include the same pattern in both the exclude and allow lists, Autocapture excludes that pattern. Enable this through the _Data Settings > Autocapture > Element Interactions_ page. #### Limit click tracking To support visual labeling, Autocapture captures interaction information about the elements clicked or changed and information about the element's parents in the HTML structure. Depending on your site's structure, you can: - Refine the elements allowed for click and change tracking. Configure the `cssSelectorAllowlist` and `actionClickAllowlist` options to change the list of elements that Autocapture can track. You can remove all common HTML elements and restrict to elements with a specific class. Enable this through the _Data Settings > Autocapture > Element Interactions_ page. #### Turn off Autocapture events You can turn off Autocapture entirely and use precision tracking for data collection. Amplitude includes robust data management tools and workflows that support planning and implementing a custom taxonomy. [Turn off any or all Autocapture events](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#disable-autocapture) through your SDK configuration. ================================================================================ # Plan your taxonomy URL: https://amplitude.com/docs/data/data-planning-playbook ================================================================================ # Plan your taxonomy A taxonomy defines which events and properties you track, what you name them, and how they fit together. A solid taxonomy keeps analyses consistent, prevents data gaps, and avoids costly schema rework later. Build one in three steps: define your business objectives, break down key metrics, then optimize the resulting events and properties. Use this playbook when you're designing a tracking plan by hand or auditing an existing one. ## What is a taxonomy A taxonomy is a set of hierarchical classifications and naming conventions for your data. A taxonomy identifies and categorizes your event and user data so that Amplitude can generate relevant and valuable insights. The process of setting up a taxonomy in Amplitude differs from organization to organization, but the core steps are selecting the events you want to track, identifying event properties and user properties to track, and naming them. ## Users, events, and properties Amplitude's analyses use a combination of events and properties attached to your users. ### Users A user represents a unique individual taking an action or engaging in an activity related to your application. Amplitude uses multiple methods to identify and reconcile your users across various devices. To learn how Amplitude tracks unique users, including how to reconcile anonymous users before login, refer to [tracking unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users). ### Events An event is a distinct action or activity a user takes within your product. Events can be active when a user interacts with your app (for example, starting a game or adding to their cart), or inactive (the user receives a push notification). When naming events, Amplitude recommends establishing a consistent naming convention that uses: - **Consistent capitalization**: Amplitude captures `Song Played` and `song played` as two separate events. This naming convention helps prevent messy data, especially when multiple teams send the same event. - **A consistent syntax**: `Song Played` and `Played Song` are also separate events. For example, a standard of `[Noun]` + `[Past-Tense Verb]` ensures all your events stay consistent. - **A consistent actor**: Does `Message Sent` mean that the user sent a message, or that you sent a message to the user? If all your events use the user's perspective, the meaning is clear immediately. Default events use Title Case from the user's perspective, with `[Noun]` + `[Past Tense Verb]`. You can also establish your own convention as long as you stay consistent. ### Properties Properties are attributes that help define details around your events and users: - **Event properties** are attributes that describe details specific to a particular instance of an event. For example, if you have a `Purchase Completed` event, you can specify what the user purchased, the total value of the order, and the payment method used. - **User properties** are traits that describe the user and apply across all the user's future events until you change them. Amplitude's SDK captures several user properties by default, and you can also set up your own properties to track. Learn more about the differences between [events and user properties](https://amplitude.com/docs/data/user-properties-and-events). As with events, establish a naming convention with consistent casing. ## Step 1: Define your business objectives Starting with your goals and metrics helps ensure you've prioritized the most important ones for your implementation. For example: - What are you and your team working toward? - What metric are you trying to optimize? - What questions do you want to answer with data? Some typical goals Amplitude customers pursue include: - Improving acquisition ROI. - Finding the "aha" moment in the product. - Optimizing conversion. - Increasing user retention and LTV. After you identify your organization's overarching goals, it's easier to break them down into individual metrics and ensure your tracking plan measures the outcome you want. For example, suppose you have an e-commerce app and want to increase purchases. You can do this by: - Increasing the conversion rate of users through your purchase flow. - Increasing the number of users who make multiple purchases. - Increasing the number of users coming to your app. Each of these can be an input metric to achieve your goal. Prioritize these input metrics so you can answer the most important question first. Consider an iterative approach, where you plan and instrument your most important metrics, then iterate later to add more. ## Step 2: Break down your key metrics After you know your ultimate goal and have hypotheses about how to accomplish that goal, break down those input metrics further. What critical paths do your users take, and how do they involve each of those metrics? What actions are essential to each of those paths? Suppose you start with increasing the conversion rate of users through your purchase flow. What are users' critical interactions with your application through the purchase flow? They could be: - **Search completed**: The user searched for an item to purchase. - **Product details viewed**: The user viewed the details of an item. - **Product added**: The user added an item to their order to purchase. - **Order reviewed**: The user viewed the items in their order before purchase. - **Order completed**: The user made a purchase and completed their order. For each of these, think about the various factors involved in each step. For example: - When using search, what term did the user search for? - When the user viewed an item, what was the `Product ID` for the item purchased? One helpful technique is to think about the objects involved with each action and include attributes of those actions in each event. For example, an item in your system likely has an ID, a category, and a price, all properties you can add to events related to your items. ## Step 3: Optimize your events and properties It's time for final optimizations on your plan. Ask yourself these questions. ### Do you have multiple events for similar actions Suppose you have two user actions you can capture as two separate events, or as a single event with a property distinguishing the two distinct cases. For example, suppose you believe payment method is a critical factor. Should you instrument: - `Order Completed` as a single event with a `Payment Method` property that captures `Credit Card` or `Apple Pay`, or - Separate events for `Credit Card Order Completed` and `Apple Pay Order Completed`? Consider these factors: - Start with your key metrics. In this case, while the purchase method is important, the key metric is the purchase flow conversion. A single `Order Completed` event is easier to include in a funnel to view the overall purchase flow conversion. - Is the event scalable? In this example, what happens when you introduce PayPal as a new payment method? Any chart measuring overall conversion would need an update. You'd also be using three events for an interaction where one is enough. - Do you want to identify these separately in [Journeys](https://amplitude.com/docs/analytics/charts/journeys/journeys-understand-paths)? If so, a single `Order Completed` event is probably fine. If you made all your events `Page Clicked` instead, a series of these generic events is unlikely to help when looking at a user flow. ### Are your property definitions consistent across your events Even though event properties are specific to each event, define them consistently across your taxonomy. For example, instead of having a property called `Type` that could represent the type of an item in one event and a type of payment in another, consider separate properties: `Item Type` and `Payment Type`. ### Are your properties captured across all applicable events One typical use case for event properties is tracking values that must hold constant to count toward funnel conversion. For example, suppose you want to know how often users add to cart after viewing details: - Step 1: `Product Details Viewed` - Step 2: `Product Added` Here, users should count as having converted through the funnel only if they triggered the event on the same product. To ensure this, instrument the event property `Product ID` and require the funnel to hold this value constant. Every event in the funnel must have that property for the holding constant feature to work. - Step 1: `Product Details Viewed` - `Product ID` = `3345` - Step 2: `Product Added` - `Product ID` = `3345` - `quantity` = `1` In this example, you can understand how often a user adds to their cart after viewing an item. Without the `Product ID`, you'd be analyzing how often a user adds any item to their cart after viewing any item. ## Next steps Refer to the steps in this playbook as you add new features or iterate on your product analytics. Amplitude Data provides ways to create and iterate on your plan directly in the product, or by importing a CSV file. For more specific examples, go to the following industry-specific best practices guides for sample use cases, business questions, taxonomy recommendations, and complementary dashboards. Each guide addresses the specific needs of these sectors: - [E-commerce](https://analytics.amplitude.com/share/8f32b20708e743e597b75c99b7a766d5). - [Fintech](https://analytics.amplitude.com/share/cbb3827995aa4d03852a3cdf9a3c46b0). - [Publications](https://analytics.amplitude.com/share/5940753342e04394bd0379cdd952cc18). - [Streaming Media](https://analytics.amplitude.com/share/6f40a915c14144b8ac992a5a8d7cf7cb). - [B2B](https://analytics.amplitude.com/share/0f7a78fadfc145d0b99e365eb41d9262). - [Healthcare](https://app.amplitude.com/analytics/share/6e938acce69d459bbb81561b2f942079). ================================================================================ # Destination event streaming overview URL: https://amplitude.com/docs/data/destination-event-streaming-overview ================================================================================ # Destination event streaming overview Event streaming sends your Amplitude event data in real time to downstream marketing, sales, and infrastructure tools, with filtering to control what each destination receives and monitoring to track delivery. Use this behavioral data to enhance customer profiles in those tools. With event streaming, you get configuration-based tools that offer precise control over the data you send. Filter data by user, group, and event properties to send only relevant information to your downstream tools. You can also monitor key metrics like event volume, latency, and detailed delivery status to assess the performance and reliability of your streaming integration. ## Warehouse and batch event streaming Amplitude streams events from both real-time and warehouse or batch sources to your configured destinations. Events imported from your data warehouse or batch sources (such as warehouse imports, Cargo syncs, or file-based ingestion) are eligible for outbound event streaming. After Amplitude ingests these events, Amplitude streams them to your configured destinations alongside real-time events. For your destination, you can expect: - **Complete event coverage**: Your downstream systems receive events from all sources, not just real-time ingestion. - **No additional configuration**: Warehouse and batch events stream to your existing destinations automatically. - **Same delivery guarantees**: Warehouse and batch events follow the same retry and latency targets as real-time events. ## Debug event streaming with Live Log Live Log gives you a real-time, sampled view of events as Amplitude processes them for an Event Streaming sync. Use it to confirm the right events flow through a sync, inspect how Amplitude transforms payloads, and review destination responses. To open Live Log, follow these steps: 1. Navigate to _Data > Destinations_. 2. Select an Event Streaming sync. 3. Select the **Live Log** tab. For each event, Live Log shows three stages side by side: - **Input**: The raw Amplitude event. - **Dispatched**: The transformed payload Amplitude sends to the destination. - **Response**: The status code and body the destination returns. Use the stream controls to pause or resume the feed, clear loaded events, and filter by status (**All**, **Success**, **Destination errors**, or **Processing errors**). Search across loaded events, or filter the stream to events where a specific field in the **Input**, **Dispatched**, or **Response** stage matches a value. Live Log provides a sampled, real-time view for debugging. Amplitude doesn't store Live Log data, so you can't use it for historical analysis. For retry and delivery status monitoring, use the **Debugger** tab on the same sync. ## Automatic destination disabling Amplitude automatically disables an Event Streaming destination when its delivery rate drops to 5% or below over three consecutive UTC calendar days. A disabled destination stops sending events until you re-enable it. Amplitude computes the delivery rate as `eventsDelivered / (eventsDelivered + eventsNotDelivered)`: - **Delivered**: Events that succeed on the first attempt or after a retry. - **Not delivered**: Events that expire or that Amplitude discards, including events with a missing `gclid`, incompatible events, and other non-retryable failures. A delivery rate strictly above 5% keeps the destination enabled. A rate at or below 5% triggers the auto-disable. ### Check schedule Amplitude runs the auto-disable check once per day between 19:00 and 20:00 UTC. Each check scores the previous 3 full UTC calendar days separately. To trigger a disable, all three days must have streaming traffic and all three must show a delivery rate at or below 5%. If any of the three lookback days has zero streamed events, Amplitude skips the auto-disable for that check. ### Scope Auto-disable applies to all Event Streaming destinations on the broadcast and connector pipeline, including Google Ads, webhooks, and Braze. It doesn't apply to cohort syncs, which have a separate auto-disable mechanism. ### Notification When Amplitude disables a destination, it emails the users associated with the sync's created-by and last-updated-by fields. The subject line is `[Amplitude] Event Streaming Pipeline named '{name}' was disabled due to the repeated issues` and the email includes a View Destinations button. Amplitude doesn't show an in-app banner. ### Recovery You can re-enable the destination from the UI at any time. There's no cooldown and no required configuration change before re-enabling. Keep in mind: - If you re-enable during the 19:00–20:00 UTC check window and the previous 3 UTC calendar days still show a delivery rate at or below 5%, the auto-disable job can disable the destination again immediately. - If you re-enable after 20:00 UTC, the destination stays enabled until the next day's 19:00 UTC check. - Fixing your destination configuration today doesn't change yesterday's delivery rate. The destination can keep disabling until three consecutive UTC calendar days show a rate above 5%. ## Considerations - **Billing efficiency:** Amplitude tracks event volume based on distinct events sent. If you send the same event to multiple event streaming destinations, Amplitude counts it only once for billing. - **What counts toward Event Streaming Usage:** Only near real-time streaming destinations count toward your Event Streaming Usage. This includes destinations such as Amazon Kinesis Data Stream and Amazon Kinesis Firehose, even though Amplitude groups them under the **Warehouse Destination** section in the UI. Scheduled batch export destinations such as Amazon S3, Google Cloud Storage, Google BigQuery, Snowflake, and Amazon Redshift export data on a recurring schedule, so they don't count toward Event Streaming Usage. - **Identify events count toward limits:** When you enable the **Send Users** option in your event streaming destination, Amplitude triggers an `Identify` event each time a selected user property changes. Amplitude sends these `Identify` events to your event streaming destinations, and they count toward your event streaming volume limit. Monitor your `Identify` event volume to avoid exceeding your contracted limits, especially if you have frequently updated user properties. - **Latency target:** Amplitude aims for an end-to-end p95 latency of 60 seconds, monitored and supported by alerts. - **Retry mechanism:** Amplitude addresses intermittent errors using in-memory retries with exponential backoff for initial sends. The retry pipeline attempts up to 10 times within a 4-hour window. This mechanism applies to all event streaming destinations. - **Monitoring and management:** Use the **Live Log** tab on an Event Streaming sync to inspect events in real time as Amplitude processes them. The **Debugger** tab lets you monitor pending retries, progress, and expired payloads. Analyze failed payload samples to gain insight into error categories. ## Limitations - **Format for user properties:** Amplitude sends all forwarded user properties as strings except for [Braze streaming](https://amplitude.com/docs/data/destination-catalog/braze) and [Iterable streaming](https://amplitude.com/docs/data/destination-catalog/iterable) destinations. - **Reserved keywords:** You can't use specific keywords, including `_all` and `_identify`, as event names when streaming events from Amplitude. - **Historical data:** Amplitude streams events ingested after you configure a destination. Amplitude doesn't retroactively send events ingested before you set up the streaming destination. Warehouse and batch events ingested after configuration stream alongside real-time events. - **Unsupported Amplitude properties:** Ingestion and streaming pipelines handle some Amplitude properties differently. If so, streaming might not support them. Properties handled differently are `Version` and `Device Family`. ## FAQs ### What's the difference between cohort syncing and event streaming? - **Cohort syncing:** Cohort syncing automatically maintains lists of user IDs based on specific criteria or behaviors. This feature transfers a list of user IDs from Amplitude to third-party tools like SFMC or Braze. Cohort syncing lets you explore behavioral targeting and analyze the impact of your targeting strategies in downstream destinations. Cohort syncing simplifies the management and updating of these lists, supporting actions based on user behavior without manual effort. - **Event streaming:** Event streaming offers more than cohort syncing. Event streaming simplifies your data setup by letting you use a single Amplitude configuration to send data to various platforms, removing the need for constant technical adjustments. With event streaming, you have precise control, choosing which events, users, or properties to send to each platform so only important data reaches its destination. Event streaming also supports real-time conversion events, triggering actions in tools like Braze, Customer.io, or SFMC to optimize your targeting and improve the effectiveness of your initiatives. ### What are some examples of how customers use event streaming? 1. **Marco Polo:** Used event streaming to power a real-time 'Welcome' email campaign by streaming sign-up events from Amplitude to Braze. 2. **Invoice Simple:** Used event streaming for a robust engagement campaign, customizing messaging based on a series of events to improve engagement effectiveness. ### What happens if I don't see an event streaming destination on Amplitude Catalog? 1. **Webhook streaming:** You can use [Webhook Event streaming](https://amplitude.com/docs/data/destination-catalog/webhooks) integration to send your Amplitude events and user data to custom webhooks. This integration sends data to a URL of your choice for various use cases. 2. **Vendor switch:** Consider switching to a vendor already integrated with Amplitude, which offers similar functionalities. Find more information in the [Amplitude Catalog](https://amplitude.com/integrations). 3. **Self-build or vendor request:** You can build the integration yourself using the Amplitude Integration Portal, or request the vendor to create it through the integration portal. Learn more about the [Amplitude Integration Portal](https://amplitude.com/docs/partners/create-an-event-streaming-integration/). ### What's the IP range of your service? Amplitude data centers use the following IP addresses, depending on their region: - Amplitude US IP addresses - 52.33.3.219 - 35.162.216.242 - 52.27.10.221 - Amplitude EU IP addresses - 3.124.22.25 - 18.157.59.125 - 18.192.47.195 ================================================================================ # Syncs URL: https://amplitude.com/docs/data/destinations/syncs ================================================================================ # Syncs Amplitude supports three types of syncs for cohorts, properties, computations, and predictions: **on-demand syncs**, **automated syncs**, and **real-time syncs**. On-demand syncs are useful for audience testing and one-off campaigns. Automated syncs run on a daily or hourly schedule. As cohort audience membership or user predicted probabilities change, Amplitude automatically adjusts cohort membership in connected destinations. Real-time syncs update each minute and work best for interactive use cases that require rapid updates. You don't need CSV downloads or manual syncs. When users take an action in your app, Amplitude automatically syncs them to the relevant ad, email, or testing platform. ## Feature availability - Users on Free, Plus, Growth, and Enterprise plans can use **on-demand syncs**. - Users on Growth, Enterprise, and Plus plans can use **automated syncs**. - Users on Growth and Enterprise plans can use **real-time syncs**. ## Real-time syncs With real-time syncs, Amplitude sends updates to a partner destination almost as soon as a user enters or exits a cohort. This unlocks additional uses for cohort sync, such as timely and contextual messaging to end users. When you create a real-time sync, Amplitude first sends the initial population to the destination. This can take several hours if the sync is large. After this initial sync, Amplitude sends updates every minute as users enter and exit the cohort. Most destinations and cohorts support real-time cohort syncs. When partners fail or reject API requests, or when network delays and errors occur, Amplitude sends any changes once the issue clears. Real-time sync doesn't support select destinations that aren't designed for frequent updates, such as ad destinations and S3, or destinations with strict integration limits that prevent frequent syncing. Real-time sync doesn't support some complex or very large cohorts because of high computation cost. Real-time sync can send cohort membership to destinations, but not computations, properties, or predictions. ## Create a new sync To create a new sync, follow these steps: 1. Click _+ New_ and click the _Sync_ tile. The _Create New Sync_ modal appears. 2. Select the sync type to create: cohort, recommendation, user property, or computation sync. Then click _Next_. 3. From the drop-down list, select the specific item you want to sync. Then click _Next_. 4. Choose the destination to sync to. If the destination doesn't appear, click _+ Add_ or _Manage Destinations_ and configure the destination there. Then click _Next_. 5. Choose whether to create an on-demand sync, recurring sync, or real-time sync. Recurring syncs run on an hourly or daily schedule, while real-time syncs update each minute. Depending on your choice in step 4, you may also need to specify a customer account or API target to sync to. 6. Click _Sync_. Your sync is active. ## Email notifications Amplitude automatically sends email alerts for cohort sync jobs: - **Success notifications**: Receive confirmation when your cohort sync completes successfully. - **Failure notifications**: Receive an alert when a sync job fails, so you can address issues quickly. These notifications help you monitor cohort sync status without manually checking the platform. ## View sync details After you create a sync, click the sync name in the _Syncs_ panel to view its details. The _Details_ tab provides basic information about the sync. The example above is a cohort sync, so the _Details_ tab provides a definition of the cohort, as well as a chart detailing its population over time. The _Syncs_ tab shows each destination that receives this sync. On the _Comparisons_ tab, you can view a head-to-head comparison between this synced cohort and another cohort of your choosing. You can break down the results of the User Composition chart by user property using the _Composition by_ drop-down. To view a list of your synced cohorts from within Amplitude Analytics, click _Cohorts_ and open the _Synced Cohorts_ tab. ## Understanding cohort sync discrepancies When syncing cohorts from Amplitude to a third-party destination, you may notice differences between the user numbers in Amplitude and on the partner's platform. Understanding why these differences occur and how to check which users transferred successfully can help you fix these issues. Amplitude lets you choose any user properties to sync. This aids in customization, but it also requires careful planning to minimize discrepancies during a cohort sync. Common reasons for differences in cohort syncs include: - **Unresolved mapping**: If a user property isn't set, or is `NULL`, Amplitude can't sync the user attached to the property. For example, if you're syncing a cohort of 100 users to a platform using email as the `User_ID`, but only 50 users provided an email, only those 50 users sync. Check and fix your data at the source, update it in Amplitude, and then run another sync. - **Invalid mapped properties**: Properties that don't conform to the expected format in third-party destinations can cause partial or failed syncs. For example, the downstream destination may not accept a particular identifier format, such as email or phone number. > **Note:** > > If a sync is partially successful, Amplitude still marks the entire cohort sync as successful, regardless of whether individual users are valid. ## Warning when updating cohort mapping Amplitude issues a warning if you attempt to modify the Amplitude user property mapping, because modifying the mapping can affect active cohort syncs. Click _View Syncs_ to view the syncs that the change could affect. From there, decide if you want to turn off the sync. Even if you **don't** receive a warning, be careful when modifying mapping properties. Mapping changes can cause unexpected changes in the number of users tracked. For example, if you stop mapping by email addresses and switch to phone numbers, users previously synced with their emails don't receive updates. Your change **only affects new users**. Amplitude syncs new users based on phone numbers, while previously existing users still sync based on email addresses. Over time, this can lead to data discrepancies. If your cohort sync process has been in place for some time and you're considering changing the mapping, create a new sync destination first. Then proceed with the sync using this new target. ## View sync history The cohort sync history page provides a detailed breakdown of cohort syncs over the last 14 days. Each cohort sync provides a list of skipped, added, or removed users. To access the page, follow these steps: 1. Click the _Cohorts_ tab. 2. Choose the specific cohort of interest. 3. Click the _Syncs_ tab. 4. If the cohort sync includes multiple destinations, select the appropriate cohort destination. 5. Click the _History_ tab. > **Note:** > > The detailed cohort sync history page supports all cohort sync destinations except for [Amazon S3](https://amplitude.com/docs/data/destination-catalog/amazon-s3) and [TradeDesk](https://amplitude.com/docs/data/destination-catalog/thetradedesk). These destinations continuously perform a full sync of users, not just an initial sync followed by incremental changes. This sync behavior makes CSV exports impractical. ## Inspect exported cohorts using CSV export To find out which users and how many users Amplitude exported from your cohort to your third-party destination, export a CSV containing all exported users. The CSV export includes the following columns: - **Amplitude\_id**: Displays the unique Amplitude ID associated with each user. - **Operation**: Indicates whether Amplitude added or removed a user from cohort membership. - **Mapped properties**: This column shows the mapped user identifier for the cohort sync. - **Skip\_detected**: Shows if Amplitude skipped a user during the cohort sync process. - **Skip\_reason**: High-level categorization of why Amplitude skipped a user. - **Unresolved mapping**: Amplitude skipped this user during the cohort sync because the mapped property used to identify the user is missing or has no value. - **Rejected by partner**: The third-party destination rejected this user because the mapped property doesn't adhere to the required format. For example, if data fields aren't in the correct numeric or email format, the destination excludes the user from the cohort sync. Some user properties may be incomplete or out of compliance with the target platform's criteria. A cohort sync success rate over 80% is often acceptable for advertising campaigns. For email campaigns or A/B testing, use a rate above 95%. If there are many skipped entries, there may be a data quality issue at the source. To resolve this issue, review the CSV file to pinpoint discrepancies. Then make appropriate corrections to the user data when you're importing it into Amplitude. After you make corrections, launch the cohort sync process again to confirm the accuracy and consistency of your data. ## Additional considerations - **Real-time cohort sync**: With Amplitude's Real-Time Sync (RTS) feature, the cohort sync history page doesn't allow you to export a CSV for users skipped during the sync. For detailed tracking of skipped users, use hourly or daily syncs instead of real-time syncs. - **Users are silently dropped upon reaching destination**: Some destinations may return a 2XX response to indicate a successful cohort sync from Amplitude, even though the destination silently dropped users who didn't meet its criteria. In these cases, confirm that Amplitude exported a specific user by checking the CSV file. > **Note:** > > Amplitude uses response codes to detect when third-party destinations don't include users. In some cases, Amplitude can't identify these users. If you have questions, post in the [Amplitude community](https://community.amplitude.com/) or contact the [Support team](https://help.amplitude.com/hc/en-us/requests/new) for assistance. ## Supported destinations Refer to the [Destination Catalog](https://amplitude.com/docs/data/destination-catalog). ================================================================================ # Troubleshooting URL: https://amplitude.com/docs/data/troubleshooting ================================================================================ # Troubleshooting When your Amplitude data looks incorrect or incomplete, start here. Pages in this section cover common diagnostic questions about ingestion, instrumentation, and source integrations. ### [Missing or unexpected data](https://amplitude.com/docs/data/troubleshooting/missing-data) Missing events, inflated user counts, and discrepancies with other platforms. ### [Instrumentation and governance](https://amplitude.com/docs/data/troubleshooting/instrumentation-issues) Hiding, blocking, and deleting events; filtering internal users; historical data changes; UI quirks. ### [Integrations and sources](https://amplitude.com/docs/data/troubleshooting/integrations-and-sources) Segment, iOS 14, mobile attribution, and third-party site builders. ## More in this section - [Missing or unexpected data](https://amplitude.com/docs/data/troubleshooting/missing-data). - [Instrumentation and governance](https://amplitude.com/docs/data/troubleshooting/instrumentation-issues). - [Integrations and sources](https://amplitude.com/docs/data/troubleshooting/integrations-and-sources). ================================================================================ # Autocapture Remote Configuration URL: https://amplitude.com/docs/data/autocapture-remote-configuration ================================================================================ # Autocapture Remote Configuration Remote configuration updates your [Autocapture](https://amplitude.com/docs/data/autocapture) settings from the Amplitude UI without a code change or SDK redeploy. It toggles which event types Autocapture tracks, adjusts allowlists and exclude lists for element interactions, and adds extra event properties such as page referrer or page URL across all events. Use Remote Configuration when you want non-engineers to adjust Autocapture without shipping code. If you need the settings hardcoded in the client or want to gate them behind a deploy, configure Autocapture directly in your Browser SDK initialization options instead. > **Note:** > > Autocapture Remote Configuration works with [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) v2.10.0+ when you enable `fetchRemoteConfig`. Browser SDK v2.16.1 enables Remote Configuration by default. ## Set up remote configuration for Autocapture 1. Go to _Data > Settings > Autocapture_. 2. Specify which elements you want to capture. By default, Amplitude captures all elements. You can capture or not capture any of the following elements: - **File downloads**: Track when a user clicks an anchor or `<a>` tag linked to a file. - **Form Interactions**: Track a user's interaction with the form element. - **Sessions**: Track the period of time that a user has your website open. Amplitude tracks both Start Session and End Session events. - **Page Views**: Track when a user navigates to a page. - **Element Interactions**: Track when users click links, buttons, inputs, and so forth. 3. For Element Interactions, specify the following additional aspects: - **CSS Selector Allowlist**: CSS selectors that specify which elements on the page Amplitude always tracks. - **Action Click Allowlist**: Additional CSS selectors to track when clicked. - **Page URL Allowlist**: Defines one or more URLs or URL patterns on which Amplitude tracks element click and change events. - **Page URL Exclude List**: Defines one or more URLs or URL patterns to exclude from element click and change tracking. **Note**: Using RegEx or glob patterns requires your SDK version to be 2.23.7 or higher. - **Text Masking RegEx Patterns**: Defines the RegEx patterns to mask for event properties in Autocapture. **Note**: Using this masking feature requires your SDK version to be 2.23.7 or higher. - **Data Attribute Prefix**: Lets Amplitude capture data attributes as event properties. - **Frustration interactions**: Rage clicks or dead clicks that a user performs. Rage clicks are clicks that occur four or more times in a second. Dead clicks are clicks on an interactive element that result in no visible change within three seconds. 4. Click **Save Changes**. ================================================================================ # Visual Labeling URL: https://amplitude.com/docs/data/visual-labeling ================================================================================ # Visual Labeling Visual Labeling creates tracked events from elements you click directly on your site, so non-technical Amplitude users can define events without writing code or understanding the structure of the page. It requires [Autocapture](https://amplitude.com/docs/data/autocapture) on your site. Amplitude maintains labeled events separately from events you've created in other ways. If there are issues with data for labeled events, make adjustments from within the Labeled Events tab, instead of involving your engineering team. ## Prerequisites - [Amplitude Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) 2.10.0 or higher. - The SDK's `config.autocapture.elementInteractions` option set to `true`. For more information, go to the [Browser SDK Configuration](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#configure-the-sdk). > **Note:** > > Visual Labeling is available to Amplitude users with the role **Member** and above. > **Tip:** Retroactive analysis > > Events you create with visual labeling work retroactively against all Autocapture data. Amplitude applies your labeled event definitions to historical click and form interaction data captured since your instrumentation went live. You can analyze user behavior from the past without waiting for new data to accumulate. ## Create a labeled event with visual labeling To use Visual Labeling to create new labeled events, follow these steps: 1. Open Amplitude Data and click **Visual Labeling**. 2. Click the drop-down menu to select the URL you want or add a new URL. 3. Click **Start Labeling**. Amplitude opens your website or app in a new tab, with the visual labeling toolbar at the top of the page. 4. Click an element you want to label. The visual labeling overlay appears. 5. In the visual labeling overlay, enter a name, description, and category for your labeled event. Select if tracking should happen when a user clicks the element, or when it changes. Visual labeling uses the `clicked` event by default. Refine the definition and select filters as needed. 6. Click **Save**. If Amplitude detects an existing event with the same or a similar definition, a warning appears before the event saves. Refer to [Avoid event duplication](#avoid-event-duplication) for details. Amplitude saves the labeled event and displays a confirmation with an option to view the labeled event. 7. Repeat for each event you want to label. 8. You can select another element to continue labeling or click "Back to Amplitude" if you're done. 9. (_Optional_) Click **Navigate** to go to a different part of the site to label more elements on different pages. When you finish, return to Amplitude where you can manually update the tag, text, selector, and page URL of each labeled event. > **Note:** > > If you leave any fields blank, Amplitude interprets that as `[any value]`. For example, if you leave the URL field blank, the tracking for that event fires on any page. ### AI-generated CSS selector Amplitude uses AI to recommend precise CSS selectors for elements on your web page during the visual labeling process. When you click an element to label it, Amplitude automatically suggests a selector that may best capture the intended target. AI-generated CSS selectors appear on individual elements (such as a button) and on groups of elements (such as a list or product tiles). The AI pre-fills the **Name** and **Description** fields using contextual understanding of the selected element. You can modify the AI-generated input for these fields at any time. ### Avoid event duplication When you save a labeled event, Amplitude checks for two types of overlap with existing events and surfaces a warning before you finalize the event: - **Same definition**: Another labeled event already captures the exact same page element and interaction. Amplitude surfaces the `This labeled event already exists` warning. Click **View** to open the existing event and decide whether to use it instead of creating a new one. - **Similar page elements**: Another labeled event matches similar page elements, even if the definitions aren't identical. Amplitude surfaces the `Event has a similar definition` warning. Click **View** to compare your new event to the existing events. Amplitude highlights the elements on screen that define each event so you can tell them apart. Reviewing these warnings before saving helps you avoid duplicate coverage across your tracking plan and keeps your event taxonomy clean. If an existing event covers the same interaction, use it rather than creating a new one. > **Note:** > > Visual Labeling prevents saving events with duplicate names or identical definitions. You must resolve a `This labeled event already exists` warning before you can save. ## Edit a labeled event When your site's code changes, you need to update the definition of your labeled events to match. Because Autocapture consistently captures the raw click events, you can update the definition of your labeled events and fix any gaps in your data. To edit your labeled events, follow these steps: 1. Open Amplitude Data and click **Events**, then select the **Labeled Events** tab. 2. Select the labeled event you want to edit. In the flyout tab, click **Edit**. 3. If your event is no longer collecting data because of a site change, add another condition at the bottom by clicking **Select action...**. 4. Add a new condition based on your new site structure. ### Repair a labeled event Sometimes, changes to your site's DOM break Visual Labeling's reference to the specific element on your site. You also need to repair a labeled event when an element moves to a different location or its structure changes. Visual Labeling's repair flow preserves your event history by adding a new `OR` statement with a secondary definition, rather than replacing the original definition. All historical data remains intact while the event begins tracking the new element as well. To repair a labeled event: 1. Open Amplitude Data and click **Events** in the left rail, then in the main section, click the **Labeled Events** tab. 2. Select a labeled event. In the flyout tab, you can interact with: - A chart that depicts the number of times Amplitude saw the event over the last 30 days. - Charts for each definition you've added to the labeled event. 3. To repair an event that doesn't have event volume, click **Repair**. This opens the Visual Labeling flow with the context of the selected event. 4. Select a new element on the page to update the labeled event's definition. The repair process adds this as an additional OR condition to your existing definition, keeping all historical data. 5. Click **Save** to exit the Visual Labeler and apply the updated definition. ### Find misconfigured events Amplitude provides information to indicate if a labeled event isn't working as it should. Go to _Data > Events_, and open the Labeled Events tab. The **Recency** column shows the last time Amplitude tracked each event. Events that weren't seen recently may show an issue with the event definition. ## Labeled events and event volume When you enable Autocapture, Amplitude begins tracking click and page change events on your site. These events count toward your total event volume. Labeled events act like a virtual layer on top of these events, and help define a specific type of click and use that click in an analysis. Labeled events don't impact event volume beyond Autocapture. For example, a well-instrumented site may record 10,000 events each day, and Autocapture may add as many as 2,000 events each day. The site could experience a 20% increase in daily events. A less-instrumented site may only record 1,000 instrumented events each day. The plugin adding another 2,000 events counts as a 200% increase. In both cases, the increase in daily events comes from tracking click and page change events. Labeled events don't impact the event count. ## Limitations - **Event streams**: Labeled events aren't available in live events, or in the event stream in user lookup and Session Replay. The raw `Element clicked` and `Element changed` events are visible instead. - **Google Chrome extension**: The Amplitude Event Explorer Chrome extension only displays raw events from the browser, so labeled events don't appear. - **Destination event streaming**: You can't send labeled events to destinations with [event streaming](https://amplitude.com/docs/data/destination-event-streaming-overview). You can use your labeled events to define cohorts and then use cohort syncing to integrate with [other destinations](https://amplitude.com/docs/data/destination-catalog). - **Content Security Policy (CSP)**: Amplitude requires cross-tab communication between your site and Amplitude. Visual Labeling requires `cross-origin-opener-policy` to be `unsafe-none` or unset. ## Troubleshooting **I don't see the visual labeling experience on my site** If the visual labeling tools don't appear on your site, check the following: - If you have pop-up or adblocking tools enabled, they can interfere with the Visual Labeling experience. Disable the adblocker and retry. - If the URL you entered redirects to another URL, the visual labeling experience may not load. For security reasons, the domain of the page you're labeling must match the domain you entered in Amplitude. Try using the final URL after any redirects complete. - Ensure `Cross-Origin-Opener-Policy` is set to `unsafe-none` or unset. ================================================================================ # Debug with the Amplitude Chrome extension URL: https://amplitude.com/docs/data/chrome-extension-debug ================================================================================ # Debug with the Amplitude Chrome extension The Amplitude Event Explorer Chrome extension captures every Amplitude event your browser JS SDK fires and displays each event's payload in a popup as you interact with your product. It also surfaces Guides and Surveys trigger state and Web Experiment exposure so you can debug why a guide, survey, or experiment doesn't behave as expected. Install it from the [Chrome Web Store](https://chrome.google.com/webstore/detail/amplitude-instrumentation/acehfjhnmhbmgkedjmjlobpgdicnhkbp). Use the extension when you need to inspect events at the moment they fire in the browser, with their raw event and user properties. To review events after they arrive in Amplitude and search across users and sessions, use [User Look-up](https://amplitude.com/docs/analytics/user-data-lookup) instead. > **Note:** > > The Event Explorer displays the `event_type`, even when it has a different display name. ## View triggered events In the Event Explorer, the **Events** tab contains detailed insights into the parameters of each event you trigger on your website. These parameters include `user_id`, `device_id`, `event_properties`, and `user_properties`. To switch between the different Amplitude projects receiving your events, select the project from the **Project** dropdown. An abbreviated API key distinguishes each Amplitude project. To clear all the events from your popup, select **Clear Events**. To hide specific event types, select the **Invisible** icon. To copy your events' event and user property parameters, select the **Copy** icons. ## View configuration options To view the [configuration options](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#configure-the-sdk) you've set for each project's SDK, select the **API Options** tab. ## View hidden events To see a list of your hidden events or to display events on the webpage as they trigger, select the **Settings** tab. ## Guides & Surveys The extension includes tools to help you debug Guides & Surveys. Use these features to verify SDK setup, troubleshoot why guides or surveys don't show, and test event-based triggers. > **Tip:** > > The **Guides & Surveys** tab doesn't update live. Wait for the page to finish loading before you review its information. ### SDK setup Verify the Guides & Surveys SDK runs correctly on the page before troubleshooting specific guides or surveys. The SDK setup section shows the status of four steps: - **Installed**: You've installed the SDK on the page. - **Initialized**: You've initialized the SDK with your configuration. - **Analytics Connected**: The SDK connects to at least one analytics SDK. - **Booted**: The SDK received user info and is ready to display guides and surveys based on triggers. If all checks pass but guides or surveys still don't work, verify these settings: - **Configuration**: Use **Show config** to verify the API key matches the project where you published your guide or survey. - **User identification**: Use **Show user info** to verify the `user_id` matches the expected user. - **SDK installation**: You might have installed the Guides & Surveys SDK on some pages but not others. Verify you've installed it on all pages where you plan to set up a guide or survey. - **Boot step**: The boot step might be conditional on certain environments or user types. Make sure your code always calls it regardless of environment or user type. ### Troubleshoot Guides & Surveys The troubleshooting section shows all published guides and surveys for the associated project's API key. Each guide or survey displays its trigger conditions and whether those conditions pass. Open a preview of any guide or survey to see the Preview toolbar and debug individual steps. The preview helps you test the guide's behavior and identify issues with specific steps. The expanded section also shows why a guide or survey may not show without opening a preview. Check the trigger conditions to see which requirements aren't met: - **Should show if triggered**: Whether the guide would show if all trigger conditions passed. - **Trigger conditions**: Built-in throttles, custom throttles, limits, page targeting, snooze settings, and user targeting. ### Forwarded events View all events that the Guides & Surveys SDK sees client-side. The SDK only sees client-side events and doesn't have access to server-side events. Use the Forwarded Events section to: - View events the SDK has received. - Simulate test events to trigger guides that depend on specific events. To test an event-based trigger, enter the event name in the input field and select **Test Event**. The event appears in the logged events list with its timestamp and full event payload. ## Web Experiments The extension shows granular targeting details for active [Web Experiments](https://amplitude.com/docs/web-experiment) so you can diagnose why an experiment isn't firing. When an experiment runs on the page, the extension displays a **Debugging Details** panel with an overall exposure badge that shows **Exposed** or **Not Exposed** at a glance. > **Note:** > > Update to the latest version of the extension to see Web Experiment debugging details. ### Audience targeting The **Audience Targeting** section shows which segment matched and which variant the experiment assigns to the current user. Use it to confirm the user falls into the segment you expect. ### Page targeting The **Page Targeting** section shows the configured page view rule, whether the current URL matches that rule, and the trigger status. Check this section first when an experiment doesn't fire, since URL mismatches and trigger misconfiguration cause most issues. ### Preview a variant To QA a specific variant without changing the experiment configuration, use **Preview Variant** to override the variant the experiment assigns to the current user. The override applies only to your session, so it doesn't affect other users or the live experiment. ================================================================================ # Self-service data migrations URL: https://amplitude.com/docs/data/self-service-data-migrations ================================================================================ # Self-service data migrations The Migrations panel moves event data between Amplitude projects and organizations you control, or imports event data from Mixpanel or Posthog. Find it under _Data > Migrations_. All plan tiers can use it, including in the EU data center. Use data migrations to consolidate event data across projects, reorganize your Amplitude structure, or bring historical event data from another analytics platform. To remove unwanted data already in Amplitude, use [self-service data deletion](https://amplitude.com/docs/admin/account-management/self-service-data-deletion-in-amplitude) instead. ## Supported sources The Migrations panel supports three migration sources: - **Amplitude**: Move event data between projects or organizations you control. - **Mixpanel**: Import historical event data from a Mixpanel project into Amplitude. - **Posthog**: Import historical event data from a Posthog project into Amplitude. ## Run a data migration To run a data migration: 1. In Amplitude, navigate to _Data > Migrations_. 2. Click **New Migration**. 3. Select the migration source: Amplitude, Mixpanel, or Posthog. 4. Provide the credentials or authentication required for the source. 5. Configure the migration scope, including the time range and the events you want to import. 6. Review the migration summary and click **Start Migration**. Amplitude runs the migration in the background. Return to _Data > Migrations_ to track the status. Migrated events count toward your monthly event volume. ================================================================================ # Data backfill URL: https://amplitude.com/docs/data/data-backfill ================================================================================ # Data backfill A data backfill loads historical events into your project so past user activity appears alongside your current data. You can import historical data to Amplitude using the [Batch Event Upload API](https://amplitude.com/docs/apis/analytics/batch-event-upload). ## Considerations Review these considerations before backfilling data. - Consider keeping historical data in a separate Amplitude project instead of backfilling into a live production project. Keeping historical data separate makes the upload easier and keeps your live Amplitude data clean and focused on current and future data. You typically don't need to check historical data often, but you still want it available. Historical user property values overwrite current live values during a backfill. Amplitude syncs the out-of-date property values onto new live events. To skip user property sync, add the following to your event payload: `"$skip_user_properties_sync": true`. - To connect historical data with current data, combine the historical data and live data in the same project. To connect users from each dataset, the users need matching Amplitude user IDs in each set. - The new user count might change. Amplitude defines a new user based on the _earliest_ event timestamp it sees for a given user. If Amplitude records a user as new on June 1 2021 and you backfill data for the user from February 1 2021, then Amplitude defines the user as new on February 1 2021. - Backfilling can compromise your app data. If a mismatch exists between the current user ID and the backfilled user ID, Amplitude interprets the two distinct User IDs as two distinct users. As a result, Amplitude double-counts users. Because Amplitude can't delete data after it's recorded, you might have to create a new project to prevent data issues. - Amplitude uses the Device ID and User ID fields to compute the Amplitude ID. For more information, refer to [Track unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users). - Events in the backfill count toward your monthly event volume. ## Limits Keep these limits in mind when backfilling data. - **Daily limit**: An ingestion daily limit of 500K events per device ID (and per user ID) applies to each project to protect Amplitude from event spam. This limit uses a 24-hour rolling window of 1-hour intervals. A user or device can send at most 500K events in the last 24 hours at any given time. If you hit this limit, you get `exceeded_daily_quota_users` or `exceeded_daily_quota_devices` in the response. For more information, refer to [Batch Event Upload](https://amplitude.com/docs/apis/analytics/batch-event-upload#daily-limit). - **Batch limit**: An upload limit applies of 100 batches per second and 1000 events per second. You can batch events into an upload, but Amplitude recommends sending no more than 10 events per batch. Amplitude throttles your upload if you send more than 10 events per second for a single device ID. For more information about throttling, refer to [Batch Event Upload](https://amplitude.com/docs/apis/analytics/batch-event-upload#code-429-explained). To avoid overloading your ingestion workers, Amplitude recommends limiting backfill event upload to 300 events per second per device ID. Backfills can exceed 300 events per second if you iterate through historical data and send data as fast as possible in parallel. ## Backfill best practices - Review the documentation for the [Batch API](https://amplitude.com/docs/apis/analytics/batch-event-upload). If you exported historical data using the Export API and want to use the data to backfill, note that the exported fields aren't in the same format as the fields needed for import. For example, the Export API uses `$insert_id`, while HTTP and Batch APIs use the format `insert_id` without the `$`. - Decide which fields to send and map your historical data to Amplitude fields. Amplitude strongly recommends that you use the `insert_id` field to deduplicate events. - Because no way exists to undo an import, create a test project in Amplitude to send sample data from your backfill. Run several tests with a few days' worth of data in an Amplitude test project before the final upload to the production project. Amplitude recommends this approach for backfilling large amounts of data: 1. Break up the set of events into mini non-overlapping sets (for example, partition by `device_id`). 2. Have one worker per set of events run these steps: 1. Read many events from your system. 2. Partition those events into requests based on `device_id` or `user_id`. 3. Send your requests concurrently or in parallel to Amplitude. To optimize further, add aggressive retry logic with high timeouts. Continue to retry until you receive a 200 response. If you send an `insert_id`, Amplitude deduplicates data that has the same `insert_id` sent within 7 days of each other. ### Skip user properties sync When Amplitude captures an event, it includes the current values for each user property, which can change over time. When Amplitude receives an event with user properties, it updates the existing user properties and adds any new user properties. To change this behavior, add `"$skip_user_properties_sync": true` to the event payload. When you include `"$skip_user_properties_sync": true`, Amplitude ignores the user properties table completely. The event has only the user properties sent with the event, doesn't update the user properties table, and doesn't display any preexisting user properties. > **Example:** > > For example, you send the following event to Amplitude. The user property table already has the user property `"city": "New York"`. > > ```json > { > "api_key": "API_KEY", > "events": [ > { > "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002", > "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636", > "device_id": "", > "event_type": "Button Clicked", > "user_properties":{ > "subscriptionStatus":"active" > } > } > ] > } > ``` > > The event appears in Amplitude as: > > ```json > "events": [ > { > "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002", > "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636", > "device_id": "", > "event_type": "Button Clicked", > "user_properties":{ > "city":"New York", > "subscriptionStatus":"active" > } > } > ] > ``` > > You include `"$skip_user_properties_sync": true` and send the same event. The event appears in Amplitude like this: > > ```json > "events": [ > { > "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002", > "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636", > "device_id": "", > "event_type": "Button Clicked", > "$skip_user_properties_sync": true, > "user_properties":{ > "subscriptionStatus":"active" > } > } > ] > ``` > > The event doesn't include the city property. > > Next, you include `"$skip_user_properties_sync": true` and send this event: > > ```json > { > "api_key": "API_KEY", > "events": [ > { > "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002", > "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636", > "device_id": "", > "event_type": "Button Clicked", > "$skip_user_properties_sync": true, > "user_properties":{ > "city":"San Francisco" > } > } > ] > } > ``` > > Amplitude doesn't update the user properties table, and the event appears in Amplitude like this: > > ```json > "events": [ > { > "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002", > "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636", > "device_id": "", > "event_type": "Button Clicked", > "user_properties":{ > "city":"San Francisco" > } > } > ] > ``` > > Any new event still has `"city":"New York"`, but this event displays `"city":"San Francisco"`. ### Timing If you send data with a timestamp 30 days or older, it can take up to 48 hours to appear in some parts of Amplitude. Use the [User Activity tab](https://amplitude.com/docs/analytics/user-data-lookup) to check the events you're sending, because that tab updates in real time regardless of the event time. ### Resources - Example scripts for data import: [https://gist.github.com/djih/2a7e7fb2c1d45c8277f7aef64b682ed6](https://gist.github.com/djih/2a7e7fb2c1d45c8277f7aef64b682ed6) - Example data: [https://d24n15hnbwhuhn.cloudfront.net/sample\_data.zip](https://d24n15hnbwhuhn.cloudfront.net/sample_data.zip) ## Data ingestion system In Amplitude's ingestion system, each user's current user properties are tracked and synced to a user's incoming events. ![Diagram of user properties synced to each incoming event in ingestion](https://amplitude.com/docs/images/data/data-user-property-sunc.svg) When sending data to Amplitude, you either send event data or send `identify` calls to update a user's user properties. These `identify` calls update a user's current user property values and affect the user properties attached to events received after the `identify` call. > **Example:** > > The Datamonster user has one user property, 'color', set to 'red'. Datamonster logs a 'View Page A' event and triggers an `identify` that sets 'color' to 'blue'. Afterward, Datamonster logs a 'View Page B' event: > > 1. `logEvent` -> 'View Page A' > 2. `identify` -> 'color':'blue' > 3. `logEvent` -> 'View Page B' > > If Amplitude receives events from Datamonster in that exact order, you'd expect 'View Page A' to have 'color' = 'red' and 'View Page B' to have 'color' = 'blue'. Amplitude maintains the value of user properties at the time of the event. For this reason, the order in which events are uploaded matters. If the `identify` arrives after 'View Page B', then 'View Page B' has 'color' = 'red' instead of 'blue'. Because Amplitude processes all of a user's events using the same ingestion worker, Amplitude guarantees that it processes events in the order it receives them. All Datamonster's events queue in order on a single ingestion worker. If two separate workers processed these events in parallel, ordering would be harder to guarantee. For example, one worker might run faster than another. Because a single ingestion worker processes a user's events, a user sending an abnormally high number of events in a short period can overload that worker. To avoid overloading your ingestion workers, Amplitude recommends limiting event upload to 300 events per second per device ID. Backfills can exceed 300 events per second if you iterate through historical data and send data as fast as possible in parallel. Amplitude tracks each device ID's event rate and rejects events with a 429 throttling HTTP response code if a device ID sends too many events. If you receive a 429 in response to an event upload, the process should sleep for a few seconds and then keep retrying the upload until it succeeds. This approach ensures that events aren't lost in the backfill process. If you don't retry after a 429 response code, Amplitude doesn't ingest that batch of events. ## Backfill preexisting users If you have preexisting users, backfill them to accurately mark when they became new users. Amplitude marks users new based on the timestamp of their earliest event. To backfill your preexisting users, use the [Batch API](https://amplitude.com/docs/apis/analytics/batch-event-upload). Send a placeholder event or a signup event where the event timestamp is the actual time the user was originally created. For example, if a user signed up on Aug 1st, 2022, the timestamp of the event you send should be Aug 1st, 2022. ================================================================================ # Privacy and consent implementation guide URL: https://amplitude.com/docs/data/privacy-and-consent-implementation ================================================================================ # Privacy and consent implementation guide You can set up Amplitude in a privacy-friendly way. The right setup depends on your policy, your region, and how much data you want to collect before consent. Before you choose a method, align with your legal and privacy teams on what's allowed in your case. A good way to think about this: first choose your consent model, then configure storage and access in Amplitude to match it. ## Using this guide This guide helps you implement a privacy-conscious analytics setup in Amplitude. It doesn't replace legal advice. Your team decides which consent model, disclosures, and regional requirements apply to your business. This guide shows you practical ways to implement those choices in Amplitude. There's no single setup that fits every company. Some organizations need strict opt-in before analytics starts. Others may use a more limited measurement-only approach in some regions. The right choice depends on your product, your data, and the rules that apply where you operate. Use this guide as a decision and implementation framework: 1. Choose the consent method that fits your policy. 2. Configure Amplitude to match that method. 3. Add the governance, retention, and deletion controls you need. 4. Validate the setup before launch. The guide covers common implementation patterns and the controls most teams need first. For complex use cases, use it as a starting point and identify the decisions to make with your legal, privacy, and security teams. ## Before you start Before you configure anything, answer these three questions: 1. Do you need consent before analytics starts? 2. Do you want to collect no data, or limited anonymous measurement, before consent? 3. Which fields should reach Amplitude at all? You're responsible for obtaining any required consent, making the right disclosures, and deciding how to classify Amplitude cookies in your policy. A practical starting point is to write down: - which events you want to collect. - which identifiers you want to store. - which properties are sensitive. - what should happen when a user declines consent. - what should happen when a user grants consent after an initial decline. That one-page decision document makes the implementation much easier to review and test. > **Note:** How to classify Amplitude cookies in your CMP > > Most organizations classify Amplitude's analytics cookies as analytics or performance cookies, not marketing cookies. If your consent banner separates cookie categories, configure Amplitude under the analytics or performance category in your consent management platform. > > In limited circumstances, such as when Amplitude is used only for feature flagging or for Session Replay in a security or debugging context, the relevant cookies may qualify as "necessary." Your legal team should confirm the correct classification for your specific use case. ## Choose the setup that fits your policy ### Method 1: Ask for consent and collect data only from users who consent This is the clearest option if your policy requires consent before analytics begins. It's also the easiest model to explain to users and auditors because nothing starts until the user grants consent. #### How it works In Browser SDK 2, the SDK may create Amplitude cookies as soon as it initializes. If you need to avoid cookies before consent, don't initialize the SDK until the user has consented. #### How to set it up in Amplitude Only call `amplitude.init()` after consent is captured. Let your site load normally, and hold off on initializing until your consent tool confirms that analytics is allowed. ```javascript import * as amplitude from '@amplitude/analytics-browser'; // User hasn't consented yet. // Don't initialize the SDK here. function onConsentGranted() { amplitude.init('API_KEY'); } ``` If you need to anonymize a user after logout, call `amplitude.reset()`. This clears the `userId` and creates a new `deviceId`. The next activity appears as a new anonymous user until the user signs in again. #### What to do outside Amplitude Use your CMP to control whether initialization happens. Amplitude doesn't provide a default CMP integration, so your CMP needs to pass the consent outcome into your Amplitude implementation. #### Centralize SDK initialization Make `amplitude.init(...)` run from one place only. If several teams initialize the SDK in different parts of the site, proving that tracking is gated by consent becomes much harder. When you test this setup, open your browser developer tools and confirm that no Amplitude cookies are present before consent. ### Method 2: Ask for consent, but collect limited anonymous measurement from users who don't consent Some organizations want a middle ground: full analytics for users who consent, and very limited measurement for users who don't. This can be appropriate only when your legal team confirms that this kind of limited audience measurement is allowed in your jurisdictions. #### How it works Keep this method limited to anonymous or strongly minimized audience measurement, such as total traffic or page views. Don't let it turn into user-level behavioral analysis. Rules can vary across Europe, so treat local regulatory guidance as part of the implementation decision. France is one well-known example: the [Cookies and consent management guide](https://amplitude.com/docs/sdks/analytics/browser/cookies-and-consent-management) describes the CNIL exemption as a narrow case for anonymous statistical audience measurement without consent, not full analytics. It's a useful reference point, but don't treat it as the default rule for every European market. > **Warning:** CNIL self-certification requirement > > Qualifying for the CNIL exemption requires completing a formal self-certification process with CNIL. If you're pursuing this route, work with your legal team to confirm your setup meets the certification criteria before relying on this exemption. #### How to set it up in Amplitude For the limited anonymous flow, reduce or remove persistent identity: - Set `identityStorage` to `none` if you don't want persistent browser identity. - Set `identityStorage` to `session` if you want to track users within a single session but not across sessions. This is a useful middle ground for some implementations. - Avoid sending a stable `userId`. - Keep the event set small and focused on aggregate traffic measurement. ```javascript amplitude.init('API_KEY', { identityStorage: 'none', }); ``` You can also shorten cookie duration if your policy allows cookies but you want a more conservative setup. #### What to do outside Amplitude Decide exactly which events belong in the anonymous flow. Keep that list short. For most teams, that means page views, traffic totals, and other high-level measurement only. If you need stronger control, [send data through your own proxy before it reaches Amplitude](https://amplitude.com/docs/analytics/domain-proxy). A domain proxy can help you filter, block, or anonymize data before forwarding it. #### Keep the anonymous flow narrow If you choose this method, be disciplined. Don't quietly turn a "limited anonymous measurement" flow into full behavioral analytics over time. The more your anonymous flow starts to look like user analysis, the weaker your privacy position becomes. ## Keep consented and non-consented data in separate projects If you collect both consented analytics data and a limited non-consented measurement stream, always keep them in separate Amplitude projects. Mixing the two into a single project creates problems that are difficult to untangle later. Three reasons to be strict about this from the start: - **Reporting integrity**: non-consented data uses minimized or rotating identifiers, so user-level metrics like uniques, funnels, and cohorts behave very differently from your consented data. Keeping them separate makes it clear which numbers mean what. - **Risk of unintended user stitching**: Amplitude resolves identity at the organization level, not the project level. If the same user ID or device ID appears in both projects, Amplitude treats them as the same user. If your non-consented project wasn't designed with this in mind, you may inadvertently link anonymous data to identified users across projects. - **Access control**: the non-consented project should have tighter controls. Disable individual user-level event lookup so analysis stays at the aggregate level. This is much easier to enforce when the data is already in its own project. ### Configure the non-consented project more strictly [Separate projects](https://amplitude.com/docs/admin/account-management/manage-orgs-projects) let you configure the non-consented stream differently from the start. In practice, that usually means using the stricter setup in the non-consented project: no cookies, no persistent storage, no stable user ID, and a minimal event set. ### How to set it up A common setup looks like this: - one project for consented users, where full analytics begins after consent. - one project for non-consented users, where you only send the limited anonymous measurement events your policy allows. When a visitor hasn't consented, route the allowed events to the non-consented project. If the visitor later gives consent, initialize Amplitude with the consented project and begin normal tracking there. If you use this approach, make sure your identity strategy is intentional in both projects. Across projects in the same organization, Amplitude assumes that the same user ID or device ID refers to the same user. That's useful for legitimate cross-project analysis, but it also means you should be careful not to reuse identifiers across consent states unless that matches your legal and implementation model. ### Restrict user-level access where appropriate For some teams, separating projects isn't enough on its own. They also want the project that contains non-consented data to have tighter access to user-level views. In those cases, review whether features such as [User Lookup](https://amplitude.com/docs/analytics/user-data-lookup), user profiles, user streams, or similar user-level surfaces should remain available for that project. This is especially relevant if the project contains anonymous or non-consented data and your privacy posture is meant to avoid individual-level exploration. As a practical rule, many teams want a stricter setup for the non-consented project and a more standard setup for the consented one. If you need that kind of project-specific restriction, discuss it with your Amplitude team as part of the implementation design so they apply the right controls for your organization. #### Disabling User Lookup at the project level In addition to DAC and RBAC, Amplitude supports disabling the User Lookup feature at the project level. When your Amplitude team enables this setting, team members can't access individual user event streams from contextual menus in charts and dashboards (for example, the microscope icon that opens a user's event stream). This control is especially relevant when your privacy posture requires analysis to happen at the aggregate level only, and you want to prevent access to raw individual-level user events. For example, to comply with CNIL requirements in France, the exemption for analytics without consent applies only to aggregate statistical measurement. Your Amplitude team manages this setting at the project level. To apply it, contact your Amplitude team so they can enable it as part of your project configuration. You can also control broader user-level access using [RBAC](https://amplitude.com/docs/admin/account-management/user-roles-permissions), but the User Lookup control is separate and more targeted, specifically for disabling individual event stream access. ### Use Portfolios to combine top-line reporting If you want to analyze consented and non-consented projects together, use a Portfolio view. [Portfolio](https://amplitude.com/docs/admin/account-management/portfolio) lets you combine multiple projects into one cross-project view so you can build charts across them. This is useful when you want a broader picture of traffic or activity across consent states without collapsing the underlying implementations into one project. A good pattern is to: - keep the data collection separate. - use a Portfolio to report across both projects where that makes sense. - set expectations clearly about what can and can't be combined. For example, top-line event counts may be useful across both projects, while user-level metrics require more caution. If the non-consented project uses minimized identity, don't expect Portfolio reporting to recreate the same kind of user continuity you have in the consented project. #### Document the routing rules If you adopt the separate-projects pattern, document it clearly for both implementers and analysts. Teams should know: - which events go to which project. - when traffic moves from the non-consented project to the consented project. - which identifiers are allowed in each project. - which user-level features should be restricted in the non-consented project. - which charts should use the Portfolio view versus a single source project. This is one of the most practical ways to support privacy-sensitive measurement while keeping your analytics setup understandable and maintainable. > **Note:** When a non-consented user gives consent mid-session > > If a visitor initially arrives without consenting and later grants consent on the same visit, you need to handle the transition explicitly. The recommended approach is: > > 1. Stop sending to the non-consented project. After the user grants consent, stop routing events to the anonymous measurement project. > 2. Initialize Amplitude with the consented project key. Call `amplitude.init()` with your consented project's API key and, if the user is now identified, set their `userId` at this point. > 3. Don't attempt to retroactively link pre-consent activity to the now-identified user, unless your legal model explicitly allows it. The anonymous events from before consent should stay anonymous. > > This ensures a clean boundary: pre-consent activity stays in the anonymous project with no stable identity, and post-consent activity begins fresh in the consented project under the user's real identity. ### Method 3: Don't ask for consent, but reduce identifiers and data collection where your policy allows it In some regions or use cases, your legal team may decide that consent isn't required for your analytics setup. If so, you can still make that setup more privacy-friendly by limiting identifiers, shortening storage, and minimizing what you send. #### How to set it up in Amplitude Choose the storage mode that matches your policy: - `cookie` for standard browser persistence. - `localStorage` if you prefer browser storage without cookies. - `none` if you want no persistent identity. If you use `localStorage`, remember that it's limited by subdomain. A user on one subdomain won't automatically carry the same stored identity to another. If you use `identityStorage: "none"`, Amplitude generates a new `device_id` on every page load (or app start), because there's no stored identity to reuse between loads. > **Note:** > > Amplitude generates a new `device_id` on each page load or app start, not on each individual event. All events fired within the same page load share the same `device_id`. As soon as the user closes the tab or restarts the app, the next page load generates a completely new `device_id` with no link to the previous one. You can't reconstruct cross-session user journeys, which is the intended behavior for strict anonymization. #### What to do outside Amplitude Make sure your privacy notice matches what you're actually doing. If you're not asking for consent, your policy should still explain what you collect, why, and how users can opt out if that applies to your model. #### Minimize data by default Even when consent isn't required, data minimization is still a good default. Collect what you need, not what happens to be available. ## Use a proxy when you want tighter control A [domain proxy](https://amplitude.com/docs/analytics/domain-proxy) is useful when you want more control over what reaches Amplitude. It lets you send tracking requests through your own domain and can help with filtering, blocking, debugging, audit logging, and anonymization before forwarding data to Amplitude. This is especially helpful if you want to remove fields such as IP address, location, or `userId` before data leaves your environment. A proxy isn't the only way to do this. You can also exclude or suppress specific fields directly in the SDK at initialization time, which is easier when you only need to strip a small number of fields client-side. > **Note:** > > You can configure the Amplitude SDK at initialization time to suppress or exclude specific fields before any data leaves the client. For example, you can pass options in `amplitude.init(...)` to prevent IP address or user ID from being transmitted. The SDK config approach is simpler when you only need to strip a small number of fields client-side. A proxy is the better choice when you need centralized control, server-side enforcement, audit logging, or want the filtering to happen outside the client entirely, so that sensitive fields never leave your infrastructure at all. If you build a proxy, involve your developer operations and information security teams early. ## Keep noisy traffic out of your data Privacy settings work better when your data is also clean. ### Block bot traffic If you track public web traffic, bot traffic can distort your metrics. Amplitude lets you create a [block filter](https://amplitude.com/docs/data/block-bot-traffic) so this data is never ingested in the first place. To set it up: 1. Go to your project's _main_ branch. 2. Open **Filters**. 3. Open the **Block Filters** tab. 4. Click **Create Block Filter**. 5. Select **Bot Traffic**. 6. Save the filter. Amplitude blocks bots based on the User-Agent, using the IAB/ABC International Spiders and Bots List. ### Block internal traffic If your team tests in production, [block internal IP addresses](https://amplitude.com/docs/data/troubleshooting/instrumentation-issues#block-and-filter-internal-users) so employee traffic doesn't inflate your metrics. In Amplitude Data, create a block filter for **Events** where **IP Address** equals the addresses you want to block. A good practice is to keep a separate development project for testing and only use production for final validation. ## Restrict who can see sensitive data Collecting data responsibly is only half the job. You should also control who can see it. Amplitude's [Data Access Control (DAC)](https://amplitude.com/docs/data/data-access-control) lets you classify properties as **PII**, **revenue**, or **sensitive**, then grant or deny access to those classifications by group. With DAC enabled: - restricted users can't view charts, cohorts, dashboards, notebooks, or user sessions that contain restricted data. - Amplitude hides classified properties from Event Stream and User or Account Lookup. - restricted values appear as `[DAC Restricted]`. To set it up: 1. Ask Amplitude Support to enable DAC for your organization. 2. In _Amplitude Data_, classify the properties you want to protect. 3. In _Settings > Organization settings > Groups_, open the group and configure access on the **Data Access** tab. If you want broader role control beyond sensitive properties, use [RBAC](https://amplitude.com/docs/admin/account-management/user-roles-permissions) to define what users can do in each project and assign those roles through groups. ## Set a retention period If you don't need to keep event data forever, set a retention period. Amplitude's [Time to Live (TTL)](https://amplitude.com/docs/data/time-to-live) lets you define event retention at the organization level and override it per project. To configure it: 1. Ask Amplitude to enable TTL controls for your organization if they aren't already enabled. 2. Go to _Organization Settings_. 3. Open the **Time to Live (TTL)** tab. 4. Choose a retention period and confirm. 5. Add project-level overrides if some projects need a different retention policy. Be careful here. TTL causes irreversible data loss, and existing charts zero out for periods outside the retention window. A good rule is to set a shorter TTL for higher-risk datasets and a longer one only where there's a clear business need. ## Prepare for deletion requests If a user asks you to delete their data, you need a process that covers both Amplitude and any upstream systems. Amplitude's [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy) lets you programmatically submit deletion requests for known Amplitude IDs or User IDs. By default, deletions are project-based. If you want to delete the user across your organization, set `delete_from_org` to `true`. Two things matter in practice: - deleting a user doesn't block future tracking for that user. - if the same user data still exists in your warehouse or another ingestion source, Amplitude may ingest it again on the next sync. So your deletion workflow should be: 1. Receive the request. 2. Identify the correct user IDs. 3. Delete the user in Amplitude. 4. Delete the same user from the warehouse or any synced source. 5. Log completion for audit purposes. ## Validate your setup before launch After your setup is live, test it with real scenarios. At minimum, test: - a visitor who hasn't consented. - a visitor who grants consent. - a signed-in user. - a user who logs out. - a user whose data is deleted. In Amplitude, use [User Lookup](https://amplitude.com/docs/analytics/user-data-lookup) to inspect the event stream for a specific user and confirm what data was actually ingested. For each test case, check: - whether the SDK initialized. - whether Amplitude cookies or storage were created. - whether the expected events were sent. - whether the expected identifiers were present. - whether restricted data is visible only to the right users. This step is worth the time. Most privacy issues come from small implementation gaps, not from the policy itself. ## Recommended rollout order If you want a simple order of operations, use this: 1. Choose the consent method. 2. Decide what data is allowed. 3. Configure SDK initialization and storage. 4. Connect your CMP if needed. 5. Add filters for bots and internal traffic. 6. Classify and restrict sensitive properties. 7. Set data retention. 8. Document your deletion workflow. 9. Validate everything with end-to-end tests. That sequence keeps the work manageable and makes it much easier to explain your setup to internal stakeholders and external auditors. ## Additional considerations Depending on your implementation, you may need to configure more than cookies, storage, and access controls. The topics below are worth reviewing before you consider your setup complete. ### Session Replay If you use Session Replay, review it separately from your core analytics setup. Replay can capture a richer set of user interactions, so it often requires its own privacy review, masking rules, and consent treatment. In practice, this means you should: - decide whether Replay is covered by the same consent choice as analytics or needs separate treatment. - review masking and exclusion settings before rollout. - make sure your privacy notice accurately describes the use of replay technology. You can learn more in the [Session Replay documentation](https://amplitude.com/docs/session-replay). ### Access requests, not only deletion requests Many privacy programs focus first on deletion, but customers may also need to respond to requests for access to personal data. If you support privacy requests, plan for both. For deletion workflows, use the [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy). If you also need to support data access requests, refer to the [DSAR API documentation](https://amplitude.com/docs/apis/analytics/ccpa-dsar). A good practice is to document one operational workflow that covers: - request intake. - identity verification. - access or deletion in Amplitude. - cleanup in upstream systems. - audit logging. ### Privacy notices and disclosures Your implementation and your privacy notice should stay aligned. If you collect analytics data, use Session Replay, or rely on a limited anonymous measurement flow, review your disclosures to make sure they still describe what you collect, why you collect it, and how users can exercise their choices. This is especially important when teams change implementation details over time. A privacy issue is often caused not by the tool itself, but by a gap between what the product does and what the notice says. ### Hosting region and data residency For some organizations, especially in Europe, hosting region is part of the privacy decision. Amplitude offers both US and EU data center options, and that choice may affect your internal review process. If data residency matters to your business, confirm your hosting setup early and make sure it matches your internal requirements. You can learn more about [data residency options](https://amplitude.com/docs/admin/account-management/manage-orgs-projects). ### Operational caveats after launch Some privacy controls work exactly as expected, but still have practical consequences that teams should plan for. A few important examples: - deleting a user doesn't prevent Amplitude from tracking that user again. - if deleted data still exists in a warehouse or synced source, Amplitude may reingest it. - retention settings can permanently remove historical data and affect old charts. - test privacy settings after every major instrumentation or tag-management change. A good rollout doesn't end at launch. Re-test your setup periodically, especially after SDK updates, consent banner changes, new event launches, or changes to upstream pipelines. ### When to ask for help If your setup includes regional legal complexity, multiple consent categories, sensitive personal data, or multiple downstream activation tools, involve your legal, privacy, and security teams early. It's much easier to design a privacy-conscious setup from the start than to retrofit one later. In general, the safest approach is to keep the implementation simple, collect only what you need, and add complexity only when there's a clear business and legal case for doing so. ### Server-side tracking as an alternative for known users For logged-in or identified users, server-side tracking offers an alternative that avoids some client-side consent constraints. If a user is authenticated, you can pass their user ID directly to Amplitude's HTTP API from your backend, bypassing the browser SDK entirely. In many jurisdictions, server-side tracking of authenticated users doesn't trigger ePrivacy Directive requirements. ePrivacy applies to accessing or storing information on the user's device (cookies, localStorage, and so on), and server-side calls don't touch the device. For logged-in users, server-side Amplitude tracking may therefore not require consent under ePrivacy rules in some regions. Important caveats: - This only applies to known, logged-in users. For anonymous visitors, you still need a client-side identifier to track behavior across pages, even if your server generates that identifier (as with cookieless tracking approaches). As soon as you store or access any persistent identifier on the user's device, ePrivacy rules apply. - Your legal team should confirm whether server-side tracking of identified users is sufficient for your jurisdiction and use case. - Confirm with your privacy team that processing authenticated user data server-side aligns with your data processing agreements and your GDPR lawful basis. ## Why Amplitude doesn't generate modeled data for non-consenting users Some analytics platforms fill in the gap left by non-consenting users by modeling estimated behavior, statistically inferring what those users might have done based on users who did consent. Amplitude doesn't take this approach. Here's why. - Modeled data is inconsistent and hard to interpret. Platforms that offer modeling typically generate estimates only when they have enough activity volume to do so. Below certain thresholds, the platform produces no model at all, and coverage is uneven across segments, time periods, and properties. You can't easily tell when you're looking at real data and when you're looking at an estimate, and applying consistent analysis rules across your dataset becomes nearly impossible. - Modeled data behaves differently depending on where you query it. If you export modeled event data to a warehouse and run the same analysis there, you often get different results than you do inside the analytics UI. Platforms typically apply this logic at query time in the UI, not at ingestion. This creates a split source of truth that is very difficult to reconcile, particularly for teams who rely on warehouse exports for reporting or compliance. Amplitude's approach focuses on clear consent boundaries and accurate first-party data. It's better to know precisely what you measured and for whom than to fill gaps with estimates that are hard to validate or explain to auditors. If your organization uses Google services alongside Amplitude, you can configure Google Consent Mode for those tools independently. It doesn't affect how Amplitude processes data. ## Privacy and Amplitude AI features > **Note:** > > If your Amplitude account includes AI-powered features, such as Ask Amplitude, AI-generated insights, or other AI-assisted workflows, you may have questions about how your user data interacts with those features. For example, you may want to know whether event data is processed by third-party large language models (LLMs), and what data handling agreements apply. > > Amplitude's [Trust Page](https://trust.amplitude.com) includes a dedicated AI FAQ that covers these topics, including questions about data sharing with AI providers. > > For more detailed technical information, the [Amplitude AI privacy and security documentation](https://amplitude.com/docs/security-and-privacy/amplitude-ai-privacy-security) covers third-party LLM usage and related data handling practices. > > Review these resources and align with your privacy team before enabling AI-powered features, particularly if you operate under GDPR or handle sensitive personal data. ## Final recommendation If you want the safest and simplest default, start with **Method 1**: initialize Amplitude only after consent, keep your event schema tight, and add access controls and retention rules from day one. If your policy allows more flexibility, you can still keep the setup privacy-friendly by reducing identifiers, using a proxy when needed, filtering bad traffic, and limiting access to sensitive data inside Amplitude. ================================================================================ # Planning and instrumentation workflow URL: https://amplitude.com/docs/data/data-planning-workflow ================================================================================ # Planning and instrumentation workflow Using Amplitude Data for planning helps ensure high-quality data from the start and reduces the need for clean-up later. This article describes the complete workflow in Amplitude Data. ## Plan your events For most companies, the lifecycle starts when launching a product or feature. Suppose the product team creates a new onboarding flow and wants to see how it performs. The first step is determining what to track in this onboarding flow. What metrics does your feature affect, and what does success look like? After you identify the events and properties you want to track, create them on the _Events_ page. With Premium plans, you can create a branch to capture all your related changes without impacting anyone else. The Git branch in your code and the branch in Amplitude Data co-exist throughout the process. Engineering can pull analytics code from the Amplitude Data branch into their Git branch throughout the feature's development. Branches are especially helpful when multiple teams work on the same project, or when teams work on various features simultaneously. ## Instrument events If you haven't already, invite the developers working on the feature to Amplitude Data and ask them to review your proposed plan. If you work in a branch, send them a link to the _Activity_ page of your branch, which shows all the changes you want to make. Next, engineers implement the updated tracking plan in their branch. They use the [Ampli CLI](https://amplitude.com/docs/sdks/ampli/ampli-cli) to generate a new tracking library that matches the changes in the Amplitude Data branch (`ampli pull -b {branch-name}`). Iterating on your tracking plan with your developers is normal. You might respond to issues or challenges they encounter. Update your plan as your understanding evolves based on their feedback. > **Tip:** Automate instrumentation planning with AI > > The Amplitude MCP plugin includes skills that automate event discovery and instrumentation planning directly in your editor. Use `amplitude:add-analytics-instrumentation` to analyze a PR or branch diff, generate a complete instrumentation plan, and add events and properties to your Amplitude tracking plan with rich metadata, including descriptions and categories, without leaving your editor. > > For setup and the full list of available skills, refer to [Plan your taxonomy](https://amplitude.com/docs/data/data-planning-playbook#ai-assisted-taxonomy-planning). ## Request reviews If you configured your project for team reviews, you might not have permission to merge directly. Instead, you first create a merge request. A merge request asks stakeholders outside your team to review your changes and give their explicit approval. After the feature team is happy with the changes (the plan is comprehensive, and engineering implemented it correctly), your branch is ready for review by other stakeholders. > **Tip:** > > Refresh your changes from main to get your branch up to date and resolve any potential conflicts. You might do this more than once as your developers refresh their branch (with `git merge` or `git rebase`). Analytics changes often affect the broader organization, so getting feedback is essential. Typical stakeholders include the security and legal team, the growth team, and the data team. Soliciting reviews starts with creating a merge request. When creating a merge request, describe the changes you're proposing and @mention any specific reviewers or approvers you want to include. An admin- or manager-level user can then approve changes. ## Merge After the tracking plan changes are ready and everyone needed to approve has done so, you're ready to merge into main. When the rest of the feature team is ready to merge in Git, merge your branch in Amplitude Data first. Merging creates a new official version of your tracking plan on main and assigns new versions to all new and changed events. If your Git branch is already up to date with the merged Amplitude Data branch, you can now merge your Git branch as-is. Run `ampli status --is-merged` to check that your Ampli code is up to date with the merged Data branch. If the command returns an error, run [ampli pull](https://amplitude.com/docs/sdks/ampli/ampli-cli#pull) to update the generated library to the latest version. After `ampli status --is-merged` succeeds, you can merge the Git branch. ================================================================================ # Create a tracking plan URL: https://amplitude.com/docs/data/create-tracking-plan ================================================================================ # Create a tracking plan A tracking plan defines every event and property you collect, why you collect each one, and which source emits it. Build one before you instrument code so analysts, PMs, and engineers work from one schema instead of arguing about field names after the data lands. In Amplitude Data, the plan lives next to your events and properties, so edits flow straight into instrumentation, governance, and the Ampli code generator. Build or update a plan directly in Amplitude Data's UI when your team wants a shared, reviewable workspace for designing events and properties together. Use the [Amplitude MCP Server](https://amplitude.com/docs/amplitude-ai/amplitude-mcp#tracking-plan-changes) instead when you want an AI coding client to create or edit the same tracking plan directly from code. For the strategy behind designing a plan before you build it, refer to the [data planning playbook](https://amplitude.com/docs/data/data-planning-workflow). ## Find your tracking plan Each project in Amplitude has its own tracking plan. To find your plan, select the _Data_ tab in the top navigation. Then, in the left navigation, select the project from the dropdown at the top. The events and properties for your plan appear on the left. ## Update your tracking plan You can update your plan in two ways: - Proactively plan new events and properties before implementation, and use Amplitude Data to define details, work together with team members, and agree on what you want to track. (Recommended.) - Reactively plan events and properties after Amplitude ingests for the first time. By default, these events and properties appear in your plan as "Unexpected." You can add them to your plan, or delete them to stop ingestion and remove them from your data catalog. You can also create and update events, properties, and branches through the [Amplitude MCP Server](https://amplitude.com/docs/amplitude-ai/amplitude-mcp#tracking-plan-changes) from an AI coding client. MCP tools such as `manage_amp_events` and `create_properties` modify the same tracking plan you manage in Amplitude Data. ### Create a source [Sources](https://amplitude.com/docs/data/sources/connect-to-source) represent the originating source of the data sent to Amplitude (for example, your iOS, Android, Web, and Backend). When using the [Ampli Developer experience](https://amplitude.com/docs/sdks/ampli), you need to create a source to generate the correct tracking library. To create a source, follow these steps: 1. Navigate to _Data > Sources_ and select **Add Source**. 2. Select the SDK source you want to add. 3. Name your new source and select **Create**. ### Create an event An event is a distinct action that a user can take in your product. When you create an event, you can specify metadata about the event that helps with both implementation and discovery in Analytics after implementation. To create an event, follow these steps: 1. Navigate to _Data > Events_ and select **Create event**. 2. Give your event a name. Amplitude suggests any modifications to match your naming convention. 3. Add a source to specify where to instrument this event. 4. Add any relevant metadata, including: - A description to help define when to send the event or important details about the event. - A category to provide more context and group similar events. - The active or inactive status of the event. An active event is one the user triggers. Inactive events relate to the user, but a direct user action doesn't initiate them (for example, receiving a push notification). 5. Add any relevant event properties to the event. ### Create an event property Event properties describe the event and the context in which a user triggered it. For example, a `Song Played` event might contain a `Song Title` property. A name, description, examples, and rules define each property. Rules are specific to each data type. For example, property `Song Title` of type `String` can have the following rules: Min Length, Max Length, and Regex. To create a new event property, follow these steps: 1. In Amplitude Data, navigate to _Data > Properties_ and select the _Event Properties_ tab. 2. Select **Create event property**. 3. Give your event property a name and add any relevant metadata to the property, including: - A description. Including example values can be helpful. - Whether this property is required on this event. If it is, and Amplitude receives an event that doesn't include it, Amplitude Data generates a warning. - The data type (such as string or number) and any additional rules. You can now add this property to your events. To add an existing property, or create a new property within an event, follow these steps: 1. In Amplitude Data, navigate to _Data > Events_ and select the event you want to add a property to. 2. In the event detail pane, select **Add property**. 3. Name your new property, or select an existing property to add to the event. > **Note:** > > If multiple events share similar properties, you can [create a property group](https://amplitude.com/docs/data/property-updates-property-groups). Property groups, which are distinct from group properties, make it easier to manage complex tracking plans because you don't have to keep adding the same properties repeatedly. When you update a property group, the update applies to all events associated with the group. ### Create a user property User properties capture traits about the user. After you set a user property, it automatically applies to any subsequent events the user triggers, until its value updates. To create a new user property, follow these steps: 1. In Amplitude Data, navigate to _Data > Properties_ and select the _User Properties_ tab. 2. Select **Create user property**. Give your new user property a name. 3. Add any relevant metadata to the property, including: - A description. Including example values can be helpful. - The data type (such as string or number) and any additional rules. ### Create a group with group properties > **Note:** > > This feature requires the [Accounts](https://amplitude.com/docs/analytics/account-level-reporting-setup) add-on. Group properties make it easy to associate a user with a particular account (for example, name, industry, or employees) whenever the `group()` call runs. Group properties help when you want to track groups of users (for example, tracking events across an entire company, instead of specific users within that company). To create a group, follow these steps: 1. In Amplitude Data, navigate to _Data > Groups_ and select **Create group**. 2. Name your group and add any relevant metadata, including: - A description. Including example values can be helpful. - The data type (such as string or number) and any additional rules. 3. Add any group properties that apply to this group type. To create a group property, follow these steps: 1. In Amplitude Data, navigate to _Data > Properties_ and select the _Group Properties_ tab. 2. Select **Create group property**. 3. Name your group and add any relevant metadata, including: - A description. Including example values can be helpful. - The data type (such as string or number) and any additional rules. ## Collaborate on your plan If you want feedback on any changes you've made, you can @mention your colleagues in the rich text editor of any event or property to send them an email notification or Slack message. This approach helps when you're working on a branch and finalizing the event and property names you plan to use. ## Send your plan to your developers Finally, send this plan to your developers. If you're using the Ampli Developer Tools, it consumes your tracking plan and presents it to developers as type-safe autogenerated code. Amplitude Data can generate a tracking library for all popular platforms and programming languages. The autogenerated library is a lightweight wrapper over your analytics provider's SDK that provides type-safety, supports linting, and enables additional features like input validation. The code exactly replicates the spec in the tracking plan and enforces all its rules and requirements. You can also send them a link to the branch or directly to Amplitude Data, where they can review the details you specified. ================================================================================ # Work with branches URL: https://amplitude.com/docs/data/work-with-branches ================================================================================ # Work with branches A **branch** in Amplitude Data is a point-in-time copy of your tracking plan that you and your team edit privately, without exposing the changes to anyone else until you merge them back into the main tracking plan. If you've used Git, the model works the same way: you isolate changes on a branch, then merge them when they're ready. When you first create your Amplitude Data account, Amplitude automatically creates a default branch called `main`. It includes a few sample events and properties to get you started. Think of the `main` branch as your production branch: it contains your latest official tracking plan and matches what's instrumented in your default branch in Git (typically `master` or `main`). `main` is suitable for getting started in Amplitude Data, and you may find that it's the only branch you need for some time. ## Publish a version of your tracking plan A branch initially keeps the changes you make in its staging area, where they remain **pending**. Pending changes are work-in-progress changes: visible to you and your teammates, but hidden from your production systems and not yet available for instrumentation by your engineering team. When your pending changes are ready, **publish** them. Publishing your changes creates a new version of your tracking plan that includes those changes. Publishing also exposes that new version to your engineering team for instrumentation. If your new version is on the main branch, those changes also propagate to your production systems. Every new version has a version number and an optional description, so you can tell versions apart later. Version numbers start at 1 and increment by 1 each time you publish a new one. Every branch has its own tracking plan versions, which means it's possible to have two versions of the tracking plan with the same version number: one in `main`, and one in your own branch. When this happens, Amplitude Data always displays the name of the branch to avoid confusion. ## Create and delete branches As you and your team ramp up your use of Amplitude Data, you may outgrow the `main` branch and need a more robust workflow. This usually happens when: - Too many people are making changes to `main` at the same time, or - Feature teams want their own separate copy of the tracking plan to collaborate in, review their work, and get stakeholder approval. In Amplitude Data, all branches spawn from `main` and merge back into `main`. To **create** a new branch, follow these steps: 1. Click **main** in the page's header. 2. Type the name of the branch you want to create. 3. Click **+**. 4. In the _Create branch_ modal, confirm the name of your branch, add an optional description, and click **Create**. If you have pending changes on `main`, you can either take those changes with you into your new branch, or leave them behind on `main`. To **delete** a branch, follow these steps: 1. Click the **X** next to the branch name. 2. In the modal that appears, click **Delete** to confirm your choice. ## Work on a branch After your branch exists, working with it is like working with `main`. You and your team can create and publish new versions, instrument those versions in the product, and report back to the branch on the status of the instrumentation. This can all happen in parallel with other teams working in their own branches, without any impact on you. From time to time, refresh your branch with any changes made to `main` since you created your branch. If Amplitude Data detects that your branch is out of date with `main`, you see a **Refresh** button in the page's toolbar. Click it to get caught up. ## Merge your branch back into main When you're happy with the changes you've made on your branch, merge them back into `main`. This typically happens when your product team is also ready to merge their changes into the `main` branch in Git. There are a few prerequisites to address before you can successfully merge: - You must publish all pending changes on your branch. - Your branch must be up to date with `main`. - `main` must have all its pending changes published as well. To publish your changes to a new version on your branch, follow these steps: 1. In the left sidebar, click **Save changes**. 2. In the _Save changes_ modal, review the pending changes. If everything looks correct, click **Save**. To merge, follow these steps: 1. Go to _Activity_. You may have to click **Refresh**. 2. Click **Approve**. 3. Click **Merge**. If your project requires [team reviews](https://amplitude.com/docs/data/amplitude-data-settings), you may not have permission to merge directly. In this case, you must first create a merge request. A merge request is a way to ask stakeholders outside your team to review your changes and give their explicit approval. Only team members with Manager or Admin permissions can approve changes; do so by logging into Amplitude Data and clicking **Merge** in the page's toolbar. Anyone on your team can then merge an approved merge request. ## Copy branch changes to testing environments After you apply changes to a branch, you can copy those changes to other projects or environments for testing. To copy branch changes, follow these steps: 1. Go to _Activity > Branch Changes_ from the branch you want to copy. 2. Click **Copy Branch**. 3. In the modal that appears, select the testing projects to copy the branch to from the dropdown. Then click **Copy**. 4. After the copy completes, click the notification to review the copied branch. 5. Review changes to the testing project. If changes look as expected, click **Merge**. Managers and Admins can also restrict which projects can accept copies of branch changes. To restrict branch copying, follow these steps: 1. From the source project, go to _Settings > General_. 2. Select the checkbox next to **Restrict branch copying to specified testing projects**. 3. From the dropdown, select the checkbox next to the projects where other Amplitude users can save copies of branch changes. ================================================================================ # Ampli and developer tools URL: https://amplitude.com/docs/data/use-ampli ================================================================================ # Ampli and developer tools **Ampli** dynamically generates a lightweight wrapper for the **Amplitude SDK** based on your analytics tracking plan in **Amplitude Data**, making event tracking easier and less error-prone. The **Ampli Wrapper** provides types and methods that prevent human error by strictly enforcing event names and property values. The wrapper code enables autocompletion for all events and properties in your tracking plan, plus static type checks at development and compile time. To learn more about using Ampli, go to the [Amplitude Developer Center](https://amplitude.com/docs/sdks/ampli). ================================================================================ # Monitor your data with observe URL: https://amplitude.com/docs/data/validate-events ================================================================================ # Monitor your data with observe Observe continuously inspects, analyzes, and monitors your event stream against your tracking plan, surfacing invalid, missing, and out-of-date events as they occur. It needs no code changes and runs automatically in the background, keeping your tracking code in sync with your tracking plan. Observe assigns every event one of four statuses: unexpected, valid, invalid, or out of date. Observe listens to your existing event stream and turns your tracking code into a living document, so you get a holistic view of your data collection across platforms. You and your teams get immediate insight into anything broken or that needs attention. With an intuitive, collaborative workflow, your teams can work together to instrument fixes and keep your tracking plan in shape. ## View and update your event statuses To access your event stream, go to _Data > Events_. This displays all your events. The first time you view your tracking plan, Amplitude displays all events and properties received and processed. By default, Amplitude categorizes all events and properties as _Unexpected_. To add them to your tracking plan, check the box next to the event name and click **Add to plan**. Do this anytime you want to add an unexpected event to your tracking plan. Click **Publish** to complete the process. From this point on, Observe alerts you about any changes to this event or any properties associated with it. Your events always have one of four statuses: - **Unexpected**: Any event or property not yet added to your tracking plan. - **Valid** (and **Current**): Any event or property that matches (in name and schema) the latest version of an existing event. If Observe doesn't know the version of the event, it only ensures that the event shape matches your current tracking plan. - **Invalid**: Any event or property that doesn't match your current tracking plan. - **Out of Date**: Any event or property that matches a previous version of an existing event or property (only applicable when using Amplitude SDKs). Observe only surfaces data as it occurs. If you have legacy tracking or events that fire infrequently, they may not appear in your tracking plan. If you know of events that Observe doesn't surface, you can add them manually to your plan, or trigger the events yourself. > **Note:** > > If you're blocking, filtering, or transforming your data upstream of Amplitude, Observe can't access this data. For this reason, ensure that you send all your data to Amplitude. ### Observe and the Ampli CLI If you've instrumented all your event tracking using Amplitude's SDKs, you already benefit from type-safe analytics libraries, client-side validation, and continuous integration with [CI](https://amplitude.com/docs/sdks/ampli/validate-in-ci) for clean, accurate data you can trust. Observe still adds value by surfacing and alerting you to runtime validation errors in the web app. This is specifically relevant for JavaScript, because it isn't a type-safe language, and checks only happen at runtime. Refer to the Amplitude Data developer documentation for more details. ## Overlay your tracking plan with observed events and issues You can overlay your tracking plan with your event stream. If you're using the Amplitude SDK, you also have the option to overlay your tracking plan with your event stream from an environment, but **only** data sent to the **specific branch** you're on. This is useful for debugging when multiple teams send data to the environment. You can also **set a specific time range** to use for overlaying your event stream with your tracking plan. You can choose from: - Five minutes. - One hour. - 12 hours. - Seven days. - 14 days. Note that changing this range can determine whether Observe considers an event valid or invalid. For example, if you had a bug seven days ago, choosing _Last 7 days_ causes the event to show up as invalid. If you fixed it at any point between seven days ago and 12 hours ago, and then choose _Last 12 hours_, Observe considers it valid. ## Act on your Observe insights Observe surfaces missing and invalid properties on an event. The property rows show this information in a few ways: - **Status tooltip**: Indicates if an event was invalid at the point Amplitude received it (if Observe receives the version, it compares the event to the version; otherwise, it compares the event to your current tracking plan). - **% Seen indicator**: Red if the property is required (published or unpublished) and Amplitude received the event without the property within the selected timeframe. The indicator can be red while the status is green if you have unpublished changes, or if you recently modified the event. - **Type indicator**: Red if Amplitude received the property with a type other than what's selected (published or unpublished) within the selected timeframe. The indicator can be red while the status is green if you have unpublished changes, or if you recently modified the event. Observe automatically detects the source of each event (based on the library) and displays those sources in the event detail pane. This is especially helpful when you have multiple sources managed by different teams, because you can identify which source is sending invalid data. The sparkline to the right of the source name shows both total and invalid event volume to quantify the amount of data with errors. You can also create and assign multiple SDK sources with the same library. For example, if you have a marketing site and a web app that use the Browser SDK, you can create two different sources and assign the correct source to each event. Using Ampli also lets you see each source's volume and validation data separately. If you're not using Ampli, you see the volume for both sources rolled up into a single row with the library name (in this case, "Browser SDK".) ## Scope and limitations Observe works by default if you're sending data to Amplitude. Observe is limited by how you're sending data to Amplitude. If you're using Amplitude's SDKs (current source support: JavaScript, Node.js, Android, and iOS), Observe can attribute your event stream to its respective source (web, iOS, backend, and so on). > **Note:** > > If Observe can determine the version of your event, it validates against that version's schema. When Observe doesn't know the version, it validates against the schema of the latest version in your tracking plan. ================================================================================ # Protect your schema from unexpected data URL: https://amplitude.com/docs/data/configure-schema ================================================================================ # Protect your schema from unexpected data Schema settings control how Amplitude handles data that violates your schema. A schema violation happens when Amplitude receives data that your schema doesn't account for, such as an event you didn't plan or a property value with an unexpected type. You configure a response to three types of schema violation: unplanned event types, unplanned event or user properties, and unplanned property values. For each type, Amplitude either marks the data as unexpected and ingests it, or rejects it. Use schema settings when you want Amplitude to mark or reject data that violates your schema at ingestion. To monitor your event stream for invalid, missing, or out-of-date events without changing how Amplitude ingests data, use [Observe](https://amplitude.com/docs/data/validate-events) instead. Find your schema settings by going to Amplitude Data and navigating to _Settings > Schema Settings_. ## Unplanned event types Sometimes, Amplitude may receive an event that isn't part of your schema, or that you didn't plan earlier. This is an **unplanned event type**. You can configure Amplitude to respond in these ways: - **Mark As Unexpected**: Amplitude ingests the event, triggers a warning, and sends a notification to the designated subscribers. The event's category in drop-downs is "Unexpected" until you approve it. - **Reject**: Amplitude rejects the event and sends a notification to the designated subscribers. Amplitude doesn't store the event or its properties. ## Unplanned event or user properties When Amplitude encounters an event or user property that isn't part of your schema, or that you didn't plan earlier, it considers the property to be an unplanned event or user property. You can configure Amplitude to respond in the following ways: - **Mark As Unexpected**: Amplitude ingests the property, triggers a warning, and sends a notification to the designated subscribers. - **Reject**: Amplitude rejects the property and sends a notification to the designated subscribers. Amplitude stores the event, but not the properties. ## Unplanned event or user property values When Amplitude receives an event property value that isn't part of your schema, or that you didn't plan earlier, it considers the value an unplanned property value. For example, an event property value arrives as a string, but your schema expected a number. You can configure Amplitude to respond to an unplanned property value in the following ways: - **Mark As Unexpected**: Amplitude ingests the property, triggers a warning, and sends a notification to the designated subscribers. - **Reject**: Amplitude rejects the property, triggers a warning, and sends a notification to the designated subscribers. Amplitude stores the event, but not the properties. If Amplitude rejects your event data and you want to ingest it, add the events or properties to your schema by planning a new event or property. ## View validation errors After you initialize your schema and define your expected events and event properties, your schema can validate live data coming into Amplitude. If you configured your schema to trigger a warning for unexpected events or properties, Amplitude logs an error in the validation errors panel. View validation errors by going to Amplitude Data and navigating to _Settings > Schema Settings > Validation Errors_. Any errors triggered in the last 24 hours appear on this page, whether or not you've since approved or rejected the event or property. If no errors appear on the validation page, there haven't been any violations in the past 24 hours. This doesn't mean you've fixed every violation; it only means Amplitude hasn't encountered them in that time. Select **Subscribe** to set up email alerts for validation errors. ## Manage subscribers You can designate specific users to receive email notifications of any schema violations. Select **Manage Subscribers** at the top right of your schema options. ================================================================================ # .CSV import and export URL: https://amplitude.com/docs/data/csv-import-export ================================================================================ # .CSV import and export Import and export your tracking plan as a .CSV to make bulk schema changes in Amplitude Data. The .CSV round-trip covers events, event properties, and user properties, and supports planning new events, editing categories and descriptions, and applying changes in one upload instead of editing entities one at a time. Use .CSV import when you need to make bulk schema edits across many events or properties at once. For programmatic, automated, or scripted schema changes, use the [Taxonomy API](https://amplitude.com/docs/apis/analytics/taxonomy) instead. ## Events and event properties Follow these steps to import or export events and event properties: 1. Navigate to Data, and select _Events_ under your tracking plan in the left side pane. 2. To import, select the import icon to open the import modal. 3. If your import file is ready to upload and follows the [expected schema for events and event properties](#events-and-event-properties-file-schema), you can drop your .CSV file or select _Upload_ and choose the file from your location. If not, select _template_ to download a template .CSV to update for importing. The imported events and event properties appear in a branch named _import_. 4. After you confirm the imported tracking plan updates are correct, you can [merge the changes back into the main branch](https://amplitude.com/docs/data/data-planning-workflow). 5. To export events and event properties from your tracking plan, select the export icon instead. 6. In the export modal that appears, choose whether to download your tracking plan's schema or a .CSV file template. Then, select _Download_. Downloaded .CSV files of your tracking plan contain additional fields not required for import. The next section defines the events and event properties .CSV import file structure and the [additional columns seen in the exported file](#events-and-event-properties-file-schema). > **Note:** > > The import and export features don't support custom events, transformations, or default Amplitude entities. ## Events and event properties file schema The events and event properties .CSV file requires a specific schema for a successful import. The table below highlights the required schema by entity type. Note that: - The file's header must contain all listed fields. - The fields can be in any order, but their names and values must match exactly in spelling and capitalization for a successful import. - Some fields require a value depending on entity type, as indicated in the following list. **Action** - Definition: Action to perform on a particular entity. - Values: - `Ignore`: No changes made to the entity or its subproperties. - `Remove`: You can remove event and property groups from the tracking plan. The remove value doesn't affect individual properties. Removing an event or property group disassociates related properties, and changes a live property's status to unexpected. The remove value doesn't delete an entity or stop ingestion. - `<blank>`: Creates or updates an entity and its associated sub-entities. - For events, event properties, property groups, and property group properties. **Array min items** - Definition: Minimum number of items for a property with an array property value type - For event properties and property group properties **Array max items** - Definition: Maximum number of items for a property with an array property value type - For event properties and property group properties **Array unique items** - Definition: Denotes if an array property value type has unique items - Values: - `TRUE`: Array has unique items - `<any>`: Assumes array doesn't have unique items - For event properties and property group properties **Const value** - Definition: Const value for properties with a const property value type - For event properties and property group properties **Enum values** - Definition: Enum values for properties with an enum property value type - Format: Separate each enum value with a comma - For event properties and property group properties **Event activity** - Definition: Description of an event's activity. - Values: - `Active`. - `Inactive`. Marking an event as inactive applies retroactively and immediately, and excludes the event from the `Any Active Event` metric. - For events. **Event hidden from dropdowns** - Definition: Set event visibility in dropdowns - Values: - `True`: Event is hidden in event dropdowns - `False`: Event is visible in event dropdowns - `<blank>`: Retains the current value - For events **Event hidden from persona results** - Definition: Set event visibility in persona results - Values: - `True`: Event is hidden from persona results - `False`: Event is visible in persona results - `<blank>`: Retains the current value - For events **Event hidden from pathfinder** - Definition: Set event visibility in pathfinder - Values: - `True`: Event is hidden from pathfinder - `False`: Event is visible in pathfinder - `<blank>`: Retains the current value - For events **Event hidden from timeline** - Definition: Set event visibility in timeline - Values: - `True`: Event is hidden from timelines - `False`: Event is visible in timelines - `<blank>`: Retains the current value - For events **Event category** - Definition: Category of an event - For events **Event display name** - Definition: Only applicable to optional display names of events - For events **Event property name** - Definition: Name of the property - Required for event properties and property group properties **Event source** - Definition: Sources associated with the event - For events **Number property value min** - Definition: Minimum value of a property with number property value type - For event properties and property group properties **Number property value max** - Definition: Maximum value of a property with number property value type - For event properties and property group properties **Number is integer** - Definition: Denotes if a property with number property value type is an integer - Values: - `True`: Property is an integer - `False` or `<blank>`: Property isn't an integer - For event properties and property group properties **Object type** - Definition: Entity type - Values: - `Event` - `Property Group` - **Required** for events and property groups **Object name** - Definition: Name of the event or property group - **Required** for events and property groups **Object owner** - Definition: Owner of the event or property group - Leaving this as `<blank>` removes the owner if one exists on the event or property group **Object description** - Definition: Description of the entity - For events and property groups **Property type** - Definition: Type of property associated with the event - Values: - `Event Property` - `Event Property Group` - **Required** for events **Property group names** - Definition: Property group that's associated with the event - For events **Property description** - Definition: Description of the property - For event properties and property group properties **Property value type** - Definition: The value type of an event property or property group property - Values: - `string` - `number` - `boolean` - `any` - `enum` - `const` - For event properties and property group properties **Property required** - Definition: Denotes the required status of the property - Values: - `True`: Property is required - `False` or `<blank>`: Property is optional - For event properties and property group properties **Property visibility** - Definition: Set property visibility in charts - Values: - `VISIBLE`: Property is visible in charts - `HIDDEN`: Property is hidden in charts - `<blank>`: Retains the current value - For event properties only **Property is array** - Definition: Denotes if the property is an array - Values: - `True`: Property is an array - `False` or `<blank>`: Property isn't an array - For event properties and property group properties **Property regex** - Definition: Regular expression (Regex) values for properties with a string property value type - For event properties and property group properties **String property value min length** - Definition: Minimum length of a property with string property value type - For event properties and property group properties **String property value max length** - Definition: Maximum length of a property with string property value type - For event properties and property group properties **Tags** - Definition: Tags associated with an event - Format: separate each tag with a comma - For events ### Additional fields .CSV export of events and event properties The following list includes additional fields found in the .CSV export of your tracking plan’s events and event properties. **Action** - Definition: The default action to perform on a particular entity. This field exists in the import template, but the downloaded file includes default values. - Values: - `Ignore`: The user property is unexpected, blocked or deleted. - `<blank>`: The user property is planned or live. - For events, event properties, property groups property group properties **Event first seen** - Definition: The date on which the event was first seen. - Format: `mm/dd/yyyy` - For events **Event last seen** - Definition: The date on which the event was last seen. - Format: `mm/dd/yyyy` - For events **Property first seen** - Definition: The date on which the property was first seen. - Format: `mm/dd/yyyy` - For property groups **Property last seen** - Definition: The date on which the property was last seen. - Format: `mm/dd/yyyy` - For property groups ## User properties Follow these steps to import or export user properties: 1. Navigate to Data, and select _Properties_ under _Tracking Plan_ in the left side pane. Then select _User Properties_. 2. Select the import icon to open the import modal. 3. If your import file is ready to upload and follows the [expected user properties schema](#user-properties-file-schema), you can drop your .CSV file or select Upload and choose the file from your location. If not, select _template_ to download a template .CSV to update for importing. The imported events and event properties appear in a branch named _import_. 4. After you confirm the imported tracking plan updates are correct, you can [merge the changes back into the main branch](https://amplitude.com/docs/data/data-planning-workflow). 5. To export user properties from your tracking plan, select the export icon instead. 6. In the export modal that appears, choose whether to download your tracking plan's schema or a .CSV file template. Then, select Download. The next section defines the user properties .CSV import file structure and the [additional columns seen in the user properties export](#user-properties-file-schema). ## User properties file schema The list below highlights the required schema for the user properties .CSV file import. Note that: - The file's header must contain all listed fields. - The fields can be in any order, but their names and values must match exactly in spelling and capitalization for a successful import. - Some fields require a value as indicated in the following list. **Action** - Definition: Action to perform on a particular user property. - Values: - `Ignore`: Amplitude makes no changes to the user property. - `Remove`: Amplitude removes the user property from the tracking plan. The removed value doesn't delete a user property or stop its ingestion. - `<blank>`: Creates the user property if it didn't already exist, or updates the user property if it did exist. **Array min items** - Definition: Minimum number of items for a property with an array property value type **Array max items** - Definition: Maximum number of items for a property with an array property value type **Array unique items** - Definition: Denotes if an array property value type has unique items - Values: - `TRUE`: Array has unique items - `<any>`: Assumes array doesn't have unique items **Const value** - Definition: Const value for properties with a const property value type **Enum values** - Definition: Enum values for properties with an enum property value type - Format: Separate each enum value with a comma **Number property value min** - Definition: Minimum value of a property with number property value type **Number property value max** - Definition: Maximum value of a property with number property value type **Number is integer** - Definition: Denotes if a property with number property value type is an integer - Values: - `True`: Property is an integer - `False` or `<blank>`: Property isn't an integer **Property type** - Definition: User property type - Values: User property **(required)** **Property name** - Definition: Name of the user property - This value is **required** **Property description** - Definition: Description of the user property **Property visibility** - Definition: Set property visibility in charts - Values: - `VISIBLE`: Property is visible in charts - `HIDDEN`: Property is hidden in charts - `<blank>`: Retains the current value **Property value type** - Definition: The value type of a user property - Values: - `string` - `number` - `boolean` - `any` - `enum` - `const` **Property is array** - Definition: Denotes if the property is an array - Values: - `True`: Property is an array - `False` or `<blank>`: Property isn't an array **Property regex** - Definition: Regular expression (Regex) values for properties with a string property value type **String property value min length** - Definition: Minimum length of a property with string property value type **String property value max length** - Definition: Maximum length of a property with string property value type ### Additional fields in .CSV export of user properties The following list includes additional fields found in the .CSV export of your tracking plan’s user properties. **Action** - Definition: The default action to perform on a particular entity. This field exists in the import template, but the downloaded file automatically includes default values. - Values: - `Ignore`: The user property is unexpected, blocked, or deleted. - `<blank>`: The user property is planned or live. **Property first seen** - Definition: The date on which the property was first seen. - Format: `mm/dd/yyyy`. **Property last seen** - Definition: The date on which the property was last seen. - Format: `mm/dd/yyyy`. ## Common questions ### Export options for raw chart or event data These questions all have the same answer: - How do I export raw data for a chart or event? - Can I export the raw event data for the events included in this chart instead of the chart results? - How do I export a .CSV of all occurrences of a specific event? - How do I see the data that was pulled into this chart? - Can I see event and user property values for every instance of this event in the last 30 days? There's no way to export selected raw data for a chart or all data for selected events. Amplitude is built to perform large-scale, complex analyses inside the application, so isolating and exporting event data in a SQL-like manner isn't supported. A few alternatives: - **Export API**: to export all values of an event and its event properties, use Amplitude's [Export API](https://amplitude.com/docs/apis/analytics/export). It exports all events across a specified time range and returns them in JSON format. From there, you can extract the specific events you want. If your data exceeds the Export API size limit, use Amazon S3 Export instead. - **Amazon S3 Export**: integrate Amplitude with Amazon S3 to export your event data to an S3 bucket. This integration is available on all accounts, including the free plan. Refer to [Amazon S3 Export](https://amplitude.com/docs/data/destination-catalog/amazon-s3). ### How does Amplitude determine the structure of the .CSV file when exporting from an Event Segmentation chart? Amplitude uses the breakdown data table as a guide when creating the .CSV. Amplitude mirrors the format and structure of the table in the .CSV. ### Why isn't the .CSV file showing all the possible values of the user or event property? There are limits on the number of values that appear in a .CSV. The limits differ from chart to chart. Refer to [Limits and quotas](https://amplitude.com/docs/faq/limits-and-quotas#csv-download-limits). ### Why is the value of a user property different between the chart and the .CSV export? When you download users from the chart through Microscope, the .CSV contains the most recent property values for the user. The chart returns the property value _at the time of the event_. The same applies when the .CSV has property values listed as "none" in the chart: the .CSV shows the most recent value, while the chart shows the value at the time of the event. ### Why are there leading spaces (tabs) in my exported .CSV file? By default, leading empty spaces can appear in the cells of an exported .CSV. To change the default: 1. Go to **Personal settings**. 2. Go to **Profile**. 3. Enable **Always Remove Leading Spaces from Export** under **Site Settings**. Refer to [Manage your settings](https://amplitude.com/docs/admin/account-management/account-settings) for more. ================================================================================ # Integrate Jira with Amplitude Data URL: https://amplitude.com/docs/data/integrate-jira ================================================================================ # Integrate Jira with Amplitude Data Amplitude Data lets you integrate with Jira to quickly create new Jira issues whenever you make changes to a feature branch. You can only create issues from within the feature branch, and you can only associate changes with a Jira ticket. ## Set up the integration To set up and use the integration, follow these steps: 1. In Amplitude Data, navigate to _Settings > Integrations_ and find the Atlassian Jira panel. Click _Add_, and in the modal that appears, click _Authenticate_ to start the authentication flow. 2. Another modal appears asking you to authorize Jira access for your site. From the drop-down in the modal, select the site you want to authorize. Then click _Accept_. ## Create a Jira issue in Amplitude Data To create a new Jira ticket from within Amplitude Data, follow these steps: 1. Create a feature branch and make your changes there. You can only use this integration from within a feature branch. 2. Your changes appear grouped by sources under the Home page. If you successfully integrate with Jira, you can create a Jira Issue for each source inside Amplitude Data. Click _+Jira_ to create a new issue or link an existing issue to current changes. 3. To unlink an issue from your feature branch, hover over the issue tag and click _Unlink Jira_. In the modal that appears, click _Unlink_ to confirm the unlink action. After you link an issue to a source, any subsequent published changes automatically leave a comment on the Jira issue. ================================================================================ # Manage access to sensitive data with Data Access Control URL: https://amplitude.com/docs/data/data-access-control ================================================================================ # Manage access to sensitive data with Data Access Control Data Access Control (DAC) restricts which users can access sensitive categories of event and property data, such as revenue data or personally identifiable information (PII), so unauthorized users can't view them. Enterprise organizations use DAC to classify this data and prevent inadvertent data leaks. > **Note:** Enable this feature > > Contact [Amplitude Support](https://gethelp.amplitude.com) to enable Data Access Controls for your organization. ## How Data Access Control works DAC works within Amplitude's Groups framework. Admins grant or restrict access to PII, revenue data, and sensitive information for all members of a group. From there, admins can [add or remove users from these groups](https://amplitude.com/docs/admin/account-management/manage-permission-groups#edit-a-group) as access requirements change, either at the individual or organizational level. For example, when an unauthorized user tries to view a chart that includes restricted information, Amplitude blocks the chart from loading. Those users also can't create new charts that might include restricted data. This applies to charts, cohorts, dashboards, notebooks, and user sessions. > **Note:** > > Organization admins always have access to all data classifications, regardless of any DAC restrictions. When a user encounters a chart they can't view because of restricted data, Amplitude specifies the properties or cohorts that DAC blocked. The user can then exclude the restricted data and view the chart (or cohort, dashboard, notebook, or user session) without it. With DAC enabled, Amplitude hides classified properties from the Event Stream and User or Account lookup pages. When your project's users encounter classified data, Amplitude displays the value as `[DAC Restricted]`. The same restrictions apply to Ask Amplitude. ## Set access for specific categories of sensitive data Setting access levels is a two-stage process. First, classify your data. After that's complete, set up permissions. > **Note:** > > DAC applies only to properties. It doesn't apply to definitions or metadata. ### Classify properties 1. In Amplitude Data, go to _Properties_ and select the tab that contains the properties you want to classify. DAC lets you classify User, Event, and Group properties in your tracking plan, except for Amplitude ID, Version, Platform, Group ID, and Group name. > **Note:** Properties not eligible for classification > > Amplitude doesn't support classifying transformed properties or unexpected properties. > > Transformed properties inherit classification from their component properties. > > To classify an unexpected property, add it to your tracking plan. 2. Select the name of the property you want to classify. You can manage event, user, and group properties directly. Derived properties inherit all the classifications of their parent properties. 3. In the details panel that opens, select the _Classification_ drop-down and choose all relevant classifications for this property. Then select **Send**. 4. Repeat steps 2 and 3 for each property you want to classify. > **Warning:** Classifying the User ID property > > If you classify `user_id`, users without access to that classification can't use [Event Explorer](https://amplitude.com/docs/analytics/charts/event-explorer). ### Set up permissions 1. Go to _Settings > Organization settings > Groups_ and select the name of the group you want to edit. You can also [create a new group](https://amplitude.com/docs/admin/account-management/manage-permission-groups#create-a-group). 2. Open the group's _Data Access_ tab. Three controllable classifications appear here: PII, revenue, and sensitive. 3. For each classification, select _Yes_ to allow members of the group to view this data, or _No_ to deny access. 4. When you're done, select **Save**. ## Data Access Controls overview page > **Note:** > > This page is available to users with the Administrator role. Go to _Organization Settings > Data Access Controls_ to view the Data Access Controls overview page. There, find information about the following: - The number of groups with access to data classified as `PII`, `Sensitive`, or `Revenue`. - The number of users with access to data classified as `PII`, `Sensitive`, or `Revenue`. - All event, user, and group properties classified as `PII`, `Sensitive`, or `Revenue`. Drill into any cell in the table for a detailed view of the specific users or groups with access to each classification, or for more detailed information about the properties in each classification. Update user and group access from the Overview page, or go to _Data_ to update any property classification. Use the project switcher to view classifications for each project, and select _Classify Data_ to open that project's tracking plan, where you can manually classify properties. To customize the error message that your internal users see when they try to access a restricted chart or cohort, select **Customize Restricted Access Message**. On the resulting modal, edit the error message and include any links to internal documentation that might help. > **Note:** > > When you customize the restricted message, the message applies to your organization, not just the project. ## Access request notifications Users who go to a restricted chart or cohort can contact an administrator in their organization to request access. Amplitude sends this request to all organization administrators. > **Note:** Turn off access request notifications > > Administrators can deselect the `Someone requests access to a property classified by Data Access Controls` notification in _Personal Settings > Notifications_ to opt out. ## Exports and subscriptions DAC enforcement applies to all exports and subscriptions in Amplitude: - If a user selects **Download Users** from the [microscope](https://amplitude.com/docs/analytics/microscope) in a chart, the CSV export excludes properties with classifications they can't access. - If a user tries to export a CSV from a dashboard, the export excludes charts they can't access. - If a user tries to export a PDF or PNG from a dashboard, the export obfuscates charts and cohorts they can't access. - If a user tries to subscribe to a chart they can't access, Amplitude cancels the subscription and the user doesn't get a notification or email. - If a user tries to subscribe to or create alerts for a dashboard, the email obfuscates the charts and cohorts they can't access. ## Manage classifications with the Taxonomy API The [Taxonomy API](https://amplitude.com/docs/apis/analytics/taxonomy) lets you manage classifications for all your properties at scale. ================================================================================ # Event and property descriptions URL: https://amplitude.com/docs/data/event-property-descriptions ================================================================================ # Event and property descriptions You can add or edit the description for an event or property to help other members of your organization understand what an event or property represents. > **Note:** > > This only applies to active events and properties included in your tracking plan. It also doesn't apply to custom events. ## Add a description to an event To add a description to an event, follow these steps: 1. Go to _Events_ and click the name of the event you want to add a description to. 2. In the flyout that appears, click _Add a description_ (under _Details_). 3. Type a description of the event and click _Apply_. ## Add a description to an event property You can change the description for an event property in two ways. Because the same event property can apply to multiple event types, you can add a description for the global event property and for the specific event-to-event property pair. If the event property description specific to an event doesn't exist, the description defaults to the global event property description. - To change the description for an event property specific to an event, navigate to _Events_ and click the event name to open the _Details_ panel. Type a description where it says _Add a description_, and click _Apply_ to save. - To change the global description for an event property, navigate to _Properties > Event Properties_ and click the event property name to open the _Details_ panel. Type a description where it says _Add a description_, and click _Apply_ to save. ## Add a description to a user or group property You can change the description for a user property or a group property by navigating to _Properties > User Properties_ or _Properties > Group Properties_. Click the property name to open the _Details_ panel. Type a description where it says _Add a description_, and click _Apply_ to save. ## AI-generated descriptions On paid plans, Amplitude generates suggested descriptions for events, event properties, and user properties. Suggestions appear in the description area of the details panel. Amplitude doesn't save the suggestion to the description automatically, and any existing description stays visible until you take action on the suggestion. ### Where descriptions come from Amplitude draws from two sources: - **Uploaded files**: Files you upload to a project under _Settings > AI Controls_, such as a data dictionary or a product spec. Amplitude treats these as the most authoritative source and prefers them over everything else. Refer to [file uploads](https://amplitude.com/docs/amplitude-ai/ai-controls#file-uploads) for details. - **Project data**: The project's own Amplitude data, including the event or property name, any existing description, how it's used across the project, and the values it takes. Amplitude only suggests a description it can trace back to one of these sources. An event or property with thin usage and no matching file gets no suggestion, because an empty description is more useful than a vague one. Only files scoped to a project describe that project's events and properties. Organization-level files support other Amplitude AI features but don't feed event or property descriptions. After you upload a file to a project, descriptions for that project refresh within a few minutes. #### Upload a data dictionary For the best results, upload a data dictionary to your project. A data dictionary is a document that lays out the project's taxonomy: its events, the properties on those events, and what each means. Amplitude relies on it more heavily than on anything it can infer from usage data alone, so projects with a data dictionary get noticeably better suggestions than ones without. Amplitude matches files to events and properties by name. A data dictionary row for `Order Placed` describes that event. For properties, type also matters. A row documenting a user property doesn't apply to an event property with the same name. ### Where suggestions appear Suggestions appear in two places: - **In Data**: Go to _Events_ or _Properties_ and select an event or property. The suggestion appears in the _Description_ field in the details panel. Suggestions never appear in the _Events_ or _Properties_ tables, only in the details panel. - **In chart dropdowns**: When you pick an event or property for a chart, the suggestion appears in the details panel next to the list. Some dropdowns are read-only. In those cases, accept or decline the suggestion from Data. ### Identify a suggestion A suggestion looks different from a manually written description: - Suggestions have a dotted underline. A description someone wrote doesn't. - Hovering over the underlined text opens a tooltip naming the source: the uploaded file it came from (all files, if more than one contributed), or "Amplitude charts, dashboards, and product metadata" when it came from the project's Amplitude data alone. - The appearance depends on what's already in the description field. With no existing description, the suggested text appears on its own. When the existing description is incomplete, Amplitude suggests text that fills the gap and keeps the original, adding the new part as a second paragraph. When Amplitude suggests a full replacement, it strikes through the current text and shows the replacement after it. ### Act on a suggestion To review a suggestion: 1. Select the suggestion to open an editor holding the suggested text. 2. Do one of the following: - Select **Apply** to accept the text as-is. - Edit the text, then select **Apply** to accept a modified version. - Select **Revert** to decline the suggestion and keep the original description. - Select **Cancel** to leave everything as-is for now. Once you accept or decline a suggestion, it doesn't come back. Amplitude already uses the suggested text for search and other AI features before anyone reviews it, so accepting confirms it rather than turns it on. Amplitude doesn't generate suggestions for events and properties it defines itself, for custom events, or for transformations. If an event property has an override on a specific event, Amplitude only suggests a description when that override has no description yet. Accepting writes the override, not the shared property description. ================================================================================ # Event and property display names URL: https://amplitude.com/docs/data/display-names-in-amplitude-data ================================================================================ # Event and property display names By default, an event's display name in Amplitude data matches the ingested name. These names can be difficult to read, understand, and incorporate directly into your analyses. To address this, you can give your events and user properties new display names that offer an easy-to-read description of their purpose and content. > **Note:** > > This only applies to active events and user properties added to your tracking plan, and doesn't apply to custom events. It changes the display name of the event or property within the Amplitude UI and doesn't change the raw data. ## Change the display name for an event You can update an event type's display name directly from the _Events_ screen. To do so, follow these steps: 1. Click _Events_ in Amplitude Data’s left-hand rail. 2. Click the event name. 3. Type the new display name for the event. ## Change the display name for a user property You can update a user property's display name from the _User Properties_ tab on the _Properties_ screen. To do so, follow these steps: 1. Click _Properties_ in Amplitude Data’s left-hand rail and open the _User Properties_ tab. 2. Click the property name to open the details panel. 3. Click the property name in the panel and enter a display name. ## Update an event's visibility Hide events from appearing in areas of Amplitude where you don't want them. For example, you can hide noisy events from your user stream to make the data that appears more useful. Support for updating an event's visibility depends on the event type. | Event type | Editable? | Where to edit | | --- | --- | --- | | Default events | Must be in the tracking plan, and have `Modify` enabled. | Table menu, table row, side panel. | | Transformed events | Yes. Hiding from event streams isn't supported. | Side panel | | Live events | Yes | Table menu, table row, side panel. | | Planned events | No | | | Unexpected events | No | | | Blocked events | Yes | Table menu, table row, side panel. | | Deleted events | No | | To update an event's visibility: 1. Navigate to _Data > Events_. 2. Select the events you want to update. 3. In the menu that appears at the top of the table, click **Edit visibility** and select the areas where you don't want the selected events to appear. ================================================================================ # Event categorization URL: https://amplitude.com/docs/data/change-event-category ================================================================================ # Event categorization You can update an event type's category directly from the _Events_, _Custom Events_, or _Labeled Events_ tab. To do so, follow these steps: 1. Go to the _Events_ page and select the _Events_, _Custom Events_, or _Labeled Events_ tab. 2. Click the checkbox next to the event name. 3. From the _Categorize_ drop-down, select the category to which this event belongs. > **Note:** > > For events within _Events_, this only applies to **active** events **included in your tracking plan**. You can also change the event's category from the _Category_ column in the _Events_, _Custom Events_, or _Labeled Events_ tables, or from inside its right-hand fly-out panel. From a table, change the status from the _Category_ column's drop-down menu. Click the event name to open its _Details_ panel, then navigate to _Category_ and select the new category from the drop-down menu. ================================================================================ # Set an event's activity status URL: https://amplitude.com/docs/data/change-event-activity-status ================================================================================ # Set an event's activity status Setting an event's activity status to **active** or **inactive** tells Amplitude whether to count that event in metrics that track active users and active events. An active event is one the user actively engaged with, like clicking the Add to Cart button. An **inactive** event is one that happened to the user without any specific action on their part. Good examples include events like `Push Notification Sent` or `Message Received`. Setting an event as inactive removes that event from any dashboard metrics counting active users and active events. Users who only trigger inactive events **don't count** as active users for that day, though they **do** count towards Amplitude's new user definitions. > **Note:** > > When you change an event's activity status from active to inactive, Amplitude applies that change **immediately and retroactively**, so expect to see changes in your historical data. Inactive events still count against your event volume. To change the activity status, follow these steps: 1. Click the checkbox next to the event name. You can select more than one event to change the status of multiple events at once. 2. Click the _Edit Activity_ drop-down menu. 3. Select the new event status. > **Note:** > > This only applies to **active** events and event properties **included in your tracking plan**. It also **doesn't** apply to custom events. You can also update the Activity status from the _Activity_ column in the _Events_ table, or the _Details_ flyout of a specific event. From the _Events_ table, change the status from the _Activity_ column's drop-down menu. Click an event's name to access the _Details_ flyout, and change the _Activity_ status from the drop-down menu. ================================================================================ # Property types URL: https://amplitude.com/docs/data/update-property-data-type ================================================================================ # Property types To change an event or user property's data type, for example from a string to a Boolean, open the property's details panel and select a new type from the _Type_ drop-down. Amplitude type-checks property values against the specified type and detects when event data doesn't match it, so update the type as your data and analysis needs change over time. To edit the data type of a user property, follow these steps: 1. Click the property's name to open the details panel. 2. Select the property's new data type from the _Type_ drop-down. Options include: - `String`: A string value. - `Number`: Numerical values (like 12345). - `Boolean`: Values representing Boolean states ("true" / "false", "yes" / "no", "0" / "1"). - `Array`: A collection of values stored in a single property (for example, \["apple", "banana", "strawberry"\] or \[1, 2, 3\]). - `Enum`: One of a set of possible values (for example, property fruit is one of \[apple, banana, strawberry\]). - `Const`: A constant value. - `Any`: Any value. ================================================================================ # Override a property definition URL: https://amplitude.com/docs/data/override-property ================================================================================ # Override a property definition Overriding property details is helpful when you want to customize the property for a specific event or property group, without updating the original version or creating an entirely new event property. Each property in the properties table represents the original version, which can be shared across multiple events and property groups. Amplitude Data applies changes to the details of any property to all events and property groups that share the original details. When you override a property on an event or property group, any changes to that property apply only to that event or property group. ## Override a property To override a property on a specific event, follow these steps: 1. Navigate to the _Events_ table and click an event's name. 2. In the event details panel that opens, navigate to _Details > Properties_. Then click the property you want to override. 3. In the event property details panel that opens, click **Override**. A message confirms that any changes to the property apply only to that event. To override a property on a property group, follow these steps: 1. From within _Properties_, open the _Event Properties_ tab to view the event properties table. 2. Click **Property Groups** to switch to the property groups table view. Then click a property group name. 3. In the property details panel that opens, navigate to _Details > Properties_, and click the property you want to override. 4. In the event property details panel that opens, click **Override**. > **Note:** > > Any changes to a property that's overridden on a property group apply to all events that use that property group. You can always [revert an overridden property](https://amplitude.com/docs/data/override-property) when you no longer need the override. ================================================================================ # Revert an overridden property definition URL: https://amplitude.com/docs/data/revert-overridden-property ================================================================================ # Revert an overridden property definition Reverting an [overridden property](https://amplitude.com/docs/data/override-property) to its original version is a quick way to retroactively clean up your tracking plan and maintain consistency across your event properties. Doing so tells Amplitude Data to update the property to match the latest state of the original version listed in the event properties table. After reverting, any changes to the property also apply to any events or property groups that use the original version of that property. ## Revert an overridden property To revert an overridden property on a specific event, follow these steps: 1. Navigate to the _Events_ table and click an event's name. 2. In the event details fly-out, navigate to _Details > Properties_ and click the event property you want to revert. 3. In the event property details panel that opens, click **Manage Override**. 4. From the dropdown menu that opens, select **Revert To Original**. > **Note:** > > Event rows that include "via property group…" appear in the list because those events use a property group that includes this event property. Reverting the property on any one of those events reverts the property on all of them. To revert an event property on a property group, follow these steps: 1. From within _Properties_, open the _Event Properties_ tab to open the event properties table. 2. Click **Property Groups** to switch to the property groups table. Then click a property group name. 3. In the property group details panel, navigate to _Details > Properties_ and click the property you want to revert. 4. In the event property details panel, click **Manage Override**. 5. From the dropdown menu that opens, select **Revert To Original**. > **Note:** > > To see how the details change after a revert before starting the process, click **Compare To Original**. The original values appear under any overridden values. Turn off this view by clicking _Manage Override > Hide Comparison_. To review and revert any overrides for a specific property, follow these steps: 1. From within _Properties_, open the _Event Properties_ tab to open the event properties table, and then click a property name. 2. In the event property details panel, open the _Used By_ tab. Any events or property groups labeled as overridden use an overridden version of that event property. 3. Hover over the overridden event or property group row you're interested in and click the three-dot icon on the right. 4. From the dropdown, select **Revert To Original**. You can bulk revert all overrides from the _Used By_ tab. Click **Manage**, and a modal opens that lets you review and bulk revert your overrides. ================================================================================ # Using property groups URL: https://amplitude.com/docs/data/property-updates-property-groups ================================================================================ # Using property groups A property group bundles a set of event properties into one reusable unit, so you can add all of them to an event in a single step instead of adding each property individually. When you update the group, Amplitude Data applies the change to every event that uses it, which keeps complex tracking plans consistent without manual edits to each event. Use property groups when you want to add the same set of properties to many events without repeating the setup on each one. To track properties about a business entity, like an account, rather than an event, use group properties instead, a distinct feature under _Data > Groups_. For example, a music app's tracking manager might need a way to streamline creation of events relating to songs. Each of these events includes the following properties: - `albumName` - `artistName` - `genre` - `recordLabel` - `releaseDate` - `songDuration` - `songTitle` Instead of individually adding properties to every one of these events, the tracking plan manager can add these properties to their own property group. Whenever they create a new song-related event that includes these properties, they only have to add the entire group to the event. Another benefit is that whenever they edit or update a property (but not a property value), that edit carries over to all events that include the group to which the property belongs. For example, imagine the tracking manager wants to change the `recordLabel` property from a text string to a numeric code to align with a standardized database of record labels. As soon as they make the change in Amplitude Data, that property updates for every event that uses the `Songs` property group. Using property groups also makes sure you use the same iteration of a property with your events. In Amplitude Data, you can have multiple iterations of a property, which can sometimes be confusing when adding properties to events. ## Create a property group To create a property group, follow these steps: 1. Navigate to _Properties > Event Properties_ and click **Property Groups**. 2. Click **+ Create property group**. 3. In the flyout window, enter a name for the group. Then add a description and any tags, if needed. 4. Click **+ Add property** to begin adding properties to this property group. 5. Select an event property from the dropdown menu. You can either scroll until you find it, or you can begin typing its name in the search box until it appears. 6. Repeat the previous step until you've added all the properties you want to include in the property group. Amplitude saves your progress automatically. ## Add a property group to an event To add a property group to an event, follow these steps: 1. In _Events_, click the name of the event you want from the list. The event's flyout window opens. 2. In the _Details_ tab, find the _Properties_ section and click **+ Add property**. 3. In the dropdown list that appears, any existing property groups appear first. Find the one you want and click it. If any property in the group already exists as a direct property on the event, Amplitude Data shows a confirmation dialog listing the affected properties and events. Confirm to remove the direct mappings and serve those properties through the group instead. The properties stay live on all affected events. This is a reorganization, not a deletion. To modify the properties for a property group, follow these steps: 1. Navigate to _Properties_ and click **Property Groups**. 2. Scroll until you find the group you want to modify and click it. Its flyout window appears. 3. Make your changes. The changes apply across all events or sources. If you add a property to the group that already exists as a direct property on an event that uses this group, Amplitude Data shows a confirmation dialog listing the affected events. Confirm to remove the direct mapping and serve the property through the group instead. > **Note:** > > This only applies to active events and event properties included in your tracking plan. It also doesn't apply to custom events. ================================================================================ # Cross-project analysis with Portfolios URL: https://amplitude.com/docs/data/cross-project-analysis ================================================================================ # Cross-project analysis with Portfolios Amplitude Data's portfolio feature lets you create cross-product analyses by combining multiple source projects into a single view. With this feature, you can create portfolios in Analytics and build charts using data aggregated across all the source projects in your portfolio. To learn more, refer to [Portfolio: Conduct cross-project analysis in Amplitude](https://amplitude.com/docs/admin/account-management/portfolio). Portfolios managed in Amplitude Data behave differently from legacy portfolios managed in the Govern section of Amplitude Analytics. Legacy portfolios didn't let users rank source projects, or show event or property metadata from the source projects in the portfolio by default. This article covers portfolios editable only from within Amplitude Data. Portfolios you manage in Analytics or Data return the same aggregated data when queried through charts. > **Note:** Portfolio project limits > > Portfolios support up to five projects. If your use case requires more, contact your account team to unlock up to 10 projects in a portfolio. ## Create a portfolio To create a portfolio in Amplitude Data, follow these steps: 1. From the project selector in Amplitude Data, select _+Create new Portfolio_. 2. In the modal that appears, name your portfolio and select the projects to include. When you're done, select _Next_. 3. Next, rank the schemas of the source projects you included. Ranking handles instances where Amplitude Data encounters conflicts or differences in the schemas. The order in which you rank them determines which schemas Amplitude Data regards as the source of truth. If an event or property name exists in multiple source projects, Amplitude Data uses and displays the metadata from the prioritized project in this portfolio. To rank the schemas, drag the project names into your preferred prioritization order. > **Note:** > > The metadata for an event or property from the source project (description, category, display name, activity, visibility) is in the Data-managed portfolio by default. 4. Select _Create Portfolio_ to finish the creation process. Customize events and property metadata in the portfolio. You can customize event and property metadata in your portfolio by using an [override](https://amplitude.com/docs/data/override-property). ## Import existing portfolios into Amplitude Data You can import existing Analytics-managed portfolios into Amplitude Data. To do so, select the project selector and find the portfolio you want to import, either by searching for it or locating it under "Projects (managed in Analytics)". After Amplitude imports your portfolio, you can view the existing aggregated list of events and properties. > **Note:** > > Amplitude Data creates overrides in the imported portfolio for all events and properties. This approach maintains the existing schema for users of the Analytics-managed portfolio. ================================================================================ # Data Assistant Overview URL: https://amplitude.com/docs/data/use-ai-data-assistant ================================================================================ # Data Assistant Overview A clean, organized tracking plan helps you get the most value from Amplitude Data. When you have hundreds or thousands of events and properties, maintaining the plan can be difficult, especially when identifying what to fix in messy data. Amplitude's AI Data Assistant helps you maintain your tracking plan by showing a short list of suggested modifications whenever you visit the Data home page. Amplitude's internal AI generates these suggestions automatically. Any changes you apply through Data Assistant post directly to your tracking plan, with no other action required. ## Update your tracking plan with Data Assistant To update your tracking plan using Data Assistant, follow these steps: 1. Open Amplitude Data. Data Assistant appears at the top of the home page, displaying a list of top suggestions. Data Assistant prioritizes suggestions based on their expected impact on your overall data health, surfacing the most critical issues first. For example: - If your project is close to the limit on the number of event types, a suggestion to clean up events surfaces as a critical issue, since exceeding the limit can make new event types unqueryable. - If high-volume events get heavy query traffic but have unclear names or meanings, Data Assistant may propose descriptions that help users and AI understand those events better. 2. Click a suggestion to expand it. The suggestion expands directly below, where you can see the proposed changes in detail. The action label describes the suggestion type, such as **Review deletions** or **Review descriptions**. 3. In the expanded suggestion, you can: - Modify the proposed action before applying it, such as editing the proposed description or category. - Click **Approve** to accept the suggestion and apply the change to your tracking plan. - Click **X** to dismiss the suggestion. Dismissals apply for 90 days to everyone in the organization. 4. To take action on multiple items at once, use the bulk action controls at the bottom of the expanded suggestion. For more detail on why Data Assistant made a specific suggestion, hover over the Info icon. ## Detect semantically similar events Data Assistant detects events that are semantically similar, such as `Order Placed` and `Completed Purchase`, which people and AI find hard to tell apart. When it finds these events, it suggests one of two fixes: merge the events with a transformation, or draft descriptions that clarify how each event differs from the other. For Amplitude's AI-generated descriptions feature, which suggests descriptions for individual events and properties in the details panel, refer to [AI-generated descriptions](https://amplitude.com/docs/data/event-property-descriptions#ai-generated-descriptions). ## Use Data Assistant interactively Beyond the suggestions panel on the Data home page, you can work with Data Assistant interactively through Global Chat or by creating an Agent in the _Agents_ section. In a single conversation, you can ask your own questions, run custom audits, and act on the results. You can apply bulk actions to as many as 1,000 items at once, and you can dismiss any suggestions you don't want to act on. ## Automated tasks in Data Assistant Data Assistant provides automated tasks to help you clean up your data. Automated tasks let data governors define conditions and actions that the system performs automatically. Automated tasks automate repetitive clean-up workflows by turning Data Assistant recommendations into automatic actions. For more information, go to [Automated Tasks](https://amplitude.com/docs/data/automated-tasks-in-data-assistant). > **Note:** > > Data Assistant is one of several AI tools in Amplitude. For analytics insights, chart creation, and natural-language data exploration, refer to [Global Agent](https://amplitude.com/docs/amplitude-ai/global-agent-overview). For automated dashboard analysis and session replay insights, refer to [AI Agents](https://amplitude.com/docs/amplitude-ai/setup-and-onboarding). ================================================================================ # Automated Tasks URL: https://amplitude.com/docs/data/automated-tasks-in-data-assistant ================================================================================ # Automated Tasks Automated Tasks are part of Amplitude's [Data Assistant](https://amplitude.com/docs/data/use-ai-data-assistant) feature. Automated tasks let data governors define conditions and actions that Amplitude then performs automatically. Automated tasks turn Data Assistant recommendations into automatic actions and streamline repetitive clean-up workflows. For example, an automated task can delete events that have gone unused for 90 days. After you create an automated task, it runs daily. > **Note:** > > Automated tasks are only available to users with manager or admin permissions. Contact your administrator if you can't access Automated tasks as an option for Data Assistant. Access your automated tasks from the Data Assistant by going to _Data > Assistant > Automated Tasks_. If you have active automations, Amplitude displays them with a current count of the affected events. If you don't have any active automations, you can create one. By default, automated tasks operate across all projects within a workspace. You can specify for the automation to only search through a single project. ## Types of automated tasks You can select any of the following types of tasks to automate: - Clean up stale events. - Clean up single-day events. - Clean up unused events. Cleanup extends beyond events. Data Assistant also cleans up broken or no-longer-useful event, user, and group properties, so you can keep your entire tracking plan tidy, not just its events. When Data Assistant identifies cleanup candidates, you choose how to act on them. You can schedule them for deletion, which starts the 30-day notice period that the following sections describe, or you can delete them immediately. ### Clean up stale events This task removes events that haven't had any recent volume. Low volume indicates that Amplitude isn't ingesting the events and they're no longer of value. The task inspects your organization for events that have a `last seen` date within a configurable number of days. For example, events that haven't been ingested in 90 days. When the automated task finds events that match those criteria, it schedules them for deletion. Amplitude notifies all people using those events through email or Slack about the impending deletion. Anywhere the events appear (for example, in a chart), a banner notifies users about the upcoming deletion. If anyone wants to keep the event, they can do so through the email or banner notification. If no one elects to keep the event within 30 days, Amplitude deletes the event. The 30-day timeframe to delete events isn't configurable. Deleted events no longer appear in the event drop-down menu, and Amplitude blocks them from future ingestion. Historical charts and data aren't affected. ### Clean up single-day events This task removes accidental or one-time test events that can negatively affect or clutter your taxonomy. The task inspects your organization for events that: - Have the same first seen and last seen dates. - Have that date more than a configurable number of days before the inspection date. For example, 90 days before the inspection date. When the automated task finds events that match those criteria, it schedules those events for deletion. Amplitude notifies all people using those events through email or Slack about the impending deletion. Anywhere the events appear (for example, in a chart), a banner notifies users about the upcoming deletion. If anyone wants to keep the event, they can do so through the email or banner notification. If no one elects to keep the event within 30 days, Amplitude deletes the event. The 30-day timeframe to delete events isn't configurable. Deleted events no longer appear in the event drop-down menu, and Amplitude blocks them from future ingestion. Historical charts and data aren't affected. ### Clean up unused events > **Tip:** Manually enabled > > The Clean up unused events automated task can affect events that you want to keep. The task must be manually enabled for each account. Reach out to your Amplitude representative or [Amplitude Support](https://gethelp.amplitude.com/hc/en-us/requests/new) for more information or to get this task enabled. This task optimizes your event volume by making sure that all your ingested events are actively used. The task inspects your organization for events that haven't been queried in 90 days. When it finds those events, it can notify you about them, schedule those events for deletion within 30 days, and notify you when Amplitude deletes them. Your users can save events through the notification from the automated task or through the Data Assistant. Amplitude doesn't delete saved events, even if no one queries them during the time window. If the task deletes an event, the deletion also blocks future ingestion of that event. Any data that Amplitude doesn't collect because of an event's deleted status isn't recoverable. Historical charts and data aren't affected. The deleted event still appears in them. You can manually recover a deleted event at any time. ## Set up an automated task You can manually set up an automated task. Alternately, the [Data Assistant](https://amplitude.com/docs/data/use-ai-data-assistant) can proactively identify tasks for you. ##### To manually set up an automated task 1. Go to _Data > Assistant > Automated Tasks tab_. 2. Click **Get Started**. 3. Complete the set up prompts. This includes: - Setting the threshold (in days). By default, the threshold is 30 days for single-day events and 90 days for stale events. - Specifying any event tags that the automation rule should ignore. For example, if you never want to remove creation events, add a `create` tag to the ignore field. Review your events to make sure you specify the exact tag applied to your event. 4. Click **Set Up Automation**. ##### To set up an automated task through the Data Assistant If Amplitude detects events that meet a task's criteria, those suggested tasks appear in the Suggestions view under _Data > Assistant_. If automation is available for that task, a banner appears above the suggestion. Click the banner to turn on automation for future matching events. Amplitude takes you to the window to complete the task set up. ## Remove an automation You can remove any current automation. When removing an automation, you can specify whether you want to affect any pending changes or to only affect future changes. ##### To remove an automated task 1. Go to _Data > Assistant > Automated Tasks_. 2. Click **View Automation**. 3. In the automated task window, click the **three-dot** option menu. 4. Click **Remove Automation**. 5. Confirm whether you want to also remove any pending changes from the task, then click **Remove**. ## Recover deleted events You can recover any deleted event at any time. ##### To recover a deleted event 1. Go to _Data > Events_. 2. Click **Deleted Events**. 3. Select the event you want and click **Restore**. ================================================================================ # Remove invalid or incorrect data URL: https://amplitude.com/docs/data/remove-invalid-data ================================================================================ # Remove invalid or incorrect data To remove invalid or incorrect data from your Amplitude analyses, use one of four Amplitude Data methods: create a drop filter, create a block filter, block events and properties, or delete events and properties. Drop filters hide events from queries and stay reversible. Block filters and blocking stop Amplitude from ingesting matching data going forward. Deleting removes an event or property from your plan but keeps historical data. Data is immutable after ingestion, so none of these methods change data that Amplitude already stored. To permanently delete data, use [Amplitude's self-service data deletion feature](https://amplitude.com/docs/admin/account-management/self-service-data-deletion-in-amplitude). ## Create a drop filter You may find you've loaded incorrect data and want to filter it out from queries. Amplitude Data's drop filters feature lets you remove specific event data from your charts at query time. Amplitude doesn't delete these events, and you can restore them to your charts by editing or deleting the drop filter. Drop filters don't apply to data exports. > **Note:** > > As query-side filters that aren't applied during data ingestion, drop filters don't affect your event volume limit. To create a drop filter, follow these steps: 1. Make sure you're on `main`, as filters aren't accessible from any other branch. 2. In the left-hand sidebar, click **Filters**, then select the _Drop Filters_ tab. 3. Click **+ Create Drop Filter** to open the Filter Configuration fly-out panel. 4. Click **Select event ...** to choose the event you want to filter on. 5. Optionally, click **+ where** to include any relevant properties that refine your filter. For example, perhaps you want to filter out all purchase events that come from a specific geographical location. Select that location from the list of properties and set the evaluation to `is not equal`. 6. Specify the time range for the events you want Amplitude Data to drop-filter out. 7. When you're ready, click **Drop Data** to initiate the drop filter. To edit or delete a drop filter, click its name in the drop filter list. In the fly-out panel that appears on the right, make your edits and click **Update Drop Filter**. > **Note:** Drop filter details > > Note the following about drop filters: > > - Drop filters don't affect event streams. > - You must use the same operator across all selected properties. > - You can mix and match event and user properties. > - You can have a maximum of three properties. > - You can't use any property more than once. ## Create a block filter Block filters let you stop data ingestion for events and properties that you specify based on criteria you define. Blocking Amplitude from ingesting data can help when you need to act quickly before you update your code. Block filters let you: - Block events based on an event property or Amplitude property. For example, events from a specific data source. - Block events from a specific IP address or set of IP addresses. Use this to block traffic from a test server or bad actor. - Block events from a specific version of your application to help find and fix instrumentation issues. - Block event or user properties that start with a particular string, or properties with numeric names to help uncover instrumentation issues. - Block bot traffic from websites. When you add or remove a block filter, allow up to 10 minutes for the change to take effect. As soon as the filter is active, it blocks Amplitude from ingesting matching data. > **Warning:** > > Amplitude doesn't collect data for blocked events or properties. As a result, you can't recover information about blocked data at a later time, because Amplitude never ingests it. If you think you may need data at some point in the future, consider hiding the event or property instead. To create a block filter: 1. Make sure you're on your project's `main` branch in Data. 2. Click **Filters** in the side navigation. 3. Click **+ Create Block Filter**. 4. Specify the project and data type (Events, Event properties, User properties, or Bot traffic). If applicable, use the available filtering parameters. 5. Click **Block Data** to initiate the block filter. ### Block events based on property values Block events based on the value of up to three event properties. When you block events based on property values, Amplitude compares your filter against the raw stringified values sent to Amplitude. Knowing the data type is important in the following scenarios: - Boolean values: If you send a property as `true` or `false`, Amplitude displays the value as "True" or "False". To use this in a Block filter, specify the exact value sent as a string. In this case, `true` or `false`. - Array values: Amplitude splits arrays into separate values for querying. Block filters compare against the stringified raw value. To find raw property values, use the [Event Explorer](https://amplitude.com/docs/analytics/charts/event-explorer) to view an example of the event you want to block. ### Block events and properties from your plan Create Block filters from your Events or Properties list. 1. Make sure you're on your project's `main` branch. 2. In Data, navigate to the Events or Properties tab. 3. Select the Events or Properties you want to block. 4. After selecting, click **Block** to create the filter, and confirm the block. 5. To unblock a blocked event, repeat the previous steps and click **Unblock**. > **Note:** > > Custom events are a virtual grouping of your ingested events and aren't blockable. Instead, block the individual events that make up the custom event. ## Block events and properties You can prevent Amplitude Data from ingesting data on a specific event, event property, or user property by blocking it. Amplitude Data immediately stops processing data for that event or property until you decide to unblock it. > **Warning:** > > Because Amplitude Data doesn't ingest any data for blocked events or properties, you can't recover any information about them at any future date. If you don't want to display a specific event or property but think you may someday need this data, consider hiding the event or property instead. To block an event or property, follow these steps: 1. Make sure you're in the `main` branch. You can only block events and properties from there. 2. Navigate to _Events_ or _Properties_, depending on which one you want to block. 3. Find the event or property you want to block and click the checkbox next to its name. 4. If blocking an event, click the **Block** dropdown menu, and choose either **Block now** or **Schedule for blocking**. If blocking a property, click **Block**. 5. A confirmation modal appears. If you still want to block the event or property, click **Block**. 6. To unblock a blocked event, follow steps 1-5 and click **Unblock** instead of **Block**. > **Note:** > > You can't block custom events. ## Delete events and properties in Amplitude Data If you ingest events or properties that you no longer need, you can delete them from your plan. When you delete an event or property, Amplitude blocks it from future ingestion and removes it from chart dropdowns to prevent future querying. The event or property doesn't count toward your monthly event volume or instrumentation limit. Deleting an event or property doesn't remove historical data. Charts that reference a deleted event load with data from before you deleted the event and indicate the event is deleted. Deleted user properties still appear on events that are already ingested, and you can still see them in historical user stream data. To delete an event or property: 1. Navigate to the Events or Properties section of Amplitude Data. 2. Find the events or event properties you want to delete and click the checkboxes next to their names. 3. Click **Delete**. 4. Complete the verification modal. You can undelete a deleted event or property. 1. From the status filter dropdown, select **Deleted** to find your deleted events or properties. 2. Find the items you want to restore and click the checkboxes next to their names. 3. Click **Restore**. ## Delete an entire user To delete a user entirely, use the [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy). This API lets you delete a user, their events, and any associated data, and helps you keep compliant with data laws and regulations. ================================================================================ # Block bot web traffic URL: https://amplitude.com/docs/data/block-bot-traffic ================================================================================ # Block bot web traffic To block bot traffic in Amplitude, create a **block filter** for bot traffic. Amplitude then stops ingesting events from crawlers, scrapers, and similar tools, which matters if you track events on public, unauthenticated websites where bot traffic can skew your metrics. ## How bot blocking works Amplitude blocks bot traffic based on User-Agent, as identified by the [IAB/ABC International Spiders and Bots List](https://www.iab.com/guidelines/iab-abc-international-spiders-bots-list/). Blocking applies by default to data sent through the [legacy JavaScript SDK](https://github.com/amplitude/Amplitude-JavaScript) or the [TypeScript Browser SDK](https://github.com/amplitude/Amplitude-TypeScript/tree/main/packages/analytics-browser) (version 1.10.0 and later). You can also provide the `user_agent` field directly on events sent through the HTTP API or Batch API. Be careful when doing this, because the value **must represent a valid browser** or Amplitude drops the event. You can't recover data that a block filter removes, because Amplitude never ingests it. ## Create a block filter for bot web traffic To create a block filter for bot web traffic, follow these steps: 1. Make sure you're on `main`. Filters aren't accessible from any other branch. 2. In the left-hand sidebar, click **Filters**, then select the **Block Filters** tab. 3. Click **+ Create Block Filter** to open the Filter Configuration fly-out panel. 4. Select **Bot Traffic** from the **Block** drop-down. 5. When you're ready, click **Block Data** to start the block filter. ================================================================================ # Change the description of an event or property URL: https://amplitude.com/docs/data/change-event-description ================================================================================ # Change the description of an event or property You can change the description for an **event** to help other members of your organization understand what an event represents. To do so, follow these steps: 1. Click the event name to open the fly-out panel on the right side. 2. Click the _Description_ field. 3. Type in a description of the event. You can change the description for an **event property** in two different ways. Because the same event property can apply to multiple event types, you can either add a description for the **original** event property, or for an event property overridden for a specific event or property group. If no override exists, the description defaults to the global event property. > **Note:** > > Event properties that aren't overridden share the same **original** event property details. To change the description for an overridden event property **specific to an event**, follow these steps: 1. Navigate to the _Events_ table and click the event name. 2. In the event details panel that opens, navigate to _Details > Properties_, then click the property you want to update. 3. Make sure the event property is overridden. If it is, _Manage Override_ appears in the blue box within the details panel, and you can skip to step 4. Otherwise, click _Override_ to apply the change only to a specific event or property group. 4. Click the field directly below the property name and type in a description of the property. To change the **original** description for an event property, follow these steps: 1. Navigate to _Event Properties_ and click the property you want to update. 2. In the event property details panel that opens, click the field and type in a description of the property. On paid plans, Amplitude can also suggest descriptions automatically. Refer to [AI-generated descriptions](https://amplitude.com/docs/data/event-property-descriptions#ai-generated-descriptions) for details. ================================================================================ # Fix your data with transformations URL: https://amplitude.com/docs/data/transformations ================================================================================ # Fix your data with transformations Transformations rewrite event data at query time to correct instrumentation mistakes without touching your code. They apply retroactively across all historical data, so a single rule fixes affected events both before and after you create it. Common fixes include merging duplicate events, consolidating property names, renaming property values, and hiding values from the UI. Use a transformation when you need to fix data retroactively across historical and future events without redeploying instrumentation. Use a custom event instead when you want to group existing events into a new analytical event while keeping the originals queryable. You can only create transformations on a project's `main` branch with the **Show transformations** toggle set to `ON`, and you can't transform Amplitude's default user properties. > **Note:** > > Transformations occur at query time when a chart or cohort generates results. This doesn't affect the raw data. Transformations don't affect raw data on Snowflake or Redshift. ## Merge events, event properties, and user properties Many Amplitude users need to merge superfluous or duplicate events, event properties, or user properties. Transformations make this process easy. ### Merge events This transformation lets you merge events together. Use it if you're tracking two or more events that you want to track as one single event instead. For example, you can merge the events `comment_reply_like` and `comment_share` into a single event, `comment`. When merging events, you can also add a property that helps distinguish between the two original events after you merge them. This transformation can help if you're logging data into two events with similar syntax when you could log this information as one event with different property values instead. For example, you could transform the events `comment_reply_like` and `comment_share` into one event, `comment`. The event `comment` then has a new event property `comment type` with values `reply like` and `share`. To merge events, follow these steps: 1. In Amplitude Data, navigate to _Events_. 2. Find the events you want to merge together and click the checkbox next to their names. 3. After you've selected the events, the _Transform_ option appears in the menu bar above the events list. Click **Transform**. 4. Choose whether you want to merge the events you selected into a single event, or into a single event with an extra distinguishing property. Then click **Next**. 5. Use the dropdown in the _Transform & Merge Events_ modal to tell Amplitude Data whether you want to merge the selected events into a new event, or whether you want to merge them into a different, already existing event. If you're merging into a new event, name it here. Then click **Preview**. 6. In step 5, if you aren't adding the extra distinguishing property to your merged event, skip to step 9. Otherwise, select the event property you want to use as a differentiator from the _Select Property_ dropdown. Then click **Next**. 7. Next, map the events you selected with new values for the property you selected. Enter the new value in the _Property Value…_ field and click **Preview**. 8. Review your changes and click **Merge** to complete the transformation. ### Merge event properties or user properties This transformation lets you merge properties, either for events or for users. Use it if you have two properties that track the same information but use different naming syntax. For example, imagine you call an event property `title` in some cases, and `TITLE` in others, even though they represent the same thing on all events. You can clean things up by transforming `title` and `TITLE` into `Title`, combining the data. Similarly, you might call a user property `name` in some cases and `NAME` in others, even though they represent the same thing for all users. Transforming `name` and `NAME` into `Name` resolves any potential confusion. You can merge event properties only with other event properties, and user properties only with other user properties. To merge event properties or user properties, follow these steps: 1. In Amplitude Data, navigate to _Properties_, then click either the _Event_ or _User_ tab, depending on which type of properties you want to merge. 2. Find the properties you want to merge together and click the checkbox next to their names. After you've selected the event properties, the _Transform_ option appears in the menu. 3. From the _Transform_ dropdown, select **Merge Property**. 4. The _Merge Properties_ modal appears. Type a new event property name or type the name of the event property you want to merge the selected event properties into. Click **Next**. 5. Review your changes and click **Merge** to complete the transformation. ## Rename property values This transformation lets you reassign event and user property values. Use this transformation if a property has misspellings or nonsensical values in dropdowns. It lets you hide them from the UI or turn them into another value. For example, you can reassign the values of `true` and `TRUE` to `True`. To rename a property value, follow these steps: 1. Navigate to _Properties_ and open either the _Event_ or _User_ tab, depending on the type of property you want to rename. 2. Find the property with the property value you want to rename and click the checkbox next to its name. 3. From the _Transform_ dropdown, select **Rename Value**. 4. The _Edit Renamed Values_ modal appears. Under _Current Property Value_, click **Select value(s)...**. 5. From the list, select the value you want to rename and click **Apply**. 6. Under _Derived Value_, click **Select value...** to set a new value. 7. Click **New Value** and enter the new value in the field that appears. 8. Repeat steps 4 through 7 for every value you want to rename. Then click **Next**. 9. A confirmation modal appears. Click **Rename**. ## Hide property values Setting a property value's visibility status to hidden is helpful for values you want to track but don't want to appear on the dashboard in any charts. Hiding a property value doesn't delete its raw data, and the value is still visible in the user's individual event stream. To hide a property value, follow these steps: 1. Find the event or user property with the value you want to hide. Check the box next to its name. 2. From the _Transform_ dropdown, select **Hide Values**. 3. Select the value or values you want to hide from Amplitude and click **Next**. 4. A confirmation modal appears. Click **Hide**. ## Edit and delete transformations Transformations aren't permanent. You can reverse them, and you can edit or delete them at any time. To edit your transformation, follow these steps: 1. Find the transformed event, event property, or user property you're interested in. 2. Click the transformation's name to open the details panel. Click _Transformed Values_ to see the transformations tab. 3. Click **Edit** next to the transformation you want to edit, make the necessary changes, and save. To delete your transformation, follow these steps: 1. Find the transformed event, event property, or user property you're interested in. 2. Click the checkbox next to the transformation you want to delete. 3. Click **Undo Transformation**. 4. A confirmation modal appears. Click **Undo Transformation**. Deleting a transformation doesn't delete the original events. ## Use transformed properties for targeting Amplitude makes transformed user properties available as targeting criteria in Experiment, Feature Flags, and Guides & Surveys. At evaluation time, Amplitude applies your project's transformation configuration before evaluating targeting rules, so the same merge and rename rules that clean up your Analytics data also govern targeting and exposure. You don't need to reimplement transformation logic in your SDK or backend. Define the rules once in Amplitude Data and they apply consistently across Analytics, Experiment, Feature Flags, and Guides & Surveys. For more details, refer to [Remote evaluation](https://amplitude.com/docs/feature-experiment/remote-evaluation#transformed-properties) and [Setup and targeting](https://amplitude.com/docs/guides-and-surveys/setup-and-target#targeting). ## Transformed events and custom events | Topic | Custom Events | Transformed Events and Properties | | --- | --- | --- | | Analysis of individual components | Can perform analysis on the individual events used in the custom event. | Can only perform analysis on the transformed event. | | Use case | Augment and group existing events into new events you can analyze. | Clean up events and fix instrumentation issues. | | Drop and block filters | Not available to block and drop filters. | Transformed entities aren't available to block and drop filters. | | Chart UI limitations | Limited availability in Funnels, but can't group by event name. | Available to most charts. | | User lookup | Shows raw event data only. | Shows raw event data only. | | Event type limit | Don't count toward the event limit. | Don't count toward the event limit. | ## Common questions ### I merged event A and event B together to create event C. What happens to saved charts that were querying on event A? Any saved chart querying on event A continues to do so after the merge. The chart doesn't automatically switch from event A to event C. For charts created after the merge, neither event A nor event B appears in the chart dropdown; only event C appears. ### I merged event A and event B together to create event C. How do I bulk update the existing saved charts to now use event C? You can't bulk update charts in Amplitude. Try adding all charts that still use the old events (in this example, events A and B) to a dashboard. Use **Find & Replace** to swap those events for event C, then click _Save onto Charts > Update existing charts_. ### I merged event property A and event property B together to create event property C. What happens to saved charts that were querying on event property A and event property B? Saved charts don't automatically switch to a different event property after a transformation. Each chart keeps querying the property you saved with it until you edit the chart. After the transformation, chart dropdowns only show the merged or target property. You can't create new charts that still query the old, untransformed property names. How you update existing charts depends on how you merged properties: - **You merged into a new event property C.** Update every saved chart that still queries event property A or B. For example, edit each chart and select event property C in the chart controls. You can also add those charts to a dashboard, use **Find & Replace** to swap the old properties for property C, then click _Save onto Charts > Update existing charts_. - **You merged into an existing event property** (for example, you map both A and B into property A instead of creating a new name). Update any saved chart that still queries a source property you dropped. Charts that already query the target property don't need changes, because they already use the merged property. ### I want to unmerge event C. What happens to the charts that use this merged event? The result depends on how you created event C in the first place. - If you merged event A and event B into event C: after refresh, the chart's user/event totals drop to zero. - If you merged event A and event C into event C: after refresh, the chart queries the source event C. ### Can I create a new transformation from an existing transformation? Amplitude doesn't support transformations on transformations. To request this capability, submit a feature request. ### Event C is a merged event composed of source events A and B. Can I view event A and event B separately, then event C starting at the date of the transformation? Transformations apply retroactively, so that isn't possible. ### Which value takes priority in a property merge? Use this example: for one instance of event A, you send the event property `event prop` = `true`; for another instance of event A, you send the event property `event_property` = `false`. You then merge both event properties into `EVENT_PROPERTY`. When you query on event A and group by `EVENT_PROPERTY`, this user appears twice. You see one data point for the `true` value and one for `false`. ================================================================================ # Custom events URL: https://amplitude.com/docs/data/custom-events ================================================================================ # Custom events A custom event is a saved, reusable event that combines two or more existing events with an `OR` clause, so any of those events counts as the same step in an analysis. For example, a custom event can show users who, after receiving a push notification, either played a song or searched for one as their next step. You can also [combine multiple events in-line](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-in-line-events) through the Events Module, but an in-line event applies only to the chart where you create it. Save it as a custom event when you want to reuse the same combination across other charts. You create a custom event in the _Events_ panel from one or more pre-existing events. Doing so tells Amplitude to combine those pre-existing events and count any user activity for them as activity for the new custom event. This approach helps when you want an easy way to track activity on related or similar events, like whether a visitor has fired either the `view_landing_page_1` or `view_landing_page_2` events. For example, `Play or Search Song` is a custom event consisting of the `Play Song` event, the `Search Song` event, and an `OR` clause to connect the two. Any user who triggers either the `Play Song` event or the `Search Song` event has converted that second step. Another method is conditioning an added event with an [event property or user property](https://amplitude.com/docs/data/user-properties-and-events). This is the primary method for analyzing whether a user performed one of many events. ## Before you begin - Only admins, managers, and members can create custom events. - You can use custom events in Event Segmentation, Funnel Analysis, Retention Analysis, Lifecycle, Stickiness, Impact Analysis, Journeys, Pathfinder, Conversion Driver, Experiment Results, and Compass charts. - You can't query on custom events in Redshift. - All custom events have the prefix `[Custom]` before the event name in your charts. - Editing or renaming custom events used in other charts breaks those charts. Amplitude continues to query the named value until you manually change it on any charts that use it. Amplitude displays a warning when you make any edits to custom events. - Querying event properties on custom events is possible only if the property applies to all events. If you try to create a custom event with five different events and want to see the location values from all those events, you need to instrument the location event property to all the individual events making up the custom event. ## Group two existing events into a single custom event To group two events, follow these steps: 1. In Amplitude Data's left-hand rail, select **Events**. Then select **Create Custom Event**. 2. In the modal that appears, select the events you want to analyze as a single event. You can set different filters on these events, in case the analysis requires a more granular view of the selected events. At this point, you can use this event for further analyses in Amplitude. Select the new event in the _Custom_ category in the appropriate chart drop-down menus. ## Custom events and transformed events | Topic | Custom Events | Transformed Events and Properties | | --- | --- | --- | | Analysis of individual components | Can perform analysis on the individual events used in the custom event. | Can only perform analysis on the transformed event. | | Use case | Augment and group existing events into new events which you can analyze. | Clean up events and fix instrumentation issues. | | Drop and block filters | Not available to block and drop filters. | Transformed entities aren't available to block and drop filters. | | Chart UI limitations | Limited availability in Funnels, but can't group by event name. | Available to most charts. | | User lookup | Shows raw event data only. | Shows raw event data only. | | Event type limit | Don't count toward the event limit. | Don't count toward the event limit. | ================================================================================ # Currency Conversion URL: https://amplitude.com/docs/data/currency-conversion ================================================================================ # Currency Conversion Currency conversion lets you analyze multi-currency revenue data in Amplitude. With currency conversion, you can: - Send Amplitude transaction data with local currency codes. - Use revenue data for insight generation or decision making without manually pre-converting data into a single currency. - Run queries based on a series of lookup tables connected to daily exchange rates to convert transaction amounts based on transaction dates and daily exchange rates. You can use the primary currency set at the project level (for example, convert all global currencies to USD). > **Note:** > > Amplitude performs currency conversion using the exchange rates from the preceding day for consistency in reporting. Amplitude sources exchange rates daily from [ExchangeRate API](https://www.exchangerate-api.com/). You can control where you view currency-converted data throughout Amplitude. You can configure target currencies at the project level through project settings, which means you can use both converted and non-converted values for `$revenue` and `$price` fields. You can also: - Send standard `$revenue` and `$price` fields or map your own custom fields (or cart properties) into the conversion logic. - View original, non-converted values in user timelines. This view aligns with the original data and avoids confusion when comparing information against chart data. ## Enabling conversion To enable currency conversion, send the `$currency` property as a 3-character [ISO 4217](https://www.iban.com/currency-codes) code such as USD or EUR alongside your revenue-related data. ## OOTB derived properties Amplitude provides two OOTB derived properties that let you view currency-converted data. These OOTB derived properties are: - Currency Converted Revenue. - Currency Converted Price. These derived properties apply only to events containing both `$currency` and either `$revenue` or `$price` fields. You can find these properties by going to _Data > Properties > Derived_. They appear as read-only fields, and you can use them for filtering, grouping, and aggregations. ### Currency Converted Revenue Converts the `$revenue` field into the project's target currency using the `$currency` field as the original currency code for the received `$revenue`. ```typescript CURRENCY_CONVERT(PROPERTY("$currency", "event"), PROPERTY("$revenue", "event")) ``` ### Currency Converted Price Converts the `$price` field into the project's target currency using the `$currency` field as the original currency code for the received `$price`. ```typescript CURRENCY_CONVERT(PROPERTY('$currency', 'event'), PROPERTY('$price', 'event')) ``` ## Custom derived properties If you use `$Cart Properties`, or if you don't use `$revenue`, `$price`, or `$currency` fields, you can create custom derived properties to apply currency conversion. Custom derived properties require project-level currency configuration. For example, add a derived property to currency convert the custom `$revenue` or `$currency` field: ```typescript CURRENCY_CONVERT(PROPERTY("_currency_", "event"), PROPERTY("_revenue_", "event")) ``` Then add the derived property to currency convert cart properties: ```typescript CURRENCY_CONVERT(PROPERTY("_currency_", "event"),PROPERTY("products.revenue", "event")) ``` ## Project settings You can configure the target currency for derived property revenue fields in the project settings. ##### To configure currencies 1. Open your project and go to _Organization Setting > Projects > General_. 2. Select the currency you want from the **Which currency should your values be converted to?** dropdown menu. All options are in standard [ISO 4217](https://www.iban.com/currency-codes) 3-digit format. ## Property selectors You can select both OOTB and custom derived properties when [building charts](https://amplitude.com/docs/get-started/create-a-chart). ##### To select currency conversion properties in a chart 1. Go to an existing chart or go to _Create > Chart_ to create a new one. 2. In the Events modal, select **Any Active Event**, then select **Select property**. 3. In the search field, find **Derived Properties**. 4. Select the properties you want. You can select any of: - Currency Converted Revenue. - Currency Converted Price. - Custom derived properties. ## Currency converted revenue in charts When viewing the chart, both the original revenue value and the currency-converted value are available. ================================================================================ # Derived properties URL: https://amplitude.com/docs/data/derived-properties ================================================================================ # Derived properties Derived properties create new event and user properties retroactively from existing ones, using functions and operators. Amplitude computes them dynamically at query time and doesn't change your raw data. Use them to run analyses on values you didn't send in the original event payload. Use a derived property when you need a value computed from existing properties and don't want to re-instrument or re-ingest data. If you need a value sent at event time from the client, use a regular event property instead. If you need a curated, named event built from multiple raw events, use a custom event instead. For example, create a derived property whose value is a boolean based on whether a cart item's price exceeds a threshold. ## Create a derived property You need to be on your project's `main` branch to create a derived property. To create a derived property, follow these steps: 1. In Amplitude Data, go to _Tracking Plan > Properties_ and select the **Derived Properties** tab. 2. Select **Add Derived Property**. 3. Give your derived property a name. 4. Add any relevant metadata to your property, including a description (optional, unless you want to use the Suggest feature) and the visibility of the property in charts within this project. 5. Enter your formula. Review the list of valid functions and operators below. 6. Select **Save**. ## Preview your results As long as the formula you entered is valid, you can test the results in the space below the formula editor. Test by selecting existing values for properties used in the formula, or by entering free-form values. You can test from either the _Create/Edit_ modal or from the side panel for a saved derived property. ## Derived property use cases Using the referrer URL example, you can write a formula using string operators such as: `SPLIT(PROPERTY('referrer_url','event'), "/", 2)` This formula converts a value like "https://www.google.com/search?q=amplitude" into the value "www.google.com." To strip this down further to "google", wrap the result of a SPLIT function inside another SPLIT function. The resulting formula looks like this: `SPLIT(SPLIT(PROPERTY('referrer_url','event'), "/", 2), ".", 1)` Amplitude also supports math operators. For example, if you have events that contain subtotal and tip properties and want to run analyses based on the total amount, use this formula: `SUM(PROPERTY('subtotal','event'), PROPERTY('tip','event'))` To determine whether a particular order receives a discount when the total order size exceeds $50, use this formula: `IF(SUM(PROPERTY('subtotal','event'), PROPERTY('tip','event')) >= 50, 'true')` > **Note:** > > Queries using derived properties might experience longer query times depending on the complexity of the formulas. A limit of up to 10 property references per derived property also applies. ## Functions and operators ### String functions - **`REGEXEXTRACT (text_property, regular_expression)`** - **Description**: Extracts substrings matching the regular expression. - **Example**: `REGEXEXTRACT("shirt-150", "[0-9]+")` - **Result**: `150` - **`REGEXREPLACE (text_property, regular_expression, replacement_text)`** - **Description**: Replaces the property's values with text matching the regular expression with replacement text. - **Example**: `REGEXREPLACE("en-US", "-.*", "")` - **Result**: `en` - **`CONCAT(property1, property2)`** - **Description**: Concatenates a property with another property or text value. - **Example**: `CONCAT("firstName", "lastName")` - **Result**: `firstName lastName` - **`LOWERCASE (text_property)`** - **Description**: Lower cases all characters in property's values. - **Example**: `LOWERCASE("John")` - **Result**: `john` - **`UPPERCASE (text_property)`** - **Description**: Upper cases all characters in property's values. - **Example**: `UPPERCASE("John")` - **Result**: `JOHN` - **`SPLIT (property, separator, [index])`** - **Description**: Split a property based on a delimiter and return an array of split elements. Takes an optional index that returns the element at that index. - **Example**: - `SPLIT("a_b_c", "_")` - `SPLIT("john@example.com", "@", 0)` - **Result**: - `["a", "b", "c"]` - `"john"` - **`REMOVE (property, text)`** - **Description**: Remove all occurrence of text in property. - **Example**: `REMOVE("en-US", "en-")` - **Result**: `US` - **`EXTRACT_FROM_DICT (property, text)`** - **Description**: Extract a value from a dictionary string based on a specific key. - **Example**: `EXTRACT_FROM_DICT("{'id': 1, 'name': 'John', 'country': 'US'}", "name")` - **Result**: `John` ### Math functions | Function | Description | Example | Result | | --- | --- | --- | --- | | `SUM(num_property1, num_property2)` | Adds a property with other properties or with numbers. Equivalent to the `+` operator. Use `ADD` as an alias. | `SUM(subtotal, tip) >>>  SUM(10, 2)` | 12 | | `MINUS(num_property1, num_property2)` | Subtracts a property with other properties or with numbers. Equivalent to the `-` operator. Use `SUBTRACT` as an alias. | `MINUS(total, tip) >>> MINUS(12, 2)` | 10 | | `MULTIPLY (num_property1, num_property2)` | Multiplies a property with other properties and/or with numbers. Equivalent to the `*` operator. | `MULTIPLY(price, quantity) >>> MULTIPLY(2.50, 4)` | 10 | | `DIVIDE(numerator, denominator)` | Divides a property by another property or number. Equivalent to the `/` operator. | `DIVIDE(calorie_intake, calorie_goal) >>> DIVID(1000, 2000)` | 0.5 | | `POWER(num_property, exponent)` | Takes the property's values to the exponent power. | `POWER(property, 3) >>> POWER(2, 3)` | 8 | | `MIN(num_property1, num_property_2)` | Returns the minimum value between two numbers. | `MIN(5, 10)` | 5 | | `MAX(num_property1, num_property_2)` | Returns the maximum value between two numbers. | `MAX(5, 10)` | 10 | | `CEIL(num_property)` | Rounds up to the nearest integer. | `CEIL(3.8)` | 4.0 | | `FLOOR(num_property)` | Rounds down to the nearest integer. | `FLOOR(3.8)` | 3.0 | ### Object functions | Function | Description | Example | Result | | --- | --- | --- | --- | | `EXTRACT_FROM_DICT (property, text)` | Extract a value from a dictionary string based on a specific key. | `EXTRACT_FROM_DICT("{'id': 1, 'name': 'John', 'country': 'US'}", "name")` | `John` | ### Date/ time functions Amplitude requires all Unix timestamps to be in milliseconds. | Function | Description | Example | Result | | --- | --- | --- | --- | | `DATE_TO_LONG (date_property)` | Convert date into Unix timestamp | `DATE_TO_LONG("2020-12-01")` | 1606780800000 | | `TIME_TO_LONG (time_property)` | Convert date time (YYYY-MM-dd\[T\]HH:mm:ss) into Unix timestamp | `TIME_TO_LONG("2020-12-01 12:00:00")` | 1606780800000 | | `LONG_TO_TIME (number_property)` | Convert Unix timestamp into date-time (local to user's timezone) | `LONG_TO_TIME (1606780800000)` | 2020-12-01 12:00:00 | | `LONG_TO_DATE (number_property)` | Convert Unix timestamp into date (local to user's timezone) | `LONG_TO_DATE (1606780800000)` | 2020-12-01 | | `DATE_TIME_FORMATTER (datetime_property, old_format, new_format)` | Convert format of a datetime property to a new format. Refer to [Java SimpleDateFormat](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html) for more details. | `DATE_TIME_FORMATTER ("05.01.2021 12:00:00:000", "MM.dd.yyyy hh:mm:ss:SSS", "yyyy/MM/dd")` | 2021/05/01 | | `TODAY()` | Current day represented as a long in epoch time in UTC. | `TODAY() - start_date_in_ms >>> 1609459200000 - 1577836800000` | 31622400000 | | `EVENT_HOUR_OF_DAY()` | Get hour of day (0-23) from the event's timestamp. | `EVENT_HOUR_OF_DAY()` | 10 | | `EVENT_DAY_OF_WEEK()` | Get day of week from the event's timestamp as string. For example, Monday. | `EVENT_DAY_OF_WEEK()` | Monday | ### Array functions When performing computations on derived properties created from array properties, Amplitude assumes that only the first child is an array property. Amplitude only considers the first value of the other children, even when those other children are also array properties. Here are some illustrative examples: ```plaintext Example 1 propA = [1,2,3], propB = [a,b,c] CONCAT(propA, propB) = [1a, 2a, 3a] Example 2 propA = [1, 2, 3], propB = [a] CONCAT(propA, propB) = [1a, 2a, 3a] Example 3 propA = [1], propB = [a, b, c] CONCAT(propA, propB) = [1a] ``` | Function | Description | Example | Result | | --- | --- | --- | --- | | `ITEM_COUNT (property)` | Length of array property; defaults to 1 for non-arrayed properties. | `ITEM_COUNT(products)` | 3 | | `GREATEST(property)` | Get max value of the array. | `GREATEST(prices)` | 10 | | `LEAST(property)` | Get min value of the array. | `LEAST(prices)` | 2 | | `COALESCE(property)` | Get the first non-null value of the array | `COALESCE(locations)` | 'California' | ### Property functions When you select a property from the _Insert Property_ dropdown, Amplitude inserts a property function referencing that property directly into the editor. You can also manually insert this function wherever you want to reference a different Amplitude property. These functions are available inside other functions. | Function | Description | Example | Result | | --- | --- | --- | --- | | `PROPERTY(property_name, property_type)` | Reference to property within Amplitude. Possible property types: "user", "event", "derived", "lookup", "group" | `PROPERTY("first name","user")` | A reference to the user property "first name" in your project. This is how derived properties communicate with Amplitude’s query service. | | `PROPERTY(property_name, "group", group_type)` | Reference to group property within Amplitude. Group type is required for group properties. | `PROPERTY("name","group", "business")` | A reference to the group property "name" in the group type "business" within your project. This is how derived properties communicate with Amplitude’s query service. | #### Reference Event Time To use an event's timestamp in a derived property formula, select **Event Time** from the _Insert Property_ dropdown in the derived property builder. Inside a derived property formula, **Event Time** is a long value in epoch milliseconds. To display it as a readable date, wrap it in `LONG_TO_TIME` or `LONG_TO_DATE`. Don't wrap **Event Time** in `TIME_TO_LONG` or `DATE_TO_LONG`, because the value is already a long and the conversion returns `none`. To compare **Event Time** against a date or datetime property, convert the other property to a long with `TIME_TO_LONG` or `DATE_TO_LONG` instead. ### Conditional operators | Operator | Description | Example | | --- | --- | --- | | `IF(logical_expression, value_if_true, value_if_false)` | Returns `value_if_true` if `logical_expression` is true, otherwise returns `value_if_false`. | `IF(property == "(none)", "Property wasn't set", "Property was set")` | | `AND(logical_expression_1, logical_expression_2)` | Returns True if both logical expressions are true, false otherwise. | `AND(is_subscribed == "true", has_valid_promo == "true")` | | `OR(logical_expression_1, logical_expression_2)` | Returns True if any logical expression is true, false otherwise. | `OR(has_email == "true", has_phone == "true")` | | `SWITCH(expression, case_1, value_1, [case_2, value_2 ...], [default])` | Evaluates an expression and returns values based on defined cases. Returns a default value if no cases are met if defined, otherwise null. | `SWITCH(tier, "gold", 2, "silver", 2, "bronze", 1, 0)` | ### String/numerical operators | Operator | Example | | --- | --- | | `==` | `action == "purchase" ` | | `!=` | `item_count != 0 ` | | `contains` | `email contains "@gmail.com"` | | `does not contain` | `title does not contain "officer" ` | | `<`, `<=`, `>`, `>=` | `duration >= 60` | | `glob match` | `url glob match "https://www.google.*/*"` | | `glob does not match` | `query glob does not match "*/query=*"` | | `has prefix` | `title has prefix "sir" ` | | `does not have prefix` | `title does not have prefix "sir"` | ### Set operators Set literals ("apple", "orange") must appear on the right hand side of the operator. - **`==`** - **Example**: - `IF(product == ("apple","orange"), "true", "false")` - _product = "apple", Returns "true"_ - **`!=`** - **Example**: - `IF(product != ("apple","orange"), "true", "false")` - _product = "banana", Returns "true"_ ### Parallel operators Perform operations on arrays of data to help perform cart analysis. | Operator | Description | | --- | --- | | `PARALLEL_SUM` | Adds corresponding values from two arrays at each position. | | `PARALLEL_PRODUCT` | Multiplies corresponding values from two arrays at each position. Use this operator to calculate revenue for each item in a cart. For example, `PARALLEL_PRODUCT(PROPERTY('Products.price', 'event'), PROPERTY('Products.quantity','event'))` | | `PARALLEL_MAX` | Returns the larger of the corresponding values from two arrays at each position. | | `PARALLEL_MIN` | Returns the smaller of the corresponding values from two arrays at each position. | | `SUM_ARRAY` | Sums all numeric elements in a single array property. Use this operator to calculate total cart value for filtering or grouping. For example, `SUM_ARRAY([1, 2, 4])` returns `7`. | Parallel operators require at least one property to be a child cart property, and both properties must be under the same parent property. For example, `products.price` and `products.quantity` are compatible. `products.price` and `shoppinglist.quantity` aren't compatible because they have different parent properties. When you use a parallel operator with two arrays, it adds, multiplies, or compares corresponding values at each position. For example, `PARALLEL_SUM([1, 3, 5], [2, 4, 6])` returns `[3, 7, 11]`. When one input is an array and the other is a scalar (single number), the scalar broadcasts to match the array's length. For example, `PARALLEL_SUM([1, 3, 5], 1)` returns `[2, 4, 6]`, and `PARALLEL_PRODUCT(2, [4, 5, 6])` returns `[8, 10, 12]`. The derived property that a parallel operator creates becomes a child property of the parent cart property used in the formula. For example, creating a `revenue` derived property with `PARALLEL_PRODUCT(PROPERTY('products.price', 'event'), PROPERTY('products.quantity', 'event'))` makes `revenue` a child property of `products`. > **Note:** > > To use a derived property created with a parallel operator in a chart, first select the parent cart property (marked with `{:}`). The derived property then appears in the child property selection list. #### Parallel operator example You have a purchase event with the following cart property: ```json "Products": [{ "brand": "Apple","categories": "Digital Content","department": "Electronics", "price": 24.99,"quantity": 1 }, { "brand": "Adidas","categories": "Newsletter","department": "Electronics", "price": 24.99,"quantity": 1 }, { "brand": "Fossil","categories": "Digital Content","department": "Women's Clothing", "price": 24.99,"quantity": 2 }] ``` | Brand | Price | Quantity | | --- | --- | --- | | Apple | 24.99 | 1 | | Adidas | 24.99 | 1 | | Fossil | 24.99 | 2 | Use `PARALLEL_PRODUCT` to create a `Revenue` derived property: ```plaintext PARALLEL_PRODUCT( PROPERTY('Products.price', 'event'), PROPERTY('Products.quantity','event') ) ``` If you add this property to a chart, group by `Brand` to view revenue by brand. You can also use `SUM_ARRAY` on the `Revenue` derived property to calculate total cart value: ```plaintext SUM_ARRAY(PROPERTY('Revenue', 'derived')) ``` This returns the sum of all revenue values across items in the cart, which is useful for filtering or grouping by total cart value. ## Common derived properties formulas ### Calculate the age of a customer ```plaintext CEIL( DIVIDE( MINUS( PROPERTY('server_upload_time', 'amplitude_user'), TIME_TO_LONG(PROPERTY('Created At', 'user')) ), 86400000 ) ) ``` Use this formula when you track a user property with a date-time data type and want to calculate the age of that user (how long that user has existed in your system) since the event that set this user property. ### Calculate days since registration Use **Event Time** with a date or datetime property to calculate how many days passed between an event and a fixed date, such as a user's registration date. In the derived property builder, select **Event Time** from the _Insert Property_ dropdown, then build a formula like this: ```plaintext DIVIDE( MINUS( PROPERTY('Event Time', 'event'), TIME_TO_LONG(PROPERTY('registration_date', 'user')) ), 86400000 ) ``` This example assumes `registration_date` is a datetime string (for example, `"2023-08-18 17:37:39"`). Inside a formula, **Event Time** acts as a long in epoch milliseconds. The formula converts the registration date to a long with `TIME_TO_LONG`, subtracts it from **Event Time**, and divides by 86400000, the number of milliseconds in one day. ### Get the difference between two dates ```plaintext DIVIDE( MINUS( DATE_TO_LONG( PROPERTY( 'start_date', 'user' ) ), DATE_TO_LONG( PROPERTY( 'end_date', 'user' ) ) ), 86400000 ) ``` Sample output. In the derived property above, Amplitude converts the properties `end_date` and `start_date` into UNIX timestamps to calculate the difference between them. Amplitude then divides that result by 86400000, the number of milliseconds in one day. > **Note:** > > This output is a double type (for example, 2.0). ### Output a standardized date format ```plaintext IF( DATE_TIME_FORMATTER( PROPERTY( 'publishDate', 'event' ), "yyyy-MM-dd'T'HH:mm:ssX", 'yyyy-MM-dd' ) contains '-', DATE_TIME_FORMATTER( PROPERTY( 'publishDate', 'event' ), "yyyy-MM-dd'T'HH:mm:ssX", 'yyyy-MM-dd' ), IF( DATE_TIME_FORMATTER( PROPERTY( 'publishDate', 'event' ), "yyyy-MM-dd HH:mm:ss", 'yyyy-MM-dd' ) contains '-', DATE_TIME_FORMATTER( PROPERTY( 'publishDate', 'event' ), "yyyy-MM-dd HH:mm:ss", 'yyyy-MM-dd' ), DATE_TIME_FORMATTER( PROPERTY( 'publishDate', 'event' ), "yyyy-MM-dd", 'yyyy-MM-dd' ) ) ) ``` Sample output. One way to format dates to Standard Date Format is to use a series of IF statements. Make sure the higher specificity conditional comes first. Replace the `$<number>` here with the actual properties. ### Get the month and year a customer signed up ```plaintext CONCAT( REGEXEXTRACT( PROPERTY( 'start_date', 'user' ), 'dddd-dd' ), "-01" ) ``` In this example, the derived property pulls the sign-up month and year from a property that contains a more detailed value, then appends "-01" to set it to the beginning of the month. Use `REGEXEXTRACT()` to pull the year and month from the value, and use `CONCAT()` to append "-01". Replace the `$<number>` here with the actual properties. ### Replace existing property values ```plaintext IF( OR( REGEXEXTRACT( PROPERTY( "package", "event" ), 'Casual' ) =='Casual', REGEXEXTRACT( PROPERTY( "package", "event" ), '1 Job Posting' )=='1 Job Posting', REGEXEXTRACT( PROPERTY( "package", "event" ), '1 Basic' )=='1 Basic' ), 'Casual', 'False' ) ``` Sample output. To replace multiple property values, use `REGEXEXTRACT()` to pull the string from the property, and use OR statements inside an IF statement to check whether the value pulled from the properties contains any of the values you want to replace. In this example, if the property value matches any of the specified values, the formula replaces the value with `Casual`. Otherwise, the formula replaces the property with `False`. Replace the `$<number>` here with the actual properties. ### Count length of an array that was accidentally ingested as a string Convert the string to an array format by using SPLIT: ```plaintext SPLIT( PROPERTY('color', 'event'), ',' ) ``` Sample output: ![Screenshot 2023-09-28 at 14.39.54.png](https://amplitude.com/docs/images/data/screenshot-2023-09-28-at-14-39-54-png.png) Amplitude ingested the property color as the string "Red, Green, Blue". After using SPLIT, the resulting value is `[Red, Green, Blue]`. Use the above derived property within a new derived property that uses `ITEM_COUNT`. ```plaintext ITEM_COUNT( PROPERTY("Transform into Array", "derived") ) ``` Sample output: ![Screenshot 2023-09-28 at 14.42.30.png](https://amplitude.com/docs/images/data/screenshot-2023-09-28-at-14-42-30-png.png) Now the underlying data is an array. `ITEM_COUNT` counts the number of items that make up the array. ================================================================================ # Lookup Tables URL: https://amplitude.com/docs/data/lookup-tables ================================================================================ # Lookup Tables With Amplitude's Lookup Table feature, you can import your own data and map it to ingested properties to create an enhanced set of event and user properties. > **Note:** Plan availability > > Lookup Tables are available on Growth and Enterprise plans with the Govern add-on. To learn more or upgrade, contact [Sales](https://amplitude.com/sales-contact). ## Lookup table benefits - **Enrich data using ingested property values**: Say you've captured an event called `Purchased` with an event property named `SKU`. The `SKU` value itself doesn't inherently hold a lot of meaning. With your list of all the SKUs and their corresponding product names, you can use this feature to create a new property called `Product Name` that populates automatically based on that list. - **Bulk change or fix property values**: Imagine you've captured a user property called `Language Code` and passed in language codes (`en_US`, `fr_FR`, `de_DE`, and so forth). These codes are difficult to read, so you want a `Language` property that maps to friendlier values like `English`, `French`, and `German`. Use this feature to create a new property called `Language` that maps the language codes to the language names. - **Bulk filter long lists**: To analyze user behavior for a specific region when you have a list of all customers and their regions, use this feature to map each customer to a region, creating a new `Region` property. You can then filter to each region in a chart. > **Note:** > > Lookup Tables can't exceed 100MB or 1 million rows. Contact your Amplitude CSM if you have data that exceeds this limit. ## Find lookup properties in charts After you create a lookup property, it appears in chart dropdowns alongside the source property you mapped it from. > **Note:** Lookup properties based on child (cart) properties > > If you create a lookup property that maps from a child (cart) property (a property nested inside an object array), the lookup property doesn't appear in the main property list in charts. Instead, it appears under its parent cart property. To find it, first select the parent cart property (marked with `{:}`) in the property dropdown, then look for the lookup property as a nested option in the second-level dropdown. For more on cart properties, refer to [Cart analysis](https://amplitude.com/docs/analytics/charts/cart-analysis). ## Create a Lookup Table Before you can start using Lookup Tables, you need: - An event property or user property to create a mapping from. - A .CSV that has the data you want to map to. The first column data must correspond to the mapping property value and must contain unique values. > **Note:** > > Lookup Tables look for exact matches, and are case-sensitive. To create a new Lookup Table in Amplitude Data, follow these steps: 1. Navigate to _Sources_ in the project you want to import the .CSV data to. 2. Click **+ Add Source**. Search for _CSV_, then click it. 3. Navigate to your .CSV file and upload it. Then click **Next**. 4. Map your event property by selecting it from the dropdown. When you're done, click **Finish**. > **Note:** > > You must be an Admin or Manager of the project to add or manage a source. ## Update a Lookup Table To create a new lookup property or fix an incorrectly mapped property, update the lookup table by following these steps: 1. In Amplitude, navigate to _Sources_, find the Lookup Table in the _Sources List_. Click it to open its _General_ tab. 2. Open the _Edit Lookup Table Configuration_ tab. 3. Make your changes. You can change the mapping, or replace the .CSV by uploading a new file. 4. When you're finished, click **Update your lookup table configuration**. ## Delete a Lookup Table and its properties To delete a Lookup Table you no longer need, follow these steps: 1. In Amplitude, navigate to _Sources_, then find the Lookup Table in the _Sources List_. 2. Open the _Edit Lookup Table Configuration_ tab. 3. Click the trash can and follow the on-screen instructions. ================================================================================ # Verify persisted properties URL: https://amplitude.com/docs/data/persisted-properties/verify-persisted-properties ================================================================================ # Verify persisted properties Persisted Properties carry a property value forward from an earlier source event to a later target event at query time. After you set up a persisted property, it starts enriching your target event immediately. This guide shows you how to confirm they are working, using your own live data. The pattern this guide covers: **An event that fires your property → an event you want to analyze** For example, "Item Viewed" fires `brand` and you want to see that brand carried forward to "Purchase Completed". Or "Search Performed" fires `search_term` and you want it on "Signup". Substitute your own events and properties throughout. The verification process consists of: 1. Confirm the property is firing on the event that should carry it. 2. Confirm the right users are in scope. 3. Validate persistence in a Data Table. ## Before you start Before running any checks, make sure you have [created the persisted property](https://amplitude.com/docs/data/persisted-properties) in **Data > Properties** and noted down: - The event that fires the property you want to carry forward. - The property name as it appears on that event. - The event you want to analyze. This is the one you want enriched with the persisted value. Also note the allocation method you chose, either **Original** (first touch) or **Most Recent** (last touch). The allocation determines which value gets carried when a user fires the source event more than a single time before reaching the target. ## Step 1: Confirm the property is firing on the event that should carry it Before checking whether values are being persisted, confirm the property actually arrives on the source event in the first place. A high `(none)` rate on your target event is often traced back here. ### Check User Profiles 1. Go to _Users & Groups > [User Profiles](https://amplitude.com/docs/analytics/user-data-lookup)_. 2. Use the search bar to filter by name, email, or user ID if you have a specific user in mind. 3. Click **Add Filter** and choose **Performed event**. Select your source event. This narrows the list to users who have fired it at least once. 4. Click into any user in the results. In their event timeline, find an instance of the source event and expand it. You should see the property you're persisting listed alongside its value. > **Note:** What to look for > > The property appears with a non-null value on the source event for the majority of users. Occasional nulls are normal. Some sessions may not hit that code path. A null rate above 30% suggests an instrumentation gap that needs fixing before persisted properties can work. ### Narrow to users who have the source but not yet the target A useful diagnostic is to isolate users who fired the source event but haven't fired the target event in the same period. These users let you inspect the source property in isolation, without the complexity of a full journey. 1. Add a filter: `Performed event = your source event`. 2. Add a second filter: `Did not perform = your target event`. 3. Browse these users' timelines. Every source event should carry the property with a non-null value. This group is your cleanest signal that the upstream data is healthy. After you're satisfied the source property is arriving reliably, proceed with the verification process. ## Step 2: Confirm the right users are in scope Review the users who have fired both events. These are the users who carry the persisted value from the source to the target, and they're the population that appears in the [Data Table](#step-3-validate-persistence-in-a-data-table). 1. In User Profiles, add a filter: `Performed event = your source event`. 2. Add a second filter: `Performed event = your target event`. 3. Note the user count. This is the population you expect to see in the Data Table you'll build next. 4. Click into a few users. In each timeline, find a source event followed by the target event. Confirm the source event carries the property, and verify the event ordering matches what you'd expect for your allocation method. > **Note:** Allocation method affects directionality > > **Original** (first touch) locks in the first value Amplitude ever recorded for the user. It can attribute that value even if the source event fired after the target event within the expiration window. > > **Most Recent** works in a strictly forward direction, using the latest value recorded before query time. When reviewing timelines, keep your method in place: for **Original**, find the chronologically earliest source event. For **Most Recent**, find the one closest to the target. ## Step 3: Validate persistence in a Data Table The [Data Table](https://amplitude.com/docs/analytics/charts/data-tables/data-tables-attribute-credit) chart is the most powerful verification tool because it shows you the distribution of persisted values at scale, and lets you drill into the users behind any cell to close the loop. ### Build the table 1. Go to _Create > Data Table_. 2. Set the metric event to your target event (for example, "Purchase Completed"). Use **Event Totals** as the metric. 3. In the **Group-by** field, add your persisted property. It appears alongside standard event properties in the dropdown. Find the name you gave it in _Data > Properties_. 4. Set the date range to the last 7 days, or any window where you know both events have fired. ### Read the results After the table loads, find the rows for each distinct value of the persisted property. The values are carried forward from the source event to the target. A healthy setup shows most of your target event volume attributed to a named value, with a small `(none)` row. | What you see | What it means | What to do | | --- | --- | --- | | Named values appear with volume; `(none)` is a small fraction | Persistence is working. The property is being carried forward successfully. | Setup is correct. Tune your allocation method or expiration if needed. | | `(none)` dominates the table | Many target events lack a persisted value. The source event may not be firing the property reliably, or the event ordering doesn't match your allocation method. | Return to the [Step 1](#step-1-confirm-the-property-is-firing-on-the-event-that-should-carry-it) step and audit source event instrumentation. Confirm both events fall within the expiration window. For **Most Recent**, the source should precede the target; for **Original**, the first-ever occurrence is used regardless of ordering. | | Persisted property doesn't appear in Group-by | The property definition may not yet be saved, or it targets a different event. | Go to **Data > Properties**, open the persisted property, and confirm the source event and property name are correct. | ### Drill into users from the table Clicking any cell in the Data Table opens a list of users behind that number. This is the most direct way to close the loop between your aggregate picture and real individual journeys. 1. Click on the count in a cell. For example, the number of target events associated with a specific persisted value. 2. In the panel that opens, click to create a cohort. Cross-reference these users against the users you identified in the [Confirm the right users are in scope](#step-2-confirm-the-right-users-are-in-scope) step. They should largely overlap. 3. Click into one of those users and open their event timeline. Find the target event and confirm it shows the persisted property with the expected value. Then trace back to the source event and confirm the value matches. 4. _(optional)_ Compare allocation methods side by side. If you set up two persisted properties with different allocation methods (Original and Most Recent), add both as group-bys in the same table. Rows where they agree represent single-source sessions. Rows where they differ reveal multi-source journeys. Both values are correct, they just answer different questions. > **Note:** > > The loop is closed when: > > 1. The user appears in your [filter](#step-2-confirm-the-right-users-are-in-scope) (performed both events). > 2. They appear in the Data Table under a named persisted value, not `(none)`. > 3. Their event timeline shows the source and target events within the same expiration window, with the persisted property value matching what you'd expect given your allocation method. ## Verify a property with item-level attribution If your persisted property uses [item-level attribution](https://amplitude.com/docs/data/persisted-properties#advanced-item-level-attribution), verification groups events by **item identifier** (such as `product.item_id`) rather than by user or session. Each item in the cart can carry a different persisted value, so checks happen for each item. For each item, confirm: - The first-touch and last-touch candidate values from your linking events. - Which value Amplitude persists onto each cart event, based on the property's allocation method. - Whether the persisted value matches what you expect. A mismatch points to an instrumentation gap on the source event or the linking event. ### Spot-check a single item 1. In _Users & Groups > [User Profiles](https://amplitude.com/docs/analytics/user-data-lookup)_, open a user who completed a `Purchase` (or `Add to Cart`) event. 2. Expand the cart array on that event. Note the item identifier (such as `product.item_id`) for one item. 3. In the same user's timeline, find the [linking events](https://amplitude.com/docs/data/persisted-properties#configure-item-level-attribution) you selected when configuring the property — for example, `View Item Details` and `Add to Cart`. Confirm each linking event carries both the source property and the item identifier. 4. Compare the persisted value on the cart event for that item against your allocation method: - **Original**: the value from the earliest linking event for that item. - **Most Recent**: the value from the latest linking event for that item before the cart event. ### Validate at scale in a Data Table Build a [Data Table](https://amplitude.com/docs/analytics/charts/data-tables/data-tables-attribute-credit) with your cart event grouped by both the persisted property and the item identifier. Rows with `(none)` are candidates to investigate — either the source event didn't fire the property for that item, or the linking events don't capture the item identifier reliably. ## Troubleshoot common issues | Symptom | Likely cause and fix | | --- | --- | | High `(none)` rate on the target event | The source event isn't firing the property on most instances, or users are reaching the target event outside the expiration window. Audit source event instrumentation first. If the journey spans multiple sessions, switch expiration from **Session** to **User**. | | Persisted property missing from Group-by | The property definition may not yet be saved or is pointing at the wrong event. Go to **Data > Properties**, open the persisted property, and confirm the source event and property name exactly match your taxonomy. | | Values don't match what you see in the user timeline | Likely an allocation mismatch. If **Original** is set, the value locked in is from the first source event in the session, not the one closest to the target. Re-read the timeline in session order. | | Users in Step 2 don't appear in the Data Table | The session or user expiration window may have ended between the two events. Extend the expiration, or filter the Data Table to the same date range you used in User Profiles. | ================================================================================ # Aggregated Metrics (fka Warehouse Metrics) Overview URL: https://amplitude.com/docs/data/warehouse-metrics ================================================================================ # Aggregated Metrics (fka Warehouse Metrics) Overview Aggregated Metrics (formally known as Warehouse Metrics) import precomputed metric values directly from your data warehouse into Amplitude, so your analyses use the same numbers as your warehouse source of truth. Unlike event-based metrics that Amplitude calculates from behavioral data, Aggregated Metrics (fka Warehouse Metrics) sync pre-calculated values from your warehouse. You can use business metrics like revenue, customer lifetime value, health scores, and financial KPIs alongside behavioral data in Amplitude's analytics and experimentation tools. Use Aggregated Metrics when you need numeric, time-series values that you can aggregate, set as experiment goals, or chart over time. If you only need the most current user attributes from your warehouse, use [Profiles](https://amplitude.com/docs/data/profiles) instead. > **Note:** > > To gain access, contact your Amplitude Client Success Manager. ## How Aggregated Metrics (fka Warehouse Metrics) work Aggregated Metrics (fka Warehouse Metrics) sync on a recurring schedule from tables in your data warehouse. Each row should include the following: - **Time**: When the metric value is valid. - **User identifier**: The `user_id` or `device_id` to which the metric applies. - **Insert identifier**: An optional unique identifier for deduplication. - **Metric values**: Numeric values (like revenue: 13423, count: 50). - **Dimensions** (optional): Categorical attributes (like `health_score`: `"green"`, or `paid: true`). ## Requirements - An Amplitude project. - Read access to your Snowflake instance. - A table or view that contains metric values with timestamps and user identifiers. - Change Data Capture (CDC) enabled for your metrics table. > **Note:** Anonymous user support > > Aggregated Metrics (fka Warehouse Metrics) support both identified users (`user_id`) and anonymous users (`device_id`). ## Metric types Aggregated Metrics (fka Warehouse Metrics) supports these aggregation types on values: - **Sum**: Total of all values. - **Average**: Mean value across per-user sums. - **Min**: Minimum value. - **Max**: Maximum value. For more information, refer to [Warehouse Metric Calculations](https://amplitude.com/docs/data/warehouse-metric-calculations). ## Data types - **Metrics**: Numeric values only (integers, decimals). - **Dimensions**: String, number, or boolean values for grouping and filtering. > **Note:** > > Metrics require the source data to be numeric. ## Common use cases Aggregated Metrics (fka Warehouse Metrics) solve challenges where business metrics are difficult or impossible to calculate natively in Amplitude: ### Revenue and financial metrics - **Average Order Value (AOV)**: Precomputed. - **Credits Remaining/Used**: Account balance tracking. These metrics often require data that's too high-volume, sensitive, or non-event-based to send to Amplitude efficiently. ### Customer health metrics - **Customer Lifetime Value (LTV)**: Forward-looking revenue projections. - **Health Scores**: Composite metrics from multiple data sources. - **Churn Risk**: Machine learning predictions from your warehouse. These metrics require modeling and forecasting that happens in your data warehouse. ### State metrics - **Activation Status**: User onboarding state. - **Subscription Tier**: Current plan level. - **Beta Group Membership**: Feature access flags. - **Experiment Exposure**: Assignment tracking. These metrics track current user state rather than discrete events. ## Import metric data Aggregated Metrics (fka Warehouse Metrics) supports Snowflake. ### Enable change tracking If this is your first time importing from this table, enable change tracking in Snowflake: ```sql ALTER TABLE YOUR_DATABASE.YOUR_SCHEMA.YOUR_METRICS_TABLE SET DATA_RETENTION_TIME_IN_DAYS = 7; ALTER TABLE YOUR_DATABASE.YOUR_SCHEMA.YOUR_METRICS_TABLE SET CHANGE_TRACKING = TRUE; ``` > **Note:** Snowflake Standard Edition > > On Snowflake Standard Edition, the maximum retention time is one day. Set your sync frequency to 12 hours. ### Connect and configure Follow the instructions in [Snowflake Data Import](https://amplitude.com/docs/data/source-catalog/snowflake#set-up-and-verify-the-connection) to connect to your Snowflake instance. ## Data specifications Your metrics table must include specific required fields and can optionally include additional fields. You must include at least one metric or dimension field. ### Required fields | Field | Description | Example | | --- | --- | --- | | `time` | When the metric value is valid | `1762813185` | | `user_id` or `device_id` | A unique identifier for a user or device. | `user_12345` | > **Note:** Time conversion > > Amplitude requires the incoming time in milliseconds from the Unix epoch. Use Snowflake’s built-in conversion functions or other tooling in your data pipeline to convert to this format before Amplitude ingests the data. ### Optional fields | Field | Description | Example | | --- | --- | --- | | `insert_id` | A unique identifier for deduplication. | `51a87950-b35d-4a2f-b919-af92f00f75dd` | ### Metric fields Your metrics table must include at least one metric or dimension field. | Field Type | Description | Example | | --- | --- | --- | | Metric | Numeric value (integer or decimal) | `150.25` | | Dimension | String, boolean, or number for filtering/grouping | `"active"`, `true`, `10` | ### Example ```json { "time": "1762813185", "user_id": "user_12345", "total_revenue": 1543.5, "order_count": 12, "ltv": 15430.0, "health_score": "green", "is_paid": true } ``` ## Query template ```sql SELECT event_date AS "time", user_id AS "user_id", total_revenue AS "total_revenue", order_count AS "order_count", ltv AS "ltv", health_score AS "health_score", is_paid_customer AS "is_paid" FROM DATABASE_NAME.SCHEMA_NAME.METRICS_TABLE WHERE event_date >= CURRENT_DATE - INTERVAL '30 days' ``` ## Add your metric to an experiment Use Aggregated Metrics (fka Warehouse Metrics) in end-to-end experiments or experiment results as: - **Goals**: Measure impact on business metrics. - **Analysis metrics**: Understand how experiments affect revenue, LTV, and other KPIs. When you create or edit an experiment, select metrics from the Warehouse source in the metrics picker. > **Note:** Last synced information > > Aggregated Metrics (fka Warehouse Metrics) display when they were last synced and the next scheduled sync. ### Creating a warehouse metric in your experiment 1. In the experiment, navigate to the **Metrics** panel. 2. Click **Create a custom metric**. 3. Enter a **Name** and **Description** for the metric. 4. Click the **Warehouse** tab. 5. Select the table you specified during data import. 6. Define the metric. Choose **Sum**, **User Average**, **Min**, or **Max**. 7. Select the column in the table you want to combine using the definition you selected. 8. Preview the results and click **Save**. > **Tip:** > > Aggregated Metrics (formally known as Warehouse Metrics) you created before appear in the **Add Metric** dialog. You don't need to recreate them. ## Best practices 1. **Define metrics once**: Create metrics in your warehouse and reference them everywhere in Amplitude. 2. **Use descriptive names**: Name metrics clearly (like "Average Order Value" not "metric\_1"). 3. **Include descriptions**: Add descriptions in the Metrics creation flow to help users understand what each metric measures. 4. **Start with key metrics**: Begin with 5-10 critical metrics before expanding. ## Troubleshooting If you encounter issues with Aggregated Metrics (fka Warehouse Metrics), these common problems and solutions can help you resolve them. ### Sync failures - Ensure data retention period is at least seven days, unless you use Snowflake Standard Edition, then set it to one day. - Verify warehouse credentials haven't expired. - Check that the table structure hasn't changed. - Ensure Change Data Capture (CDC) is enabled in your Snowflake table or view. - Verify the sync completed successfully in the activity log. ## Limitations - Aggregated Metrics (fka Warehouse Metrics) require a unique user identifier per row. - Metric values can only be numeric (dimensions can be strings, numbers, or booleans). - Each metric represents a point-in-time value, not an event stream. - Amplitude doesn't support rollup or combined tables without unique user identifiers. - Aggregated Metrics (fka Warehouse Metrics) don't support CUPED or group by. ## Frequently asked questions ### Using Aggregated Metrics (fka Warehouse Metrics) without sending events to Amplitude Yes, but Aggregated Metrics (fka Warehouse Metrics) are most powerful when combined with behavioral events. You can create metric-only charts if needed. ### Differences between Aggregated Metrics (fka Warehouse Metrics) and profiles Profiles sync current user attributes. Aggregated Metrics (fka Warehouse Metrics) sync time-series numeric values that you can combine, use as experiment goals, and visualize over time. ================================================================================ # Connect to a source URL: https://amplitude.com/docs/data/sources/connect-to-source ================================================================================ # Connect to a source To connect a data source, select **Catalog** in the left navigation, choose the tile for the platform you want to add, and complete its setup instructions. A data source sends data from a third-party platform, warehouse, or event stream into Amplitude for analysis. Use a data source when you already have data flowing through one of these systems; if you're instrumenting your own app from scratch, use the [Amplitude SDKs](https://amplitude.com/docs/get-started/get-data-in) instead. ## Understand the interface The _Sources_ panel includes two tabs, **Sources List** and **Ingestion Debugger**. The **Sources List** tab shows the active data sources for a project, the activity status of each source, and the event volume each source sent in the last 30 days. The **Ingestion Debugger** tab shows three charts: successful requests, event and identify counts, and error requests for the endpoints you specify. You can view the last 3 hours or the last 90 days. Below the **Ingestion Debugger**, the throttled users and devices list shows which users and device IDs Amplitude has throttled in the last 30 minutes, plus any silenced device IDs. > **Note:** > > Only users with Manager permissions or higher can view throttled user IDs and device IDs in the **Ingestion Debugger**. Members and Viewers can't access the throttled users and devices list. ## Set up ingestion error alerts Configure email alerts to notify you when ingestion errors occur. Ingestion error alerts help you identify and resolve data quality issues before the issues affect your analysis. To set up ingestion error alerts, follow these steps: 1. Navigate to _Data > Sources_. 2. Select the **Ingestion Debugger** tab. 3. Select **Create A New Alert**. 4. Configure your alert settings: - **Ingestion Path**: Select the source of the error. For example, SDK or HTTP API. - **Error type**: Select the type of error that triggers the alert. - **Threshold**: Set the error rate or count that triggers an alert. - **Evaluation Window**: Set the frequency with which Amplitude checks for alerts. - **Recipients**: Add email addresses for notification recipients. - **Alert frequency**: Choose how often Amplitude sends alerts (for example, immediate, hourly, or daily). 5. Enable the alert and select **Create Alert**. After you set up alerts, Amplitude monitors ingestion error rates and sends email notifications when errors exceed your configured thresholds. Use these notifications to address data quality issues and maintain reliable analytics. > **Tip:** Best practices > > - Set up alerts for critical data sources that power key dashboards or reports. > - Include multiple team members as recipients so one person doesn't receive all alerts. > - Review and adjust thresholds periodically based on your typical error patterns. ## Add a data source To add a new data source, follow these steps: 1. In the left navigation, select **Catalog**. 2. Select the tile for the source you want to add. 3. Complete the setup for the source. Some sources redirect you to log in to your source account. Other sources show setup instructions on the source's **Set Up Connection** tab. ## Source notifications Notifications alert you when a source has an issue. By default, new sources notify the creator and Admins. ### Edit source notifications 1. In the left navigation, select **Sources**. 2. Select the source whose notifications you want to configure. 3. On the right side of the screen, select the email icon. The email icon tooltip says **Manage Notifications**. 4. Select **Subscribe** or **Unsubscribe** to change your notification subscription. To add or remove other email addresses, select **Manage Notifications**. ### Add source notifications to Slack 1. Follow [Slack's email guide](https://slack.com/help/articles/206819278-Send-emails-to-Slack#h_01F4WDZG8RTCTNAMR4KJ7D419V) to set up an email address for your Slack channel or DM. 2. Use the steps in _Edit source notifications_ to add that email address to the source notifications. ================================================================================ # Amplitude Wordpress plugin URL: https://amplitude.com/docs/data/amplitude-wordpress-plugin ================================================================================ # Amplitude Wordpress plugin The [Amplitude Wordpress Plugin](https://wordpress.org/plugins/amplitude/) instruments your Wordpress site with an advanced version of Autocapture. The Amplitude Wordpress plugin installs a version of the [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) and adds the script before the `</head>` tag on each of your site's pages. The plugin enables an [advanced](https://github.com/amplitude/Amplitude-TypeScript/tree/v1.x/packages/plugin-default-event-tracking-advanced-browser) version of Autocapture that tracks the following events and associated properties: - Page viewed. - Form started. - Form submitted. - File downloaded. - Start session. - End session. - Element clicked (new in advanced DET). - Element changed (new in advanced DET). If you enable Session Replay in the plugin's settings, the plugin also initializes and adds the [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin). ## Install the plugin Follow these instructions to install the Amplitude Wordpress plugin. 1. Log in to Wordpress and open your site's dashboard. 2. Click **Plugins** in the sidebar. 3. Click **Add New Plugin**. 4. Search for `Amplitude`. 5. Click **Install Now** on the Amplitude plugin. 6. When installation completes, click **Activate Plugin**. ## Configure the plugin With the Amplitude Wordpress plugin settings page open: 1. Enter your Amplitude project's [API key](https://amplitude.com/docs/apis/authentication). 2. (Optional) Enable Session Replay and set the [Sample Rate](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#sampling-rate) with the slider. 3. Click **Save**. After you enable the plugin, confirm in Amplitude that your project receives data from the plugin. ## Session Replay If you enable Session Replay in the plugin, replays may not appear in Amplitude. This can happen for a few reasons: - Users must complete their interaction with the site, which happens when they close the browser or leave the site. Wait at least five minutes after a session ends before attempting to view the replay in Amplitude. You may need to refresh the Amplitude page you're on. - The sample rate you select determines the percentage of sessions that Session Replay captures. If you set the sample rate below `1`, Amplitude may not capture the specific session in question. - You don't have Session Replay enabled on your account. ## Autocapture The Wordpress plugin installs a version of the Browser SDK that enables a version of Autocapture that tracks two extra events: - `[Amplitude] Element Clicked`. - `[Amplitude] Element Changed`. These are high-volume events with a high degree of cardinality in the property values. However, Amplitude limits the "noise" to these two events and a specific set of properties, limiting the impact on your taxonomy. This approach differs from auto track or auto capture because it targets two specific interactions and a small set of elements to limit the impact of any noise in your data. ### Impact on event volume Autocapture impacts event volume because it adds new tracking, which results in more captured events. The amount of this increase depends on your organization. If you start with few precisely tracked events, expect a large increase in event volume. If your organization has an extensive tracking plan with many precisely tracked events, the impact is lower. For help or support with this plugin, contact [plugins@amplitude.com](mailto:plugins@amplitude.com). ================================================================================ # Amplitude Shopify Plugin URL: https://amplitude.com/docs/data/amplitude-shopify-plugin ================================================================================ # Amplitude Shopify Plugin [Shopify](https://www.shopify.com/) is a commerce platform that lets businesses of any size create, customize, and manage online stores. Shopify offers tools for product listings, payments, shipping, and customer engagement, streamlining the selling process online, across social media, and in person. The [Amplitude Shopify Plugin](https://apps.shopify.com/amplitude) brings data from your Shopify store into Amplitude, unlocking insights from funnel analytics, user behavior trends and charts, ROI analysis, Session Replay, and more. ## How the Shopify plugin works The Shopify plugin installs a version of the [Amplitude Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) and adds the script before the `</head>` tag of your site's pages. The script includes [Session Replay](https://amplitude.com/docs/session-replay) and [Web Experiment](https://amplitude.com/docs/web-experiment/set-up-a-web-experiment). > **Note:** Guides and Surveys > > The Shopify plugin doesn't include [Guides and Surveys](https://amplitude.com/docs/guides-and-surveys). To use Guides and Surveys on your Shopify store, install the [Guides and Surveys Web SDK](https://amplitude.com/docs/guides-and-surveys/sdk) separately. > **Warning:** Shopify and flickering > > The method Shopify uses to load Amplitude's Shopify app causes flickering. To avoid this, add the [asynchronous web script with the anti-flicker snippet](https://amplitude.com/docs/web-experiment/implementation#async-script-with-anti-flicker-snippet) to your `theme.liquid` file. The Shopify plugin captures Amplitude's default events, including [marketing attribution](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-marketing-attribution) and Shopify's standard [events](https://shopify.dev/docs/api/web-pixels-api/standard-events). #### Shopify plugin events and event properties | Event | Source | Properties | | --- | --- | --- | | Page viewed | Amplitude | Page counter, Page domain, Page location, Page path, Page title, Page URL, Session Replay ID (if enabled), Referrer, [Attribution](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-marketing-attribution), [User properties](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#user-properties). | | Start session | Amplitude | Session Replay ID (if enabled), [User properties](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#user-properties). | | End session | Amplitude | [User properties](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#user-properties). | | Form started | Amplitude | Form destination, Session Replay ID (if enabled), [User properties](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#user-properties). | | Form submitted | Amplitude | Form destination, Session Replay ID (if enabled), [User properties](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#user-properties). | | File downloaded | Amplitude | File extension, File name, Link text, Link URL, Session Replay ID (if enabled), | | Element clicked | Amplitude | Element Aria Label, Element Class, Element Hierarchy, Element href, Element ID, Element Parent Label, Element Position Left, Element Position Top, Element Selector, Element Tag, Element Text, Page Title, Page URL, Session Replay ID, Viewport Height, Viewport Width. | | Element changed | Amplitude | Element Class, Element Hierarchy, Element ID, Element Parent Label, Element Position Left, Element Position Top, Element Tag, Page Title, Page URL, Session Replay ID, Viewport Height, Viewport Width. | | Collection viewed | Shopify | Collection title | | Product viewed | Shopify | Quantity, SKU, Price, Currency Code, Type, Variant Title, Title, Vendor, Products | | Product added to cart | Shopify | Quantity, SKU, Price, Currency Code, Type, Variant Title, Title, Vendor, Products | | Product removed from cart | Shopify | Quantity, SKU, Price, Currency Code, Type, Variant Title, Title, Vendor, Products | | Checkout started | Shopify | Discounted amount, Total price, Currency code, Products | | Checkout contact info submitted | Shopify | -- | | Checkout address info submitted | Shopify | -- | | Checkout shipping info submitted | Shopify | -- | | Checkout completed | Shopify | Total tax, Discount amount, Subtotal price, Currency code, Customer id, Products | | Order created | Shopify | Customer, Products | | Search submitted | Shopify | Search query | In most scenarios, when a customer completes the checkout flow, Shopify sends the Checkout complete event, then the Order created event. If you create an order manually from your store's Admin page, only the Order created event sends. The Checkout complete event is specific to a customer completing the checkout flow. Amplitude sets User ID using the email address or phone number the customer enters in the Contact section of the checkout. > **Note:** Shopify checkout page > > Shopify prevents third-party packages from loading on your store's checkout page. As a result, Amplitude doesn't receive events from the checkout page, and you can't run experiments on it. ### Performance impact The packages that Amplitude adds to your Shopify pages weigh approximately 167kb. Internal testing showed Lighthouse performance reports averaging 98 without the plugin and 96 with the plugin. ## Install the plugin The method you use to install the Shopify plugin depends on whether you have an existing Amplitude organization. ### Install without an existing Amplitude organization 1. Find the [Amplitude Shopify plugin](https://apps.shopify.com/amplitude) in the Shopify App Store. 2. Click **Install** and confirm access to add it to your Shopify store. 3. Navigate to the [Amplitude Get Started page](https://analytics.amplitude.com/login?utm_source=shopify_app) and click to create your Amplitude account. Complete the form, agree to terms, and click **Continue**. > **Note:** Data Storage Location > > Amplitude provides data storage in the US and EU. Choose the appropriate option based on your location. 4. After you create your account, on the Amplitude setup page, click **Shopify** in the _Other ways to install_ section. 5. In the modal, copy your Amplitude project's API key. 6. Return to the Amplitude Settings screen in Shopify, enter the API key, and click **Connect**. ### Install into an existing Amplitude organization 1. Log in to Amplitude and navigate to your organization's settings. 2. Select the project within your organization that you want to connect to Shopify. 3. Find the project's API key and copy it. 4. Return to the Amplitude Settings screen in Shopify, enter the API key, and click **Connect**. ### Configure Session Replay sample rates 1. Log in to Amplitude as a manager and navigate to your organization's settings. 2. Click **Session Replay & Heatmaps** in the sidebar. 3. Select the project that matches the API key you used to install the Shopify app. 4. Input the sample rate you want under the Sampling section. 5. Save the settings. ================================================================================ # Track sessions URL: https://amplitude.com/docs/data/sources/instrument-track-sessions ================================================================================ # Track sessions A session is a continuous span when a user has your app in the foreground or your website open. Amplitude groups events into sessions by session ID, derives Start Session and End Session events, and exposes session counts and durations to the [User Sessions chart](https://amplitude.com/docs/data/user-properties-and-events). Use the default session tracking when you want Amplitude SDKs to manage session boundaries automatically. If you need session boundaries tied to specific events or a different timeout, configure a custom session definition instead. ## How Amplitude defines sessions Session behavior differs between mobile and browser applications: - For **mobile**, a session begins when the app moves into the foreground. A mobile session ends when the app goes into the background and sends no events for at least five minutes. Events sent within five minutes of each other count toward the current session. You can define a custom session expiration time with `setMinTimeBetweenSessionsMillis(timeout)`, where `timeout` is in milliseconds. - On a **browser**, a session begins when the website loads and the SDK initializes. A browser session ends when the last event occurs. Web sessions time out after 30 minutes by default. Events sent within 30 minutes of each other count toward the same session. You can customize the browser timeout window with the [Browser SDK configuration options](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2). Amplitude automatically generates a session ID for each new session. The session ID is the session's start time in milliseconds since **epoch** (also known as the [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time)). All events within the same session share the same session ID. Amplitude SDKs manage session IDs automatically. If you send data to Amplitude through the HTTP API, explicitly set the [session ID](https://amplitude.com/docs/apis/analytics/http-v2) field to track sessions. ### How Amplitude counts sessions To count sessions, Amplitude filters for events marked as "active," applies the project's session definition, groups the filtered events into sessions, and counts the grouped sessions. For more information about setting a project's session definition, review [Manage Organizations and Projects](https://amplitude.com/docs/admin/account-management/manage-orgs-projects#view-and-edit-your-project-information). ## How Amplitude groups events into sessions By default, Amplitude uses session ID as the session property. Amplitude groups all events with the same session ID and the same user ID into the same session. The session ID doesn't need to be unique across multiple users. You can change the property you use to group sessions. Amplitude SDKs automatically generate and manage session IDs for events. For events sent through the [HTTP API](https://amplitude.com/docs/apis/analytics/http-v2), Amplitude defaults to a session ID of `-1`. A session ID of `-1` excludes the event from all session metrics. > **Note:** > > A session ID of `-1` commonly occurs when data comes to Amplitude from Segment through a cloud-mode connection. As with data sent through the HTTP API, you need to explicitly set a session ID to track sessions. In a user's event stream, a blue line connects events in the same session. Amplitude assigns a session to a specific date based on its actual start time. The start time must fall within a chart's selected date range for Amplitude to include the session on that chart. For example, a session begins on May 17 at 8:00 PM and ends on May 18 at 1:30 AM. The session appears on charts where the selected date range includes May 17, the date when the session began. The date range for the example session can start on or before May 17 and end on or after May 17. If the chart's date range starts on May 18, the session doesn't appear on the chart, even though the session was still active on May 18. ### Start Session and End Session events By default, Amplitude derives `Start Session` and `End Session` events from each session's session ID. Amplitude also uses session ID to calculate session lengths. If you use session IDs, Amplitude doesn't add extra events to your monthly event volume limit. If you need `Start Session` and `End Session` events for analysis beyond session lengths, enable `Start Session` and `End Session` event tracking by adding the following code before initializing the SDK: For Android: ```java Amplitude amplitude = new Amplitude(new Configuration(apiKey = AMPLITUDE_API_KEY, context = applicationContext, trackingSessionEvents = true, )); ``` For iOS: ```objc [Amplitude instance].trackingSessionEvents = YES; ``` For Browser: ```js amplitude.init(API_KEY, OPTIONAL_USER_ID, { defaultTracking: { sessions: true, }, }); ``` ### Start Session and End Session limitations - Session event tracking applies only to Amplitude's [Android](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk), [iOS](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk), and [Browser](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) SDKs. - `Start Session` and `End Session` events count toward your monthly [event volume limit](https://amplitude.com/docs/faq/limits-and-quotas). - Amplitude sends the `End Session` event at the start of the user's next session. - By default, you can't add extra event properties to automatically generated `Start Session` and `End Session` events. To send event properties for session start and end events, you have two options: - Implement your own custom `Open App` and `Close App` events. - Use an [Enrichment Plugin](https://amplitude.com/docs/sdks/sdk-plugins#enrichment-plugins) to add properties to the generated session events. Enrichment plugins let you modify properties in Event objects. ### Out-of-session events You can log events outside a session by setting the session ID to `-1`. Out-of-session events aren't part of the current session and don't extend the current session. Out-of-session events are useful for events triggered by push notifications. Out-of-session events are usually server-side events received by Amplitude. For more information, refer to the [HTTP API](https://amplitude.com/docs/apis/analytics/http-v2) documentation. Out-of-session events appear in a user's event stream as disconnected green squares. ### Configure a custom session definition By default, Amplitude sorts events into sessions by session ID. You can define sessions without adding instrumentation. A custom session definition can use a constant property, a custom timeout window, or beginning and ending events. You need Admin or Manager privileges to edit session definitions. > **Note:** > > Custom session definitions are only available in the User Sessions and Pathfinder charts and user timelines. Sessions only include **active** events. To configure a custom session definition: 1. From the left sidebar, navigate to _Settings > Projects_. 2. Select the project you want to work with. 3. Select **Session Definitions**. The _Session Definitions_ modal appears. 4. Select **Custom Session Definition**. 5. Configure one or more conditions: - **Session property**: Select **Select property...** and choose the event or user property for grouping sessions. - **Starting Event and Ending Event**: Select **Starting Event** or **Ending Event** and choose the events that mark the beginning and end of a session. The ending event ends a session if the ending event occurs before the timeout interval elapses. - **Session timeout**: Enter the default timeout interval in minutes. Amplitude counts events from the same user that occur within the specified timeout interval as part of one session. Amplitude recommends a default of 30 minutes. 6. Enter the confirmation phrase and select **Save**. > **Note:** > > Changing the session definition applies to all User Sessions, Funnel Analysis, and Journeys charts, and to the session metric in your project. Review the impact before you configure or change a custom session definition. Amplitude combines conditions with **and** logic. A session must meet all configured conditions to count. If you don't configure any conditions, Amplitude uses session ID as the session-defining property. To require all events in a session to come from the same source, use session property and timeout window together: - Session property = `device ID` - Session timeout = `30 min` To define sessions based on in-app usage, use starting event and timeout window: - Start event = `app open` - Session timeout = `5 min` ================================================================================ # Track revenue URL: https://amplitude.com/docs/data/sources/instrument-track-revenue ================================================================================ # Track revenue A revenue event captures a purchase using the `price`, `quantity`, `currency`, and `revenue` fields. This page covers how to instrument revenue events with the iOS, Android, and Browser SDKs and the HTTP API so they appear in the [Revenue LTV](https://amplitude.com/docs/analytics/charts/revenue-ltv/revenue-ltv-track-new-user-monetization) chart. Only revenue events that include [revenue properties](#revenue-properties) appear in the chart, which includes both verified and unverified events. To send revenue events, refer to the following documentation: - [iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk) - [Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk) - [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) - [HTTP API](https://amplitude.com/docs/apis/analytics/http-v2). Set the `price`, `quantity`, `currency`, and `revenue` fields to record the event as a revenue event. Amplitude counts only events that you send through the Amplitude ingestion system. Amplitude doesn't count computed events separately. Additional events attached to revenue events, such as `Revenue (Verified)` or `Revenue (Unverified)`, don't count toward your limit. ## Revenue properties Amplitude needs revenue properties to track revenue: - Send `$revenue` directly, or send `$price`. In most cases, include `$quantity`. - Amplitude calculates revenue with the formula `$price * $quantity`. If `$quantity` isn't present, Amplitude uses 1. | Name | Type | Description | Default | | --- | --- | --- | --- | | $revenue | Double | The total revenue from the user's purchase. Negative values are valid. You must send `$revenue` if you want the revenue event to appear in a Revenue LTV chart. | null | | $price | Double | The price of the products purchased. Negative values are valid. | null | | $productId | String | An identifier for the product. | null | | $quantity | Integer | The quantity of products purchased. Defaults to one if not specified. | 1 | | $revenueType | String | The type of revenue, for example, tax, refund, or income. | null | | $currency | String | The currency for the purchased item. Use a three-character uppercase [ISO 4217](https://www.iban.com/currency-codes) code, for example, USD or EUR. | null | | eventProperties | Object | An object of event properties to include in the revenue event. You can only segment on the included event properties in the [Event Segmentation](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-build) chart. | null | You must explicitly send revenue properties using Amplitude's SDKs or server-side when you log revenue events. ## Track non-in-app purchases For purchases that aren't in-app purchases, there are three ways to send revenue data to Amplitude: - Use Amplitude's [SDKs](https://amplitude.com/docs/sdks/analytics) to call the `logRevenueV2` function. The `logRevenueV2` function generates `Revenue` events. - Use Amplitude's SDKs to call the `logEvent` function if you include the `$revenue` property. - Use Amplitude's HTTP API by setting the `price`, `quantity`, or `revenue` fields. Add your own event name, for example, `Purchase completed`. > **Note:** > > Amplitude performs verified revenue checks only for in-app purchases. ## Track in-app purchases (IAPs) To track IAPs, send revenue events the same way you send regular revenue events, using `logRevenueV2` or `logEvent` (with the `$revenue` property) in Amplitude's SDKs. For IAPs, you can validate purchases by passing receipt data with the revenue event. ### Enable revenue verification To enable revenue verification, copy your iTunes Connect In App Purchase Shared Secret or your Google Play License Public Key into the Sources section of your project in Amplitude Data. You must include a key for each Amplitude project where you want revenue verification. You also need to pass in receipt data for Amplitude to verify the revenue event. Amplitude can create three revenue event types from the SDK `logRevenue` call. The SDK revenue event types are separate from revenue events sent server-side through the HTTP API: | Event type | Description | | --- | --- | | `Revenue` | Amplitude logs `Revenue` for revenue events, whether revenue verification is on or off. The `Revenue` event doesn't populate the `$revenue` property. `Revenue (Verified)` and `Revenue (Unverified)` events populate `$revenue`. To include SDK revenue events in a Revenue LTV chart, turn revenue verification on. If revenue verification is on and the user activity stream shows only `Revenue`, the revenue failed verification. | | `Revenue (Verified)` | Amplitude logs `Revenue (Verified)` for legitimate transactions. The count difference between `Revenue` and `Revenue (Verified)` is the number of illegitimate app purchases. By default, revenue events recorded on SDKs appear in Amplitude dashboards as unverified revenue events. To generate `Revenue (Verified)` events, enable revenue verification. | | `Revenue (Unverified)` | An unverified revenue event didn't necessarily fail verification. An unverified event means Amplitude didn't attempt verification because the event came through the HTTP API or JavaScript SDK, or because your project didn't include revenue verification keys. If revenue verification is off, Amplitude logs `Revenue (Unverified)` for all revenue events. | > **Note:** > > You can switch verification on or off only for mobile. Web always tracks `Revenue` and `Revenue (Unverified)`. Amplitude displays revenue that doesn't fail verification. You may see both `Revenue (Verified)` and `Revenue (Unverified)` if, for example, you send both mobile and web revenue events through Amplitude SDKs. ### Receipt validation Amplitude validates in-app purchases based on the receipt from [Apple](https://developer.apple.com/library/content/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html#//apple_ref/doc/uid/TP40010573-CH104-SW1) or [Google](https://developer.android.com/google/play/billing/billing_integrate.html#Purchase). ### Discrepancies Discrepancies between app store reports and Amplitude can come from time zone differences, event generation bugs, or piracy. If the discrepancy is minor and consistent day to day, the most likely cause is a time zone difference between the app store and Amplitude. Amplitude uses UTC. If the app store uses a different time zone, the app store may report a purchase event on a different day than Amplitude. No data is lost. Major discrepancies can come from client-side errors, such as the store purchase callback running multiple times for a single purchase. Call revenue events only after a successful store purchase. The following calls track the event property and revenue amount: ```plaintext AmplitudeClient.getInstance().logEvent('IAP', {type='Sale Special'}) ``` ```plaintext AmplitudeClient.getInstance().logRevenueV2("com.company.productid", 1, 2.99) ``` Piracy can also cause major discrepancies. Users can circumvent the app store and make purchases that don't appear in app store reports. To exclude pirated revenue events from your data, use Amplitude's revenue verification method. If you suspect piracy heavily skews your data, contact [Amplitude Support](https://help.amplitude.com/hc/en-us/requests/new). ### Considerations for developers Review the following points when you track revenue events: - Backward compatibility: The existing `logRevenue` methods still work but are deprecated. Events logged with the old methods miss fields such as `revenueType`, so the Amplitude platform limits segmentation on those revenue events. - Opting users out of logging: You can turn off logging for a given user by calling `setOptOut`: ```plaintext amplitude.getInstance().setOptOut(true); ``` Amplitude doesn't save or send events to the server while opt out is enabled. The opt out setting persists across page loads. You can reenable logging by calling: ```plaintext amplitude.getInstance().setOptOut(false); ``` ================================================================================ # Track unique users URL: https://amplitude.com/docs/data/sources/instrument-track-unique-users ================================================================================ # Track unique users Amplitude counts unique users by combining three identifiers (device ID, user ID, and Amplitude ID) into a single profile across anonymous sessions, sign-ins, and multiple devices. Send a stable user ID as soon as a person authenticates so anonymous events on the same device merge into one profile and your active-user counts stay accurate. ## How Amplitude identifies unique users The three IDs work like this: - **Device ID:** For mobile applications, Amplitude pulls the Identifier for Vendors, [IDFV](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#advertiser-id), or generates a random alphanumeric string for the device ID. For web applications, Amplitude sets the device ID to a randomly generated Universally Unique Identifier, [UUID](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk#set-a-custom-device-id), by default. The device ID persists unless a user clears browser cookies or browses in private mode. - **User ID:** You configure the user ID. Many products use a username or an internal unique identifier as the user ID. Use a stable value for the user ID. Don't assign anonymous users a user ID. Anonymous users still have Amplitude IDs and device IDs, so Amplitude might recognize them as the same user later. - **Amplitude ID:** After Amplitude receives a device ID, a user ID, or both, Amplitude generates the Amplitude ID and associates it with the collected identifiers. Amplitude needs only one identifier to generate an Amplitude ID. Amplitude prefers the user ID because multiple unique users could share the same device. > **Note:** > > If Amplitude encounters a known device ID that is already tied to a user ID in a different project, Amplitude assumes the device ID is tied to that user ID in all projects, even if you don't have the Portfolio add-on. For more information, refer to [Portfolios](https://amplitude.com/docs/admin/account-management/portfolio). When multiple projects reside in a single organization, all projects **must** use the same variable as the user ID. Using the same user ID variable prevents tracking discrepancies. For example, if one project uses email addresses as user IDs and another project uses phone numbers, Amplitude doesn't merge those identifiers into the same Amplitude user profile. If you're on [MTU billing](https://amplitude.com/docs/admin/billing-use/mtu-guide), you might incur charges for multiple users. ### Use advertising identifiers as the device ID You can configure Amplitude to use the Identifier for Advertiser, [IDFA for iOS](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk), and the Advertising Identifier, [AdID for Android](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk), as the device ID. For more information, refer to the relevant SDK installation guide. Using advertising identifiers causes the device ID to persist across installs. iOS users can reset the IDFA on their devices at any time. As of iOS 10, if a user limits ad tracking, iOS returns an IDFA of all zeros. Amplitude instead sets the device ID to either the IDFV or a randomly generated string. Android users can reset the AdID on their devices at any time. ### Set up cross-domain tracking You can track anonymous behavior across two domains. For example: - Site 1: `https://www.landingpage.com`. - Site 2: `https://www.productpage.com`. To track an anonymous user who starts on Site 1 and navigates to Site 2, pass both the device ID and session ID from Site 1 as URL parameters to Site 2. Passing only the device ID preserves anonymous identity but doesn't maintain session continuity. Sessions that split across the domain boundary can distort session-based metrics like traffic source analysis. For Browser SDK 2 (`@amplitude/analytics-browser` v2.8.0 and later): 1. From Site 1, get the device ID from `amplitude.getDeviceId()` and the session ID from `amplitude.getSessionId()`. 2. Pass both values to Site 2 as URL parameters when the user navigates. For example: `https://www.productpage.com?ampDeviceId=DEVICE_ID&SessionId=SESSION_ID`. 3. Initialize the Amplitude SDK on Site 2 with `amplitude.init('YOUR_API_KEY')`. The SDK reads `ampDeviceId` and `ampSessionId` from the URL automatically. > **Note:** > > A custom time-based session definition can supplement session-based reporting, but it doesn't replace passing `ampSessionId` for true SDK session continuity across domains. For full implementation details, refer to [Cross-domain tracking](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#cross-domain-tracking) in the Browser SDK 2 documentation. ## How Amplitude assigns Amplitude IDs The following scenarios show how Amplitude uses device IDs and user IDs to generate a new Amplitude ID or apply an existing Amplitude ID. ### No user ID exists If your product doesn't assign user IDs, Amplitude generates an Amplitude ID when Amplitude sees a particular device ID for the first time. | Device ID | **User ID** | **Amplitude ID** | | --- | --- | --- | | A | null | 1 | | B | null | 2 | | B | null | 2 | | C | null | 3 | | A | null | 1 | | C | null | 3 | There are three unique users in this set. The first event from each device gets a new Amplitude ID. Later events from the same device reuse the existing Amplitude ID. In this example, device A uses Amplitude ID 1, device B uses Amplitude ID 2, and device C uses Amplitude ID 3. ### User ID follows anonymous events If your product assigns user IDs, Amplitude assumes previous anonymous events on that device belong to a single user until Amplitude receives an event with a user ID. Amplitude then applies the same Amplitude ID to the anonymous events and the identified event. | **Device ID** | **User ID** | **Amplitude ID** | | --- | --- | --- | | G | null | 4 | | G | null | 4 | | G | John | 4 | There is one unique user in this set. Amplitude logs the first two events anonymously on device G and assigns them Amplitude ID 4. The third event is the first event from device G that includes a user ID. Amplitude assigns John the same Amplitude ID as the anonymous events, so Amplitude counts one unique user. ### Same user ID on multiple device IDs, with _no_ anonymous events Amplitude prioritizes user IDs over device IDs when assigning an Amplitude ID. | **Device ID** | **User ID** | **Amplitude ID** | | --- | --- | --- | | K | Zack | 5 | | L | Zack | 5 | There is one unique user in this set. User Zack sent an event on device K, and Amplitude assigned Amplitude ID 5. Whenever Zack's user ID appears again on **any** device, Amplitude assigns the event Amplitude ID 5, regardless of the device ID. ### Multiple user IDs on the same device If Amplitude receives an anonymous event **after** at least one user ID has appeared on that device, Amplitude assumes the last known user sent the anonymous event and assigns the event that user's Amplitude ID. | **Device ID** | **User ID** | **Amplitude ID** | | --- | --- | --- | | R | Jane | 6 | | R | null | 6 | | R | Mary | 7 | | R | null | 7 | | R | null | 7 | There are two unique users in this set. Jane logs the first event on device R, and Amplitude assigns Amplitude ID 6. Amplitude receives the next event anonymously, for example after Jane logs out, but still assigns Amplitude ID 6 because Jane was the last known user. Mary sends the third event on device R, and Amplitude assigns Amplitude ID 7. Amplitude receives the next two events anonymously and assigns them Amplitude ID 7. Amplitude assumes Mary sent those events because she was the last known user. If you want to explicitly log users out or log events under an anonymous user, set the user ID to null and regenerate a new device ID. Follow the instructions in the [iOS](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk) or [Android](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk) SDK documentation. ### Same user ID on multiple devices, with anonymous events | **Device ID** | **User ID** | **Amplitude ID** | | --- | --- | --- | | Y | David | 8 | | Z | null | 9 | | Z | David | 8 | | Z | null | 8 | David logs an event on device Y, and Amplitude assigns Amplitude ID 8. Next, an anonymous user logs an event on device Z, and Amplitude assigns Amplitude ID 9 because no user is associated with the device. Then David logs into the product on device Z. The sign-in event has Amplitude ID 8 because Amplitude ID 8 belongs to David. Finally, Amplitude logs an event anonymously on device Z. The anonymous event receives Amplitude ID 8. David was the last known user, so Amplitude attributes the event to him. In this scenario, the anonymous events on device Z have two different Amplitude IDs, even though only one user ID is associated with the device. Amplitude interprets Amplitude IDs 8 and 9 as a single user: David. When Amplitude detects the relationship between Amplitude IDs 8 and 9, Amplitude **merges** the IDs, so Amplitude counts only one user. The merge can only happen because the event with Amplitude ID 9 didn't have a user ID present. > **Note:** > > If you're using Redshift, the data is immutable, and the anonymous event still has Amplitude ID 9 in the raw data. For more information, refer to [Merged users](#merged-users). ## Merged users Merged users occur when Amplitude determines that an anonymous user, such as a user whose only ID is a device ID, is a recognized user with an Amplitude ID. For example, a user gets a new device and logs events in your product anonymously before signing in. To Amplitude, these anonymous events look like they come from a new user, so Amplitude maps them to a new Amplitude ID. When the user logs into their existing account, Amplitude maps all subsequent events to that user's existing Amplitude ID. The separate Amplitude IDs create two problems: - Amplitude counts the user twice in active and new user counts. - Amplitude doesn't attribute events received while the user was anonymous to the true Amplitude ID and the user's actual user ID. Amplitude solves duplicate Amplitude IDs by cross-referencing the list of Amplitude IDs with an internal mapping of merged Amplitude IDs. Merged Amplitude IDs belong to the same user. Amplitude applies merged user mapping when you query on the dashboard. You can view a list of a user's merged IDs in their User Activity page, along with the merge times. > **Note:** Important note > > - Amplitude can't merge user IDs. If you create a new user ID for an existing user, Amplitude recognizes them as different unique users. > - Merged user mapping doesn't apply to raw data in Amazon [Redshift](https://amplitude.com/docs/data/destination-catalog/amazon-redshift), because the database contains raw event logs and not a merged users table. Without merged user mapping, Amplitude has observed an average change of about 5% in DAU numbers, with a higher-than-average change for web data. ### Event IDs, device IDs, and merging users After Amplitude merges users, the event ID count continues on a device-by-device basis: | **Device ID** | **User ID** | **Amplitude ID** | **Event ID** | | --- | --- | --- | --- | | A | null | 8 | 1 | | A | David | 8 | 2 | | A | David | 8 | 3 | | B | null | 9 | 1 | | B | David | 8 | 2 | | B | David | 8 | 3 | If a user clears product data, for example by deleting and reinstalling the app, the event ID resets to 1. When a user deletes and reinstalls the app, Amplitude usually generates a new device ID as well, which then triggers a new merge. After Amplitude merges users, a merged user might lose user property values that should stay unchanged, such as `Start Version` or initial UTM parameters, because the new user property values overwrite the original user property values. If merged users affect your user property values, contact Amplitude Support. ================================================================================ # Connect to a Destination URL: https://amplitude.com/docs/data/destinations ================================================================================ # Connect to a Destination Amplitude Data makes it easy to set up third-party platforms as data export destinations. You can share data generated in Amplitude with other tools and stakeholders in a variety of contexts. ## Add a destination To add a new data destination, follow these steps: 1. From Amplitude Data, open the **Destinations** tab in the Connections section. 2. Click **Add Destination**. 3. Look for the tile or search for the name of the destination you want to add and click to select it. 4. Enter the requested information into the pop-up modal. The specific information required varies from destination to destination. 5. Click **Save**. ## Destination notifications Notifications alert you when you have an issue with your destination. By default, new destinations notify the creator and your Admins. ### Edit your notifications 1. Click **Destinations**. 2. Find the destination you want to configure notifications for, then click to select it. 3. Hover over the **Notifications Button** with an email icon on it. Click the **Manage Notifications** button when it appears. 4. From the Manage Notifications settings, you can **Subscribe** or **Unsubscribe** yourself. You can also manage notifications to add or remove other email addresses. ### Add notifications to Slack 1. Follow [this guide](https://slack.com/help/articles/206819278-Send-emails-to-Slack#h_01F4WDZG8RTCTNAMR4KJ7D419V) to set up an email for your Slack channel or DM. 2. After your Slack/email integration is complete, edit your [notifications](#edit-your-notifications) to add that email to your destination's notifications. ================================================================================ # Streaming transformations URL: https://amplitude.com/docs/data/streaming-transformations ================================================================================ # Streaming transformations Streaming transformations send transformed data from your Amplitude taxonomy, including custom events, derived properties, transformed events, and transformed properties, to your event streaming destinations, so downstream tools receive cleaned and enriched data instead of raw events. Select any transformation when you configure event streaming. You must define the transformation in Amplitude Data before you can stream it. Refer to [Transformations](https://amplitude.com/docs/data/transformations) to create custom events, derived properties, and other transformation types. ## Setup 1. In Amplitude Data, click **Catalog** and select the **Destinations** tab. 2. In the Event Streaming section, click on any streaming destination tile. 3. Enter a sync name, then click **Create Sync**. 4. Toggle _Status_ from **Disabled** to **Enabled**. 5. Paste your destination's Server Secret Key. 6. Toggle **Send events** to enable event streaming. 7. In _Select and filter events_, choose which events to send. Select only the events needed for your downstream destination. The dropdown includes any transformed events from your taxonomy. 8. (_optional_) In _Select additional properties_, select any event properties (including transformed event properties) to include. By default, Amplitude doesn't send any additional properties unless you explicitly select them. 9. (_optional_) In _Select additional user properties_, select any user properties to include. By default, Amplitude doesn't send any additional user properties unless you explicitly select them. 10. When satisfied with your configuration, click **Save**. ## Example use cases ### Streaming renamed events to AppsFlyer AppsFlyer requires unique event names for attribution and doesn't support event properties. Previously, you had to create custom events in your backend and resend them to Amplitude. You can now use Amplitude Data to rename events before streaming them to AppsFlyer, which reduces duplicate ingestion. ### Streaming derived properties to Braze To improve campaign effectiveness, you can stream derived properties from Amplitude to Braze. Select derived properties in your sync filters and include them when configuring additional properties. This enables more targeted campaigns using enriched event data from Amplitude. ## Considerations Note the following when streaming transformations from Amplitude: - Amplitude sends selected event and user properties along with the event. - Amplitude targets an end-to-end p95 latency of 60 seconds. Amplitude streams 95% of events within 60 seconds. Amplitude has internal processes, monitors, and alerts in place to meet this target. ## Transformation payload structure The streaming payload includes transformations as nested JSON fields. Understanding this structure is essential when using custom FTL (FreeMarker Template Language) templates or configuring how your destination receives data. ### Selection requirement You must explicitly select transformations in your sync configuration to include them in the streaming payload. You can select transformations in: - _Select and filter events_: For example, filtering events where a derived property isn't `null`. - _Select additional properties_: To include specific transformed properties. - _Map properties to destination_: When mapping properties to your destination's schema (if applicable). The streaming payload only includes transformations you explicitly select. ### JSON structure The payload includes transformations as nested JSON objects. The top-level field name depends on the transformation type: | Transformation Type | Top-level JSON Field Name | | --- | --- | | Merged properties | N/A (replaced in original field) | | Derived properties | `derived_properties` | | Channel properties | `derived_properties` | | Lookup properties | `lookup_properties` | Field names within these objects match the transformation names displayed in the Amplitude UI. ### Example payload If you select a derived property called `sample_derived_property_key1`, the streaming payload looks like this: ```json { "event_type": "Button Clicked", "user_id": "12345", "derived_properties": { "sample_derived_property_key1": "whatever_value" } } ``` ### Using transformations with custom FTL If your destination uses custom FTL templates, you can access transformation data using these patterns. **Example 1: Using FtlUtils to serialize derived properties** ```ftl <#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']> { "version": "derived_properties_sample_ftl1", "derived_properties": ${UtilClass.toJson(input.derived_properties)} } ``` **Example 2: Manually iterating over derived properties** ```ftl <#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']> { "version": "derived_properties_sample_ftl2", "derived_properties": { <#list input.derived_properties?keys as key> "${key}": "${input.derived_properties[key]}"<#sep>,</#sep> </#list> } } ``` ## Customize payloads with FreeMarker (FTL) Event streaming destinations that expose a custom payload editor use [Apache FreeMarker](https://freemarker.apache.org/) (FTL) to turn the Amplitude event into the JSON body your destination expects. The editor in the connector builder provides autocomplete, hover documentation, and inline validation for the fields and helpers below. For the FreeMarker language itself, refer to the [guide to creating templates](https://freemarker.apache.org/docs/dgui.html). ### The input object `input` is the event (or user) Amplitude forwards. Access its fields with dot notation, wrapped in `${ }` to output the value: ```ftl "${input.user_id}" "${input.event_type}" "${input.event_time}" ``` Commonly available fields include `event_type`, `user_id`, `device_id`, `time`, `event_time`, `session_id`, `platform`, `event_properties`, `user_properties`, `group_properties`, and `groups`, plus any transformations you select (`derived_properties`, `lookup_properties`). For the complete shapes, refer to the [event format](https://amplitude.com/docs/apis/analytics/export) and [user (Identify) format](https://amplitude.com/docs/apis/analytics/identify). > **Warning:** Fields aren't guaranteed > > `input` fields depend on how each user instruments events, and a selected event property might not be present on every event you stream. Reference fields defensively (refer to [Handle missing fields](#handle-missing-fields)), and keep required-field usage to common fields like `user_id`, `event_type`, and `event_time`. The payload editor flags a referenced property that isn't present on all of the events you selected. ### Dot and bracket notation Use dot notation when a property name is a valid identifier, and bracket notation when the name contains spaces or other special characters: ```ftl ${input.event_properties.plan} ${input.event_properties["Plan Type"]} ``` ### Handle missing fields Because fields aren't guaranteed, guard against missing values: - `??` tests whether a value exists: `<#if input.user_id??>…</#if>`. - `!` supplies a default when a value is missing: `${input.user_properties.email!}` (empty string) or `${input.revenue!0}`. ```ftl { <#if input.user_id??> "external_id": "${input.user_id}", </#if> "email": "${input.user_properties.email!}" } ``` ### Useful built-ins FreeMarker built-ins (`?name`) transform values. Common ones for JSON payloads: | Built-in | Use | | --- | --- | | `?c` | Format a number for computers, with no locale grouping or scientific notation. Use for numeric JSON values: `${input.revenue?c}` | | `?json_string` | Escape a string for safe use inside a JSON string: `"${value?json_string}"` | | `?keys` | Get an object's keys to iterate with `<#list>` | | `?is_number`, `?is_boolean`, `?is_string` | Test a value's type before serializing it | ### Iterate over properties Use `<#list>` with `?keys`, and `<#sep>` to place commas between items only: ```ftl "user_properties": { <#list input.user_properties?keys as key> "${key}": ${UtilClass.toJsonString(input.user_properties[key])}<#sep>,</#sep> </#list> } ``` ### Helper methods (FtlUtils) Amplitude exposes helper methods for serializing values and other common transforms, so you don't have to hand-write the logic. Assign the helper once at the top of the template, then call its methods: ```ftl <#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']> { "user_properties": ${UtilClass.toJson(input.user_properties)} } ``` | Method | Returns | Description | | --- | --- | --- | | `toJson(value)` | string | Serializes a value to JSON. Maps, lists, and JSON values become JSON; scalars become a quoted JSON string (for example, `42` becomes `"42"`). | | `toJsonString(value)` | string | Alias of `toJson`. | | `dateStringToIso(dateTime)` | string | Converts an Amplitude datetime string to ISO 8601. | | `dateStringToEpochSeconds(dateTime)` | number | Converts an Amplitude datetime string to epoch seconds. | | `dateStringToEpochMillis(dateTime)` | number | Converts an Amplitude datetime string to epoch milliseconds. | | `epochSecondsToIso(seconds)` | string | Converts epoch seconds to ISO 8601. | | `epochSecondsTextToIso(text)` | string | Converts epoch seconds provided as text to ISO 8601. | | `epochMillisToIso(millis)` | string | Converts epoch milliseconds to ISO 8601. | | `isValidEmail(value)` | boolean | Returns whether the value is a valid email address. | | `sha256(value)` | string | Returns the SHA-256 hash of the value. If the value is already a 64-character hash, returns it unchanged. | | `cleanJsonPropertyName(name)` | string | Replaces whitespace with underscores and removes other non-alphanumeric characters. | | `getDisjointMap(source, filter)` | map | Returns the entries of `source` whose keys aren't present in `filter`. | > **Note:** Destination-specific helpers > > Some destinations provide additional helper methods tailored to that destination. You can use those helpers only in that destination's template. ### Examples Each example shows the **input** event Amplitude forwards, the **template** you write, and the **result** Amplitude sends to your destination. #### Simple: rename and pick fields Map a few input fields into the shape your destination expects. Input event: ```json { "event_type": "Song Played", "user_id": "user-123", "event_time": "2024-01-15T09:30:00.000", "event_properties": { "song_id": "abc-987" } } ``` Template: ```ftl { "external_id": "${input.user_id}", "name": "${input.event_type}", "song": "${input.event_properties.song_id}" } ``` Result: ```json { "external_id": "user-123", "name": "Song Played", "song": "abc-987" } ``` #### Complex: guards, bracket notation, and iteration Guard an optional field with `??`, read a property whose name has a space with bracket notation, format a number with `?c`, and serialize all user properties by looping with `<#list>`, emitting numbers and booleans raw and everything else through `toJsonString`. Input event: ```json { "event_type": "Purchase Completed", "user_id": "user-123", "revenue": 12.5, "event_properties": { "Item Name": "Pro Plan" }, "user_properties": { "email": "alex@example.com", "plan": "pro", "age": 30 } } ``` Template: ```ftl <#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']> { "event": "${input.event_type}", <#if input.user_id??> "user_id": "${input.user_id}", </#if> "item": "${input.event_properties["Item Name"]}", "revenue": ${input.revenue?c}, "traits": { <#list input.user_properties?keys as key> <#assign value = input.user_properties[key]> "${key}": <#if value?is_number || value?is_boolean>${value}<#else>${UtilClass.toJsonString(value)}</#if><#sep>,</#sep> </#list> } } ``` Result: ```json { "event": "Purchase Completed", "user_id": "user-123", "item": "Pro Plan", "revenue": 12.5, "traits": { "email": "alex@example.com", "plan": "pro", "age": 30 } } ``` ## Supported custom events Amplitude supports streaming custom events that meet specific criteria. When you create custom events in the Amplitude taxonomy, you can select them for event streaming if they have: - **Supported properties**: User properties and event properties only. - **Supported operators**: `is`, `is not`, `contains`, and `does not contain`. Custom events that use other property types or operators aren't available for selection in event streaming configurations. ## Limitations Streaming transformations from Amplitude has some limitations: - When you rename custom events or derived properties, update any existing sync configurations that reference them. Syncs require current event and property names to work properly. Note that changing the underlying definition of a transformation doesn't affect syncing. Only name changes require sync updates. - **Lookup properties**: You can stream lookup properties by requesting access from Amplitude. Lookup properties map existing event or user properties to new properties using a CSV file upload and can enrich already-ingested events at query time. - Lookup property files with over 1000 rows don't display in the streaming setup. - After you save a lookup property file, it can take up to one hour to populate into the streaming system. - **Channel classifiers**: To stream channel classifiers, request access from Amplitude. Channels act like derived properties applied in real time during queries. Marketers primarily use channels to define acquisition channels based on UTM and referrer data. By default, you can't select channel properties in sync configuration (event filters or additional properties) unless Amplitude has already enabled this feature for your organization. - You can stream transformations to all streaming destinations except Data Warehouse destinations. - The streaming setup doesn't support the following transformation types: - Custom events that don't meet the criteria in the [Supported custom events](#supported-custom-events) section. - Group properties. - Cart properties. - Nested properties (for example, derived properties that rely on other derived properties). Exception: the UI allows selecting nested properties based on merged or cart properties, but they don't work in practice. ## FAQ #### Does this impact my event volume streaming limit? Yes, streaming transformations count towards your existing event streaming volume limit. Check your event streaming limit by navigating to _Settings > Plans & Billing_. #### Can I select both raw and transformed events/properties? Yes, you can select both raw and transformed versions in your streaming sync. For example, if a transformation merges three event types into one transformed event, all four event types (the three originals plus the merged version) appear in the selection dropdown. #### How does Amplitude handle custom events and transformed properties during streaming? Custom events and transformed properties follow the configurations set in your Amplitude Data taxonomy. Amplitude applies transformations before it streams the data to the destination. #### How can I enable channel classifiers for my event stream? Amplitude can enable channel classifier selection in event streaming sync configurations on request. Email integrations@amplitude.com with your organization ID and app IDs to request access. ================================================================================ # Sync Cohorts with Destinations URL: https://amplitude.com/docs/data/sync-cohorts-with-destinations ================================================================================ # Sync Cohorts with Destinations Cohort sync pushes cohorts to third-party [destinations](https://amplitude.com/docs/data/destination-catalog) such as ad networks, attribution providers, and marketing automation platforms. Amplitude offers three cadences: a one-time export, a scheduled hourly or daily refresh, and a real-time stream that checks for updates every minute. The cadence you pick also determines which destinations accept the sync. ## One-time sync Use a one-time sync to send a cohort to your destination once. Use this option if you need to export a cohort to the destination and don't require continuous updates. ## Scheduled sync Use a scheduled sync to send cohort updates to your destination on an **hourly** or **daily** basis. Amplitude queues sync jobs throughout the hour or day, depending on your selection. You can't select the time of day that a sync occurs. > **Note:** Scheduled sync timing > > Amplitude schedules a time to sync the cohort as soon as you create a new cohort or update the sync details. > > The first sync occurs right after Amplitude schedules it. The first two syncs may occur more frequently than every 24 hours. > > If you don't update the sync, future sync jobs run around the same time within the time period. ## Real-time sync Use a real-time sync to keep the destination updated with the most recent cohort information. Real-time sync checks for updates and sends them to the destination every minute. Amplitude recommends real-time syncs for cohorts that require minute-by-minute precision and don't change by a large number of users from minute to minute. If you choose real-time syncing and notice in the sync history that most syncs update `0` users, hourly sync may work better for your use case. > **Warning:** Real-time sync limitations > > Real-time sync supports cohorts of 1,000,000 users or fewer, and all cohort types except: > > - Funnel > - Retention > - Stickiness > - Nth time event > - Event within > - Distinct interval > > Real-time sync supports all cohort destinations except: > > - [Facebook Ads](https://amplitude.com/docs/data/destination-catalog/facebook-ads) > - [Google Ads](https://amplitude.com/docs/data/destination-catalog/google-ads-cohort-syncing) > - [Twitter (X) Ads](https://amplitude.com/docs/data/destination-catalog/twitter-ads-cohort) > - [Hubspot](https://amplitude.com/docs/data/destination-catalog/hubspot-cohort-sync) > - [Qualtrics](https://amplitude.com/docs/data/destination-catalog/qualtrics) > - [S3 cohort sync](https://amplitude.com/docs/data/destination-catalog/amazon-s3-cohort) > - [TikTok Ads](https://amplitude.com/docs/data/destination-catalog/tiktok-ads) > - [Enterpret](https://amplitude.com/docs/data/destination-catalog/enterpret) > - [SFMC](https://amplitude.com/docs/data/destination-catalog/salesforce-marketing-cloud-v2) > - [The Trade Desk](https://amplitude.com/docs/data/destination-catalog/thetradedesk) ================================================================================ # DataGrail URL: https://amplitude.com/docs/data/pii/datagrail ================================================================================ # DataGrail > **Note:** > > For feedback on this integration or documentation, contact [support@datagrail.io](mailto:support@datagrail.io). [DataGrail](http://www.datagrail.io) is a privacy management platform for system detection and automated data subject request (DSR) fulfillment. DataGrail supports compliance with privacy laws and regulations such as GDPR, CCPA, and CPRA. The Amplitude integration helps privacy owners identify, retrieve, and delete PII from Amplitude. ## Before you begin - If you don't have admin rights in Amplitude, you can't complete the DataGrail integration. Contact your Amplitude Admin for help. - You need a paid DataGrail plan. ## Copy Amplitude credentials Copy the Amplitude API key and Secret Key for your project. Amplitude doesn't require other setup steps. ## Configure DataGrail For detailed setup information, refer to the help documentation while logged in to DataGrail. 1. Log in to the DataGrail Portal. 2. Select **Integrations** on the navigation bar, then select **Configure New Integration**. 3. Search for Amplitude by name, then select **Configure**. 4. Enter the API Key and Secret Key. 5. Select **Save Connection** to complete the setup. Your Amplitude integration is now active. Contact DataGrail's support team ([support@datagrail.io](mailto:support@datagrail.io)) with questions. ================================================================================ # Osano URL: https://amplitude.com/docs/data/pii/osano ================================================================================ # Osano [Osano](https://www.osano.com/) is a data privacy platform that helps you manage website compliance with laws such as GDPR and CCPA. Osano monitors the vendors that receive your data. Osano connects to Amplitude with a one-click integration. Osano then discovers and automatically classifies the personal data that Amplitude stores. After Osano finishes discovery and classification, you can include Amplitude in subject rights request searches. > **Note:** > > For feedback on this integration or documentation, contact [Osano's support team](https://www.osano.com/company/contact). ## Before you begin - The Osano integration requires an Osano Enterprise plan. ## Copy Amplitude credentials Copy the Amplitude API key and Secret Key for your project. Amplitude doesn't require other setup steps. ## Configure Osano 1. Log in to the Osano Portal. 2. From the **Data Discovery** menu, open the **Data Stores** page. 3. Select **+** to add a new data store. 4. Select **Connect to third-party vendors to enable automated data discovery**. 5. Select **Amplitude** from the dropdown menu. 6. Paste the Amplitude API key into **API Key**. 7. Paste the Amplitude Secret Key into **Secret Key**. 8. Select a **Data Store Owner** from the dropdown menu. 9. Save your changes. When you save, Amplitude and Osano immediately begin syncing to detect PII. Manage PII detection results from Osano. ================================================================================ # Transcend URL: https://amplitude.com/docs/data/pii/transcend ================================================================================ # Transcend [Transcend](https://transcend.io/) is a privacy platform for data transparency, consent, and control. Transcend lets you programmatically access and erase user device activity in Amplitude to comply with data privacy regulations such as GDPR and CCPA. > **Note:** Partner-maintained integration > > For feedback on this integration or documentation, contact [Transcend's support team](https://transcend.io/integration/amplitude/). ## Configure Transcend For setup instructions, refer to the [Transcend documentation](https://transcend.io/integration/amplitude/). ================================================================================ # Missing or unexpected data URL: https://amplitude.com/docs/data/troubleshooting/missing-data ================================================================================ # Missing or unexpected data This page diagnoses three common data problems: a chart that shows fewer events than you expect, user counts that look inflated or too small, and Amplitude numbers that don't match another platform. Each section below covers a common cause and how to fix it. ## Why an event or property is missing Even when you successfully send data to Amplitude, the event or property may not appear in analysis. The following sections cover common causes. ## Your project reached the instrumentation limit If your project hits its [instrumentation limit](https://amplitude.com/docs/faq/limits-and-quotas), Amplitude can't query data for any event types and event or user properties that exceed the limit. You can only access this data by exporting raw data through a CSV file or Amplitude's [Export API](https://amplitude.com/docs/apis/analytics/export). To get back under the limit, [delete unneeded event types in Amplitude Data](https://amplitude.com/docs/data/remove-invalid-data). After you're under the limit, the new event types, event properties, and user properties take approximately 24 hours to appear in Amplitude. ## Someone hid, blocked, or deleted the data Someone may have hidden, blocked, or deleted the expected data. Review the [differences between those actions](https://amplitude.com/docs/data/remove-invalid-data) from your `main` branch so Amplitude ingests the data properly. > **Note:** > > Hidden or blocked events and properties still count toward your project's [instrumentation limit](https://amplitude.com/docs/faq/limits-and-quotas). Deleted events and properties don't. The data may also have a name you don't expect, or have a [display name](https://amplitude.com/docs/data/display-names-in-amplitude-data) you're not familiar with. To adjust the name, refer to the article on [making retroactive changes to your data](https://amplitude.com/docs/data/transformations). ### Hidden events An event may appear in an event stream but not in a chart. The cause is usually a filter (such as a drop filter) or someone hiding the event from view in Amplitude Data. > **Note:** > > You can also [hide](https://amplitude.com/docs/data/troubleshooting/instrumentation-issues#hide-block-or-delete-an-event-or-property) events and properties from drop-downs, Pathfinder results, and Personas charts. ## Schema doesn't include unplanned data The missing data might count as unplanned. Unplanned data conflicts with your current schema settings, so Amplitude doesn't know how to handle it. Verify that your project's tracking plan accepts [unplanned events or properties](https://amplitude.com/docs/data/configure-schema). If it doesn't, Amplitude doesn't store the event or its properties. ## Data ingestion or access delays If event or property data appears for some users but not others, data ingestion can lag. For example, when a [Mobile SDK](https://amplitude.com/docs/sdks/sdk-maintenance-and-support) sends data to Amplitude, events may not appear immediately. The user may not have an internet connection, or the SDK may not have reached its event upload threshold. > **Note:** > > By default, Amplitude's Mobile SDKs have an event upload threshold of 30 seconds or 30 events. The SDK doesn't send event data until it reaches the threshold. New or modified user properties sent through the [Identity API](https://amplitude.com/docs/data/user-properties-and-events) can also experience ingestion delays. ## Unexpected values in user counts When you group events by an event or user property, some results may appear in a group called `(none)`. In Amplitude, `(none)` represents a null value. The following sections explain why users have null or unexpected property values. ### Why your event property appears in the `(none)` bucket Amplitude is an event-based analytics platform, and all charts and cohorts query at the event level. Charts return the event property value at the time of an event. Because an event property is a component of an event, event property values can be unique at the event level. If you send an event with a null value at the time of the event, grouping by that event property places some events or users in the `(none)` bucket. For example, User A triggered `Send Message` once on January 1st and once on February 1st. You instrumented the `Audience` event property on January 15th, so the property wasn't available when User A triggered `Send Message` on January 1st. The `Audience` property accepts only `Default` and `Mentioned_Contacts`. When User A sent `Send Message` on February 1st, the event had `Audience = Default`. Amplitude counts User A once in the `Default` bucket and once in the `(none)` bucket. User A had `Audience = Default` at the time of the February 1st event, and `Audience = (none)` at the time of the January 1st event. Amplitude sorts events and users according to the property value sent at the time of the event. ### Why your user property doesn't show the expected value Like event properties, charts return the user property value at the time of an event. Amplitude stores user properties in a separate table, then applies them to events. When a user's property values update, the user property values attached to historical events don't change. ### Why your custom property shows a null value Custom user properties attached to events reflect the user property values present at the time of the event. For example, you instrumented a user property called `Account_Type` on January 15th. User A is a registered user with an account type of `Shopper`. User A triggered `Add Item to Cart` once on January 1st and once on February 1st. Because you didn't instrument `Account_Type` until January 15th, all events triggered before January 15th have a null value for `Account_Type`. Amplitude counts User A once in the `(none)` bucket and once in the `Shopper` bucket. When measuring Uniques, Amplitude deduplicates users within each unique bucket. If User A triggered `Add Item to Cart` with their `Shopper` account type on both February 1st and February 2nd, Amplitude still counts User A only once in the `Shopper` bucket. The same logic applies for non-null user property values. Amplitude sorts events and users by the property value applied at the time of the event. Amplitude uses this logic because user attributes can change over time. `City`, for example, can change by the hour as users travel and send events from different cities. Knowing where the user was at the time of the event can be more valuable than knowing where the user is now. ### Location property shows a `(none)` value Amplitude determines location user properties (such as `[Amplitude] City`, `[Amplitude] DMA`, `[Amplitude] Region`, and `[Amplitude] Country`) by GeoIP. Amplitude uses the [MaxMind](https://www.maxmind.com/en/home) database to look up location information from the user's IP address. For client-side events, location properties can have `(none)` values when MaxMind returns null for that IP address. The accuracy and availability of city and region information varies by country. For details, refer to [MaxMind's accuracy comparison](https://www.maxmind.com/en/geoip2-city-accuracy-comparison?country=&resolution=50). For server-side events, Amplitude determines location property values either by GeoIP (which falls back on `location_lat` and `location_long` if unavailable) or by explicit definition in your API call. Amplitude's [HTTP API](https://amplitude.com/docs/apis/analytics/http-v2) lets you send custom `City`, `DMA`, `Region`, and `Country` values with your events. Amplitude doesn't modify these values to reflect GeoIP. Update all four fields together: setting any one of these fields automatically resets all others. ### Why your device property shows a `(none)` value Amplitude determines `[Amplitude] Device family` and `[Amplitude] Device type` by reading `device_brand`, `device_manufacturer`, and `device_model` strings from the user's device, then mapping these strings to Amplitude's repository of device types. When a new phone model launches, Amplitude may not have mapped some device types yet. In these cases, `[Amplitude] Device type` is `(none)`. Server-side events can also have null device information when you don't update these fields together: `platform`, `os_name`, `os_version`, `device_brand`, `device_manufacturer`, `device_model`, `carrier`, and `user_agent`. Setting any of these fields resets all other property values to null unless you set them explicitly for the same event. ## User counts from past events The user count for an earlier date can fluctuate over time. When you view data on different days, the number of users for an earlier date may increase or decrease. The user count can increase when Amplitude later ingests events that occurred in the past. Common reasons: - Amplitude's mobile SDKs batch events with a threshold of every 30 seconds, or every 30 events. When users don't meet the threshold, the SDK may not send their events until they return to your product and trigger more events. - To resolve this, adjust the event upload frequency. For [Android Kotlin SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk#configure-the-sdk), configure `flushIntervalMillis` or `flushQueueSize`. For [iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#configure-the-sdk), configure `eventUploadPeriodSeconds` or `eventUploadThreshold`. For other SDKs, refer to the [SDK documentation](https://amplitude.com/docs/sdks/analytics). - Amplitude's Batch API and server-side integrations have inherent delays. - To resolve this, schedule batches more frequently. - If the user's cellular or Wi-Fi connection wasn't strong enough when they triggered events, the SDK holds those events until the connection is stronger. - There's no remedy for this issue. The user count can decrease when Amplitude merges user records. Amplitude uses a system of user IDs, device IDs, and Amplitude IDs to [track unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users). If some users don't have user IDs, or if you have many anonymous events, Amplitude first assigns these anonymous events to an anonymous profile, then later merges them into a known profile. Your data stabilizes over time as anonymous users return and merge into existing profiles. The time this takes depends on user behavior (how often they return to your product) and your settings (how often you batch events). Users who interact with your product every day have shorter merge delays. Users who return less frequently have longer delays. ## Data discrepancies with other platforms Amplitude's numbers may differ from what other vendors report. The cause can vary. Before you compare numbers, review how Amplitude tracks users and sessions. Refer to [tracking unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users) and [the definition of a session in Amplitude](https://amplitude.com/docs/data/sources/instrument-track-sessions). ## Data discrepancy checklist Use the following questions as a troubleshooting checklist for data discrepancies. If you can answer "yes" to a question, that factor is probably not the cause. ### Time zones align between Amplitude and the other platform If not, align the time zones before comparing numbers. Amplitude timestamps the data it ingests in UTC, but you can customize the time zone [within the Amplitude UI](https://amplitude.com/docs/admin/account-management/manage-orgs-projects#view-and-edit-your-project-information). ### Events tracked in Amplitude match what you track in the other platform If not, a discrepancy in users and sessions numbers becomes more likely, because both depend on the events tracked. ### Amplitude and the other platform block the same web bots and scrapers If not, a discrepancy in users and sessions numbers becomes more likely. ### Both platforms define the metric of interest the same way If not, a discrepancy is more likely. ### The other platform merges users the way Amplitude does If not, you may see a discrepancy in users and sessions numbers, depending on the identifiers the other platform uses to merge users. ### The session timeout window matches between Amplitude and the other platform If not, you're more likely to see a discrepancy in sessions numbers. > **Note:** > > For Amplitude SDKs, the default session timeout windows are 30 minutes for web and 5 minutes for mobile. These thresholds are customizable, so confirm with your developer whether they've been changed. ## Sessions in Google Analytics Google Analytics and Amplitude track sessions similarly, but certain common events can cause a discrepancy in session numbers. | **Scenario** | **Amplitude** | **Google Analytics** | **Source** | | --- | --- | --- | --- | | Time hits midnight | Session continues | The current session ends at 11:59 PM and the new session starts at 12:00 AM. | [Refer to "Time Based Expiration"](https://support.google.com/analytics/answer/2731565#time-based-expiration) | | Campaign source changes | Session continues | New session begins even if it is within the 30-minute threshold. | [Refer to "Campaign Based Expiration"](https://support.google.com/analytics/answer/2731565#campaign-based-expiration) | | Session Event Limit | No limit | After the first 10 events, Google Analytics limits tracking to 1 event per second. | [Refer to "Events Per Session Limit"](https://support.google.com/analytics/answer/1033068) | ================================================================================ # Instrumentation and governance issues URL: https://amplitude.com/docs/data/troubleshooting/instrumentation-issues ================================================================================ # Instrumentation and governance issues Answers to common instrumentation and governance questions: how Amplitude treats hidden, blocked, and deleted events, how to filter internal and bot traffic, how to modify historical data, and how the date picker handles offsets and exclusions. ## Instrumentation basics ### Can you delete or alter values after ingestion? After Amplitude ingests data, you can't alter it. Amplitude's architecture uses pre-aggregated sets by the hour, day, week, and month, for both users and events. This approach supports large-scale queries, but requires immutable data. You can delete data at the individual user level in compliance with GDPR and other privacy laws through the [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy). ### How does Amplitude set Device ID? Amplitude sets Device IDs differently for client-side events (using Amplitude's SDKs) versus server-side events (HTTP API). - SDKs - For Android, the Device ID defaults to a randomly generated UUID, unless you opt to use Google's Advertising ID as the Device ID. - For iOS SDK, Device IDs default to the Identifier for Vendor (IDFV) if available; otherwise the SDK generates them randomly. You can choose instead to use the Advertising Identifier (IDFA), if available. - Server-side (HTTP API) - For server-side events, you must manually send Device ID in the event. If no Device ID is available, Amplitude sets the Device ID to a randomly-generated hashed version of the `user_id`. For more details, refer to the [HTTP V2 API](https://amplitude.com/docs/apis/analytics/http-v2). - If you don't maintain the same Device ID setup for server-side and client-side events, the same user has different Device IDs even when the device model, language, and carrier are the same. ### Can two different events have the same name? No. Each event name must be unique across an entire project. Amplitude treats two events with the same name as the same event. If you notice two events in a project with the same name, the display name for one of them may have been set to the same name as another event. You can confirm by expanding the event in Amplitude Data to see more details. ### Can you send array values into Amplitude? Yes. However, Amplitude doesn't support exact matching on array properties. You can use the `contains` operator to filter for values within an array. - SDK - [User Property Array](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#arrays-in-user-properties) - [Event Property Array](https://amplitude.com/docs/sdks/analytics/browser/javascript-sdk#arrays-in-event-properties) - [HTTP API Array](https://amplitude.com/docs/apis/analytics/http-v2) ### Why does device information (like Device Type or Device Family) return 'null' in my project? Amplitude returns a null value when it can't parse device information from the device or browser, or when the device isn't mapped in Amplitude's system. To map new device values, contact Amplitude's support team with the following information: - Manufacturer (for example, samsung). - Model (for example, sm-g930u). - Device Family (for example, Samsung Galaxy Phone). - Device Type (for example, Samsung Galaxy S7). ### Why do my sessions generate new Session ID values? Events ingested through Amplitude's SDK maintain the same session _if_ the events come from the same device. Session ID changes every time the Device ID changes. The default session timeout for JavaScript SDK is 30 minutes. For iOS/Android, it's five minutes. ### How do you send recurring revenue subscription events? After the first subscription-related revenue event, Apple or Google must validate whether the subscription is active. If the subscription is active, Amplitude receives the subscription revenue event at the time interval of that subscription. ### How do I filter out bot traffic users? Amplitude SDKs use the User Agent to populate some user properties (such as device type), but don't collect or store the User Agent itself. Some customers implement logic to store User Agent as a custom user property and remove bot users that way. Alternatively, if you can determine the IP address of a suspected bot user, you can use Data Filters to block events from that IP address. To learn more, refer to Amplitude's help center article on [blocking bot web traffic](https://amplitude.com/docs/data/block-bot-traffic). ## Block and filter internal users To keep data clean, Amplitude recommends setting up a development project alongside your production project, and sending test data to the development project only. Testing your production environment can still send internal data into your production project. Because internal user events can falsely inflate your product's metrics, you must block or filter out these events for accurate reporting. ### How do I block specific users? You can block all internal event data originating from your organization's IP address from ingestion into Amplitude Analytics. Use your project's Data Filters page to set up filters. To set up a filter to block events from a specified IP address, follow these steps: 1. From Data, navigate to Filters and click _+Create Block Filter_. 2. In the fly-out panel that appears, choose which environment to apply the filter to. 3. Select _Events_ from the _Block_ drop-down menu. 4. Choose _IP Address_ and _equal to_ from the two other drop-down menus. Then enter the IP address to block. 5. Click _Block Data_. 6. Repeat steps 4 through 6 for each IP address to block. > **Note:** > > You must be a manager or admin of your organization to add a data filter. After you set up this filter, Amplitude drops all events sent from your list of IP addresses on ingestion. This filter doesn't work if you've modified Amplitude's SDK configurations to prevent the collection of IP addresses. The filter only drops events whose collected IP address matches the IPs you've blocked. ### How do I filter out specific users? You can always segment out internal user events using the Segmentation Module of any Amplitude chart. Segment out users by user ID, device ID, Amplitude ID, IP address, or an identifiable user property (for example, username or email). ### How do I save user segments? You can save user segments and pin them to your charts so you don't have to recreate filters every time. When you set a saved segment as your default, Amplitude applies that segment to all new charts you create through the _Create Chart_ or _New_ button. The applied filter then appears on your chart. ### How do I maintain user lists? Your list of internal users can change over time, and maintaining this list takes effort when your users don't share a common attribute. In these cases, use Amplitude's [behavioral cohorts](https://amplitude.com/docs/analytics/behavioral-cohorts) feature and import a cohort of internal users to block on Amplitude. You can apply this cohort to charts the same way you apply user properties. After you create a user segment that excludes your internal cohort, save and pin the segment for easy access. You can also update behavioral cohorts programmatically to maintain your cohort of internal users. Review the [Behavioral Cohorts API](https://amplitude.com/docs/apis/analytics/behavioral-cohorts) for more details. ## Related resources - [Block bot web traffic](https://amplitude.com/docs/data/block-bot-traffic): Prevent bot traffic from affecting your metrics. - [Winsorization in Experiment](https://amplitude.com/docs/feature-experiment/advanced-techniques/winsorization-in-experiment): Find and resolve outliers that may skew your experiment results. ## Hide, block, or delete an event or property The differences between hiding, blocking, and deleting an event or property aren't immediately clear. Hidden and blocked events and properties still count towards your project's instrumentation [limit](https://amplitude.com/docs/faq/limits-and-quotas); deleted events and properties don't. > **Note:** > > These options only appear in the menu at the top of [Amplitude Data](https://amplitude.com/docs/data) after you select an event or property. ### What is a hidden event or property? Hide an event or property when you don't want users to query on it in Amplitude charts, but still want to collect data for it. You can hide an event or property from drop-downs, Pathfinder results, and Personas charts: - Hiding from drop-downs means you can't select that event or property from drop-down lists in any Amplitude chart. - When you hide the event or property from Pathfinder or Personas results, those charts' calculations exclude that event. Amplitude still ingests the data, and the event or property becomes queryable again after you unhide it. ### What does blocking an event or property do? Block an event or property when you want to continue querying historical data, but want to stop collecting new data. Blocking helps when a particular event is causing you to hit your monthly event volume limit. When you block an event or property, Amplitude stops ingesting and processing it. Blocked events and properties that Amplitude ingested before the block remain selectable in drop-downs and usable in charts. Data sent after you create a block doesn't appear in user streams or chart results. Blocking doesn't stop you from sending that data to Amplitude, so you still receive a success response. Amplitude drops the data before the processing stage, and you can't recover it. ### What happens to deleted events and properties? Delete an event or property that you no longer need to keep your data structure organized. Too many unnecessary events and properties can lead to hitting your project's instrumentation limit. As with blocking, Amplitude doesn't ingest deleted events and properties, and you can't recover data sent after deletion. Unlike blocked items, deleted events and properties aren't available in drop-downs. Charts that include a deleted event or property remain available, but you can't include the deleted item in new charts. If you removed a deleted event from a chart, you can't add it back unless you undelete it. Deleted events still appear in chart results, so to remove or hide chart data for a deleted event, [create a drop filter](https://amplitude.com/docs/data/remove-invalid-data) before deleting the event. ### What are the differences between hiding, blocking, and deleting? | | Blocked from ingestion | Available in data exports | Available in chart dropdowns | Count towards monthly event volume limit | Count towards 2000 event type limit | In Govern | | --- | --- | --- | --- | --- | --- | --- | | **Blocked** | Yes | No | Yes | No | Yes | All, Blocked | | **Deleted** | Yes | No | No | No | No | Deleted | | **Hidden** | No | Yes | No | Yes | Yes | All, Live, Hidden | ## Modify or delete historical data The Amplitude architecture uses pre-aggregated sets by the hour, day, week, and month for users and events. This approach scales well, but the tradeoff is that data is immutable. ### How do I modify events that Amplitude has already ingested? If your account is on the Growth or Enterprise plan, refer to [Self-service data deletion in Amplitude](https://amplitude.com/docs/admin/account-management/self-service-data-deletion-in-amplitude). For other account types, direct modification isn't possible. As a workaround: 1. Export all project data using the [Export API](https://amplitude.com/docs/apis/analytics/export). 2. Clean the data (for example, make the required changes). 3. Upload the cleaned data into a new project using the [Batch API](https://amplitude.com/docs/apis/analytics/batch-event-upload). ### I updated user properties using the Identify API. Why are there still 'none' values in my charts? The Identify API only updates user property values for future events. You can't change data that Amplitude has already ingested. Send another event for Amplitude to apply the updated property value. For more details on how Amplitude updates user properties, refer to [user properties and events](https://amplitude.com/docs/data/user-properties-and-events). ### I accidentally sent an event for a user. How do I delete this specific event for this specific user? You can't. Ingested data is immutable. For similar results, try this process: 1. [Delete or block](https://amplitude.com/docs/data/remove-invalid-data) the event: - This prevents the event from entering Amplitude for all users. - The event still appears in the user's event stream, but isn't available for querying. 2. If deleting or blocking doesn't work, try the workaround described in the previous FAQ. ### How do I backfill historical data into Amplitude? Refer to the [Data Backfill Guide](https://amplitude.com/docs/data/data-backfill). ## Date picker behavior The datepicker selects the timeframe of the analysis you're conducting. You can choose to analyze data collected between two dates, since a specific date, or in the last x days, weeks, or months. The datepicker has nuances in how it handles time. ## Offset When you use Last, your queries return data from the specified timeframe, plus the latest still-incomplete interval. For example, when you set the datepicker to the last 30 days, Amplitude retrieves data from the last 30 full days, plus the hours elapsed today. To exclude data from the incomplete day, or when you use a delayed batch ingestion system, use an offset. Click +Offset in the datepicker, then enter the number of days to offset by. To remove the offset, click 'X' near the Offset by text. ## Exclude When you use Since or the Last x days, weeks, or months options, you can also exclude the current day, week, or month. This helps when the data for the selected timeframe isn't fully available. To exclude the incomplete time interval from your chart, click +Exclude in the datepicker and select the Incomplete Interval option. The current date no longer appears framed in a dotted line, and Amplitude excludes it from your analysis. Deselect Incomplete Interval to revert this setting. Use the same process to exclude or include the current week, current month, or current quarter. > **Note:** > > Amplitude doesn't support using offset and exclude at the same time. ### Exclude specific days You can exclude specific days of the week from your analysis. This option suits organizations that operate on custom schedules. For example, retailers can exclude Sundays when stores aren't open, or SaaS companies can omit weekends to focus on workweek behavior. Excluding specific days affects both chart visuals and metric calculations like averages and rolling windows. Exclude specific days supports only the following chart types: - Segmentation. - Funnels. - Data Tables. - Retention. - Sessions. Exclude specific days supports only the following time ranges: - Last. - Since. > **Note:** > > Exclude specific days doesn't work with Period over Period analysis, and it doesn't work with `realtime` intervals. #### How Amplitude handles excluded days When you exclude days, Amplitude: - Removes the days from the calculations and from the chart visualization. - For averages, calculates on the valid days in the window. For example, if you're looking at the range Sunday - Saturday (7 days) with Wednesday removed: - For non-average time series analysis, the data shows as normal with Wednesday removed. - For aggregate data analysis, the data doesn't count the Wednesday in the aggregation. - For averaging analysis (such as the rolling window), Amplitude doesn't count the dropped days in the numerator or the denominator. If you have a 7-day rolling window, Amplitude treats the data point as a 0 and divides the average based on the valid days in the window (6 days in this example). - For non-daily or non-hourly intervals analysis, Amplitude doesn't remove data from the chart or the table. However, the data still has the underlying days removed. This method avoids artificially low averages and maintains consistent windowing on charts. ## Time input When you use Since or Between, you can narrow the range further by enabling time input. Time input lets you enter a start time or an end time to add granularity to your analysis. > **Note:** > > The datepicker's time input feature is only available for Event Segmentation and Funnel Analysis charts. To enable time granularity, click +Time in the datepicker. After you enable time input, enter the start or end times in hours, minutes, and seconds to accompany your selected date range. To turn off time input, click the 'X' near the entered time. ## Presets The datepicker also supports presets to streamline repetitive analysis and ensure consistency across teams. ### Using presets Presets give you quick access to predefined time ranges, including: - Last 7 days. - Last month. - Year to date. - Custom fiscal periods. When you select a preset, the datepicker automatically fills in the associated time range. ### Custom presets You can create custom presets for recurring analysis windows like product launches, campaigns, or testing periods. Presets can include: - Specific start/end dates. - Relative timeframes (for example, "Last 60 days"). - Optional exclusions (like incomplete data or specific weekdays). Amplitude defines presets at the project level, and they're available across the project. Admins and managers can create, edit, and manage these presets in Project Settings. ### Default presets Users can also define their own default preset for a given project. This preset automatically applies when creating new charts. ## New orgs can't open the menu ### Why can't new users navigate the left-hand menu? When you create a new org on Amplitude, all team members start on the Amplitude _Settings_ page. They don't have an option to open the left-hand menu. New users can appear "stuck" on the _Settings_ page, unable to navigate to any other page on Amplitude. This happens because Amplitude can't populate any charts until it has data to work with. To open the left-hand menu, first set up your data sources and send data to Amplitude. After the charts have data to query on, your left menu expands and you can navigate through the Amplitude UI. ## Firefox ingestion failure ### Why does Firefox block the Amplitude SDK? In Firefox, the tracking protection feature is automatically enabled in standard mode. Amplitude can't record events when you switch this feature to "strict," or when you use a private browser window. Tracking protection blocks cross-site trackers to protect user privacy when browsing across the web. To read more about what tracking protection is and how it affects tracking, refer to [Mozilla's documentation](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop#w_what-enhanced-tracking-protection-blocks). Because tracking protection prevents cross-site tracking, it blocks the Amplitude SDK. Firefox blocks the network requests, which causes events to fail ingestion. The following error appears when tracking protection is enabled in the Firefox browser: Failed POST request. ### How do I fix the ingestion issue? According to the Amplitude engineering team, the best solution is to build a proxy server and point the JS SDK at it. Refer to the [documentation on how to create a proxy](https://amplitude.com/docs/analytics/domain-proxy) to learn more. ================================================================================ # Integrations and source troubleshooting URL: https://amplitude.com/docs/data/troubleshooting/integrations-and-sources ================================================================================ # Integrations and source troubleshooting This page covers troubleshooting for Amplitude data sources and integrations: missing events and properties from Segment, incorrectly tracked sessions, iOS 14 IDFA changes, missing mobile attribution events, and how to instrument Amplitude on third-party site builders like Wix and Squarespace. ## Segment-Amplitude integration ## Missing events ### Why don't I see any data in Amplitude? If the event isn't in Segment, then it isn't in Amplitude. Confirm that your requests from Segment received a successful response before considering an event missing. After you confirm that the event is in Segment and got a successful response, confirm these three things: 1. Is Amplitude enabled as a destination? 2. Is the correct API Key entered? Verify the Amplitude API Key value in project settings in your Amplitude UI matches the one in Segment. 3. Is the syntax correct? Instrumentation errors aren't always obvious. Check the code for syntax errors (the browser Console tab can help). After you confirm these requirements, send data to Amplitude by calling `track`. Data appears after you track your first event. ### Are you over the event-type instrumentation limit? If you went [over the limit](https://amplitude.com/docs/faq/limits-and-quotas), Amplitude doesn't ingest any data sent after that. To ingest more event types, delete events to get back under the limit. ### Is the event deleted or blocked from Amplitude? Check your deleted and blocked events. Deleting event types also blocks all future instances of events with the same name. If you send data to a deleted or blocked event name in Amplitude, the data doesn't come through. ### Are there any errors in Segment's debugger? Check your Debugger tab for errors. If the missing event doesn't appear in the Debugger, send a test event of that event type. If the event doesn't reach Segment, it doesn't appear in Amplitude. ### Does the event exist in Segment? For track calls, you can choose to send only certain events to certain integrations. Verify that the event is sending and that Amplitude is enabled. You can also enable or disable specific integrations directly in the instrumentation code. Check that Amplitude isn't disabled in the code. For page and screen calls, you can't see all the individual page names, but the activity shows whether Segment is receiving page calls. You can also check the raw JSON of the requests to verify whether the Amplitude integration is turned off: ```json "integrations": { "Amplitude": false } ``` ## Missing properties ### What is the difference between an event property and a user property? The article on [user properties and events](https://amplitude.com/docs/data/user-properties-and-events) explains the difference between the two types of properties. ### Why don't I see any user properties or only \[Amplitude\] user properties? To send user properties through [Segment](https://segment.com/), call `identify` and include your user properties in the `traits` field. Refer to the [Segment documentation](https://segment.com/docs/spec/identify/) for more on the `identify` call. ### Are you over the event property type instrumentation limit? If you went [over the limit](https://amplitude.com/docs/faq/limits-and-quotas), properties may be missing in Amplitude. Amplitude doesn't ingest any data sent after you exceed the limit. Delete properties to get back under the limit and ingest new properties. ### Is the property deleted or blocked from Amplitude? Check your deleted and blocked properties. Deleting properties also blocks all future instances of properties with the same name. If you send data to Amplitude with a deleted or blocked property name, the data doesn't come through. ### Did the property come through in the raw payload to Segment? If the property isn't in Segment, it isn't in Amplitude. Check Segment's debugger to confirm that the property appeared in Segment first. ### Does the property exist in Segment's schema? Check your tracked properties and confirm they exist in Segment. ### Spot any syntax code errors or other instrumentation errors? Instrumentation errors aren't always obvious. Check the code for syntax errors (the browser Console tab can help). Refer to [Segment's specs](https://segment.com/docs/spec/) for how to format your data. Amplitude has a [limit of 1024 characters](https://amplitude.com/docs/faq/limits-and-quotas). If the property value is too long, the property doesn't appear in Amplitude. ### Why does the location information (city or country) from Segment's data differ from the location information in Amplitude's data? Amplitude tries to determine the user's location from the user's IP address, if available. This location may differ from the location information Segment recorded. ## Incorrectly-tracked sessions ### What is the definition of a session? A session is a period of time when the user has the application open in the foreground. If session tracking is available, events logged within the same session share the same session ID. A new session starts when the application enters the foreground after being in the background or closed for more than five minutes. ### Why do all of my events have a `sessionId` of -1? If you use the Amplitude Classic integration in Cloud mode, Segment doesn't provide session tracking by default, so Session ID appears as -1 in Amplitude. Segment doesn't have a [concept for a session](https://segment.com/blog/facts-vs-stories-why-segment-has-no-sessions-api/). You must pass in the sessionId for your server-side calls from Segment to Amplitude. For more details, refer to [Segment's Amplitude integration docs](https://segment.com/docs/integrations/amplitude/#sessionid%C2%A0). If you use Segment's client-side bundled integration, the integration uses Amplitude's native SDKs, which track Session IDs for you. Segment provides these options: - Use the integration in device mode and use Amplitude's native SDKs' default session tracking. For details, refer to the [Segment source catalog](https://amplitude.com/docs/data/source-catalog/segment). - If you use the Amplitude Actions integration from Segment, session tracking is available in Segment's new libraries [Analytics.js 2.0](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/), [Swift](https://github.com/segmentio/analytics-swift), or [Kotlin](https://github.com/segmentio/analytics-kotlin). For details, refer to [Segment's Amplitude Actions docs](https://segment.com/docs/connections/destinations/catalog/actions-amplitude/#connection-modes-for-amplitude-actions-destination). ### Why are there no session length calculations in Amplitude Dashboard? When Session ID is -1 (refer to the previous answer), Amplitude can't calculate session length. ### What if Segment's SDK doesn't support feature X? \[device-mode\] The Segment SDK might not have all the APIs the Amplitude SDK provides. You can still access features by directly calling Amplitude's SDKs. ### Still have questions? Submit a Support ticket with the following details: - What type of connection are you using? ([cloud-mode or device-mode](https://segment.com/docs/connections/destinations/#connection-modes)). - Do you have any destination filters enabled? - Do you see any errors in the _Event Delivery_ tab? - Confirm that you're using the correct API Key for the Amplitude destination. Also share the raw data for an event that should have been in Amplitude but is missing. Amplitude needs a full payload of the event, including the endpoint used, header, and body. ## iOS 14 changes At WWDC 2020, Apple announced that iOS 14 requires users to opt in to tracking. The IDFA is only present for users who explicitly opt in, and the percentage of users who do so is likely to be low. This article covers frequently asked questions about Apple's iOS 14 IDFA changes. ### Does Amplitude accept IDFA (Identifier for Advertisers) as the device identifier on iOS? By default, Amplitude's iOS SDK uses IDFV (Identifier for Vendor) for the device ID. You can change this and use any value as the device identifier. The SDK includes an option to use IDFA as the device ID, but this option only works if the user has permitted the application to use IDFA. ### What are the implications of Apple's IDFA changes on user tracking? For logged-in users, there's no impact. Even if the device ID changes, events continue to merge from devices when Amplitude receives a common user ID. Anonymous users have some potential for impact. For anonymous users, there are no changes in most cases, because most Amplitude customers don't set IDFA as the device ID. For customers who do set IDFA as the device ID, Amplitude stores the device ID when the SDK initializes, and the SDK continues to send Amplitude the same ID as long as the application remains installed on the device. If a user deletes and reinstalls an application that uses IDFA for device ID, the SDK doesn't retain the former device ID. Instead, the SDK generates a new random device ID, unless the user grants the application permission to use IDFA. For all new application installs, the SDK accepts IDFA if the user has opted in and the application chooses to use IDFA. ### Does Amplitude require IDFA on attribution events? No. Amplitude's attribution API accepts both IDFA and IDFV, and tries to match those IDs to user events Amplitude receives later. In some cases, IDFV is enough to make a match, but some Amplitude customers' attribution providers only send IDFA. For these customers, Amplitude can no longer match attribution events unless the user has explicitly opted in to both the referring and installed application. Some attribution vendors are likely to stop sending individual attribution events. Vendors are unlikely to send aggregated data to Amplitude (because of the nature of the platform), unless customers or attribution vendors can segment that data and use it to set user properties. ### How does this affect outbound integrations? If you send data to outbound integrations, you see a lower match rate when using IDFA to match devices between Amplitude and the integration. Amplitude recommends switching to IDFV or another common identifier instead. ## Missing mobile attribution events Mobile attribution partners identify events using advertising IDs like IDFA, IDFV, or ADID. Amplitude identifies users based on a combination of `user_id`, `device_id`, and `amplitude_id`. Amplitude's [Attribution API](https://amplitude.com/docs/apis/analytics/attribution) reconciles these differences and maps attribution events to existing users in Amplitude. Some mobile attribution partners (Appsflyer, Adjust, Branch, and Singular) use this API to send their non-custom, standard data with the advertising IDs as the identifier. Amplitude stores unmapped attribution events for 72 hours. During that time, Amplitude looks for a matching IDFA, IDFV, or ADID on an existing user in an Amplitude project. If a match exists, Amplitude routes the attribution event to that user. If no match exists, Amplitude drops the attribution event after 72 hours. To support this process, instrument Amplitude with advertising IDs enabled. ## Why mobile attribution events may be missing You can resolve some causes quickly: - The attribution events didn't successfully send to Amplitude. Confirm that the attribution partner receives a success response (for example, a 200) when sending events. - Your project has reached the [instrumentation limit](https://amplitude.com/docs/faq/limits-and-quotas). Delete event types or properties to allow Amplitude Analytics to ingest new event types and properties. - You blocked or deleted the event type in the Amplitude project. Restore the event type or property through Amplitude Data to fix the issue. Other causes require more investigation: - No existing user in Amplitude with the matching IDFA, IDFV, or ADID. - Amplitude didn't complete mapping within 72 hours. ## Troubleshoot: No existing user in Amplitude with the matching IDFA, IDFV, or ADID This is the top reason why Amplitude Analytics doesn't ingest mobile attribution events. You must instrument Amplitude before you can send mobile attribution events. ### Determine if you're tracking advertising IDs Advertising IDs are IDFA, IDFV, or ADID. If you track advertising IDs in your Amplitude events, Amplitude Analytics captures their value in the respective property field. For security and PII reasons, advertising IDs don't appear as a usable property, and Amplitude removes advertising IDs from your raw data after capture (unless you instrument advertising IDs as a custom property). Amplitude stores a hashed version of the advertising IDs in a field called `amplitude_attribution_ids`. Use this field to determine whether you're instrumenting advertising IDs. If the value is `null`, Amplitude captured no advertising IDs for this user. A `null` value generally means either that you haven't instrumented Amplitude Analytics to capture advertising IDs, or that the end user has opted out of advertising ID tracking. You must honor user opt-outs. If you track advertising IDs properly and want to confirm that `amplitude_attribution_ids = null` results from a user opt-out, contact Amplitude Support. ### Solution: Tracking advertising IDs If you use JavaScript, which can't track advertising IDs automatically, send an Amplitude event with the advertising ID through the [HTTP API](https://amplitude.com/docs/data/sources/instrument-track-unique-users). ## Troubleshoot: Mapping didn't happen within 72 hours Amplitude holds an attribution event for 72 hours. If Amplitude doesn't make a match during that time, Amplitude drops the event. For example, User A downloads a game app on December 1 but doesn't open the app until December 7: - Mobile attribution partners list an Install event for User A on December 1 and send that event to Amplitude on December 1. - User A doesn't record their first event in Amplitude until they open the app on December 7. Amplitude considers User A a new user on December 7. Amplitude drops User A's `Install` event because User A didn't exist in Amplitude within 72 hours of the attribution event. User A only existed in Amplitude seven days after the `Install` event, which is longer than the 72-hour holding period. ### Determine if the attribution event came too early Amplitude's iOS SDKs capture IDFV as `device_id` by default. If you use the default setting for iOS SDKs, use this process to troubleshoot: 1. Identify an iOS SDK user in Amplitude who doesn't have an `Install` event, even though there is a value for `amplitude_attribution_ids`. 2. Copy the `device_id` (IDFV) of that user. 3. With your mobile attribution provider, look for the `Install` event of the IDFV. 4. Check the date on the `Install` event. 5. Compare that date to the New User date in Amplitude. The mobile attribution provider likely sent the `Install` event more than 72 hours before the user existed in Amplitude. You can also check whether a user already exists in Amplitude by following a similar process: 1. Identify an iOS Install event from the mobile attribution provider that doesn't appear in Amplitude yet. 2. Get the IDFV on that payload. 3. Enter the IDFV in the [user look-up](https://amplitude.com/docs/analytics/user-data-lookup) feature as the device ID. The IDFV likely doesn't associate with a profile in Amplitude Analytics, which means Amplitude hasn't seen the user yet. ### Solution: Create users before real user activity An end user exists in Amplitude when Amplitude receives the user's first event. If you don't want to wait on the end user's actions to trigger profile creation, create a profile yourself by either: - Sending a placeholder event with advertising ID and `device_id` or `user_id` through the HTTP API. - Creating a profile with advertising ID and `device_id` or `user_id` through the Identity API. Creating a profile is only possible if you can capture the advertising ID on your own. Maintain the correct `device_id` or `user_id` so you connect real-world user activity to the right profile. ## Instrument on third-party site builders > **Note:** > > These instructions may become outdated as the third-party platforms covered here make changes and upgrades. Amplitude's Support team provides support for the instructions and processes in this article only; they can't provide recommendations for anything not included here. ### How do I instrument Amplitude on a third-party website builder? If your site runs on a third-party website builder like Wix or Squarespace, most builders have an underlying code base you can use. Add Amplitude's [JavaScript SDK](https://amplitude.com/docs/sdks/analytics/browser/javascript-sdk) to that space, as if you were adding the SDK to a natively-built website. Add the [JavaScript SDK snippet](https://amplitude.com/docs/sdks/analytics/browser/javascript-sdk#install) to the header, and the rest of the JavaScript SDK code in the body. If you don't have access to the header or underlying source code, you can use [webhooks](https://en.wikipedia.org/wiki/Webhook) to combine a [trigger](https://support.zendesk.com/hc/en-us/articles/203662106) or [automation](https://support.zendesk.com/hc/en-us/articles/203662126) with an HTTP [target](https://support.zendesk.com/hc/en-us/articles/203662136) to Amplitude's server-side endpoint, [HTTP v2](https://amplitude.com/docs/apis/analytics/http-v2). ### How do I instrument Amplitude on Wix? Wix has a Tracking Tools & Analytics feature, which you can use to embed Amplitude's JavaScript SDK snippet and code in your site. To do so, follow these steps: 1. Go to [_Settings_ in your site's dashboard](https://www.wix.com/my-account/site-selector/?buttonText=Manage%20Settings&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https://www.wix.com/dashboard/%7B%7BmetaSiteId%7D%7D/manage-website). 2. Click the _Tracking & Analytics_ tab, under _Advanced Settings_. 3. Click _+ New Tool_ and select _Custom_. 4. Set up your custom code: 1. Enter your custom code. 2. Select the relevant domain. This option appears only if you have multiple domains. 3. Enter a name for your custom code. 4. Add Code to Pages: Select which pages to add your code to: - All Pages: Click the dropdown and select either _Load code once_, or [_Load code on each new page_](https://support.wix.com/en/article/custom-code-loading-options). - Choose specific pages: Begin typing the name of the relevant pages. Then click the checkbox next to the relevant page. 5. Place Code in: Select where to place the code snippet in your site's code. - Head: This is where to place the [JS SDK install snippet](https://amplitude.com/docs/sdks/analytics/browser/javascript-sdk#install) on every page to track analytics. - Body: This is where all other calls like [logEvent](https://amplitude.com/docs/sdks/analytics/browser/migrate-from-javascript-sdk-to-browser-sdk-1-0#logevent) and [user properties](https://amplitude.com/docs/sdks/analytics/browser/migrate-from-javascript-sdk-to-browser-sdk-1-0#set-user-properties) should go. 5. Click _Apply_. Some customers have reported that Wix lets you add header scripts but not call functions from them. One workaround is to put the necessary script in the Public folder. #### Further reading on Wix - [Adding custom code to your site](https://support.wix.com/en/article/about-tracking-tools-analytics). - [Embedding custom code on your site](https://support.wix.com/en/article/embedding-custom-code-to-your-site). ### How do I instrument Amplitude on Squarespace? Squarespace's Code Injection and Code Block features let you embed Amplitude's JS SDK snippet and code in your site. > **Note:** > > These features may be premium features, only available in Business and Commerce plans. #### Code Injection Use Code Injection to add Amplitude's JavaScript SDK install snippet and other scripts that enhance specific parts of your site, like an order confirmation page. To add JavaScript to a Code Injection field, surround the code with `<script></script>` tags. Site-wide and per-page code injection options are both available. For the per-page code injection option, refer to [Squarespace's Code Injection article](https://support.squarespace.com/hc/en-us/articles/205815908). If you add code to Code Injection, Squarespace may ask you to [disable the code while editing your site](https://support.squarespace.com/hc/articles/205815908#toc-disable-scripts-in-preview). To add the JavaScript SDK install snippet with Code Injection: 1. Open Code Injection. In the _Home_ menu, navigate to _Settings > Advanced > Code Injection_. 2. Add JavaScript SDK code into the appropriate Code Injection fields for the header, footer, lock page, or order confirmation page. - Header: Code added here goes into the `<head>` tag on every page in your site. The Amplitude JavaScript SDK install snippet belongs here. - For information on the other three options, refer to [Squarespace's Code Injection article](https://support.squarespace.com/hc/en-us/articles/205815908). 3. After adding your code, click _Save_. #### Code Block Use Code Block to set up logEvent, user properties, and similar calls. To add JavaScript to a Code Block field, surround the code with `<script></script>` tags. To add a Code Block, follow these steps: 1. Edit a page or post, click an insert point, and select _Code_ from the menu. For help, refer to [Adding content with blocks](https://support.squarespace.com/hc/articles/206543757). 2. [Add your code](https://support.squarespace.com/hc/en-us/articles/206543167#toc-add-code) in the text field. For event and property calls, refer to the [Browser SDK 2 documentation](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-an-event). 3. If you're using the Code Block to [display code snippets](https://support.squarespace.com/hc/en-us/articles/206543167#toc-display-source), check _Display Source_. 4. Click _Apply_ to save your changes. ================================================================================ # Common Patterns URL: https://amplitude.com/docs/data/common-patterns ================================================================================ # Common Patterns Amplitude fits into many different data stacks. Most customers use one of four patterns: 1. Amplitude as the primary analytics destination. 2. Amplitude with a Customer Data Platform (CDP) such as Segment. 3. Amplitude with a data warehouse such as Snowflake, BigQuery, Redshift, or Databricks. 4. Amplitude with both a CDP and a data warehouse. Across all four, Amplitude's web, mobile, and server SDKs give you a single way to collect events, power Session Replay, and stream that same data to the rest of your stack through Event Stream and exports. After you instrument your product, you rarely need to change application code when you add new destinations. You can instrument Amplitude Session Replay in several ways. For the browser, use the Session Replay plugin for the Amplitude Browser SDK, a standalone Session Replay SDK, Google Tag Manager, or a Segment integration. For iOS, Android, and React Native, use plugins that sit on top of Amplitude's analytics SDKs, standalone Session Replay SDKs, or Segment-based options. Instrumenting Session Replay together with events gives you three main benefits: - You can trace every chart, funnel, and cohort back to real user sessions so teams can watch what users did. - Product and engineering teams can debug issues faster by combining quantitative signals such as drop-offs or errors with qualitative evidence from replays. - You get a single set of SDKs and privacy controls for both analytics events and replay, which simplifies governance. The sections below describe how each data stack pattern works. ## Amplitude only In this setup, Amplitude and its SDKs are your main event collection, Session Replay, and analytics layer. ### Data flow Your website, mobile apps, and backend services send behavioral events directly to Amplitude using Amplitude SDKs or HTTP APIs. The same web and mobile SDKs can capture Session Replay data for selected sessions. Amplitude stores and processes everything for product analytics, experimentation, journey analysis, cohorts, and session-level insights. From there, you can sync events, cohorts, and selected replay links to downstream tools. ### Role of the SDKs and Session Replay Because Amplitude SDKs collect events and replay, you can later turn on Event Stream and forward those same events from Amplitude to other tools such as a warehouse, CDP, or marketing systems, without changing tracking in your application. Session Replay shares the same user and session identifiers as your events, so product teams can move from a funnel in Amplitude to a specific session and watch what happened at a critical step. ### When this works well This pattern is ideal when you're building a new analytics stack, don't yet have a central warehouse or CDP, and want to standardize tracking and replay quickly with one SDK implementation. ### Key benefits - Fast time to value with minimal infrastructure. - Single place to define events, properties, identities, and replay settings. - You can use Event Stream from Amplitude as you add new tools later. - Direct connection between quantitative analysis and qualitative replay for faster debugging and UX improvement. ## Amplitude with a CDP Here, a CDP is the primary collection and routing layer, and Amplitude is a downstream analytics and activation destination. ### Data flow Your product sends events to the CDP using CDP SDKs. The CDP forwards a copy of those events to Amplitude and routes them to marketing tools and ad platforms. Amplitude uses that behavioral data for product analytics, experimentation, cohorts, and activation. You can instrument Session Replay in four main ways. The last method uses a CDP: 1. Using the [Amplitude Session Replay SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk). 2. Using the [Amplitude Session Replay Browser SDK plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin). 3. Using [Google Tag Manager](https://amplitude.com/docs/sdks/session-replay/session-replay-google-tag-manager). 4. Using [Segment](https://amplitude.com/docs/sdks/session-replay/session-replay-integration-with-segment). These methods let you keep the CDP as the central event router while still getting session-level visibility inside Amplitude. ### Role of the SDKs and Session Replay Most customers either instrument events only through the CDP SDKs and use Amplitude's SDKs specifically for Session Replay and any extra product-only events, or combine CDP and Amplitude SDKs more broadly for redundancy and lower latency. In all cases, Amplitude can still use Event Stream to forward its copy of events to other destinations. ### When this works well This pattern is common when you've already deployed a CDP that owns identity resolution and audience syncs, and marketing teams rely on it. Amplitude becomes the main product analytics and Session Replay surface while the CDP remains the system through which events pass. ### Key benefits - Single event schema in the CDP shared across Amplitude and marketing tools. - Amplitude benefits from the CDP's unified identities while adding deep product analytics and replay. - You can use Session Replay to explain patterns seen in CDP-driven campaigns and journeys. - You can stream Amplitude's enriched event data into other systems. ## Amplitude with a data warehouse In this pattern, Amplitude is the product analytics and event collection layer, and the warehouse is the central storage and business intelligence layer. ### Data flow Your applications send events and Session Replay data into Amplitude using Amplitude SDKs. Amplitude stores and processes events and replay for analytics and troubleshooting. Amplitude then exports raw or modeled event data to your warehouse on a schedule or through streaming. Business intelligence tools query the warehouse to combine Amplitude events with billing, CRM, support, and other data. You can activate this data out of the warehouse with a Reverse ETL tool like Hightouch. ### Role of the SDKs and Session Replay Amplitude SDKs define a behavioral schema optimized for product analytics and replay. After you instrument, you don't need separate tracking for warehouse use. Events flow first into Amplitude, then into the warehouse through exports or Event Stream. Session identifiers and user identifiers stay consistent across analytics in Amplitude and tables in the warehouse, so data teams can link warehouse-based models such as churn or lifetime value back to specific replays for qualitative investigation. ### When this works well This pattern fits organizations where product teams rely on Amplitude for self-service analytics and debugging, while the data team uses the warehouse for cross-domain reporting and modeling. ### Key benefits - One instrumentation path for both analytics and warehouse use. - The warehouse receives clean event data that Amplitude has already validated. - Data teams can join behavioral events with other domains while still using Amplitude for quick analysis and Session Replay. - Replays give valuable context when investigating anomalies or model outputs discovered in warehouse-based dashboards. ## Amplitude with CDP and data warehouse This pattern combines all three components. The CDP (or a CDI like Snowplow) is the real-time collection and routing layer, the warehouse is the long-term storage and modeling layer, and Amplitude is the product analytics, Session Replay, and activation layer. ### Data flow Your applications send events into the CDP using its SDKs. The CDP forwards those events to Amplitude and to the warehouse. Amplitude instruments Session Replay through its own SDKs, plugins, or Segment-based integrations, and attaches replays to the sessions that originate from CDP events. The warehouse receives event data from the CDP or Amplitude, and data teams build models and aggregate tables there. You can send modeled attributes and scores back into Amplitude or the CDP with reverse ETL. ### Role of the SDKs and Session Replay CDP SDKs typically provide the core event stream. Amplitude SDKs focus on Session Replay and any Amplitude-specific instrumentation that you choose to add. Amplitude can still stream enriched events and replay metadata to the warehouse or other tools. This combination gives you multiple controlled paths for data without duplicating tracking logic in code. ### When this works well This pattern fits data-mature organizations where: - The CDP owns event collection, identity resolution, and routing. - The warehouse owns storage, modeling, and governance. - Amplitude owns behavioral analytics, experimentation, Session Replay, and product-led activation. ### Key benefits - Shared behavioral data across product, marketing, sales, and analytics teams. - Strong governance for schemas and identities with clear ownership in CDP and warehouse. - Session Replay directly tied to CDP-based journeys and warehouse-based models to explain the why behind metrics. - You can stream Amplitude events and replay context to many downstream tools without new SDK work in the product. ## Choosing the right pattern Many customers evolve through these patterns over time. 1. Start with Amplitude only and instrument both events and Session Replay with Amplitude SDKs to get quick value and a consistent behavioral model. 2. Add a CDP to standardize collection for marketing and other tools while still using Amplitude for analytics and replay. 3. Add a warehouse to centralize storage, join across systems, and support advanced modeling and business intelligence. 4. Connect all three so that the system best suited for each job handles collection, analytics, replay, and storage. Across all four scenarios, Amplitude's instrumentation layer for events and Session Replay is reusable and extensible. After data flows into Amplitude, you can use Event Stream and exports to route events and replay context across your stack, so your architecture can evolve while your tracking plan remains stable. ================================================================================ # Autocapture Events and Properties URL: https://amplitude.com/docs/data/autocapture-events-and-properties ================================================================================ # Autocapture Events and Properties This reference lists Autocapture event types and event property names for web when you use the [Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2). Use this reference to understand what Amplitude captures automatically, configure your tracking plan, or set up pipelines and validation. For a machine-readable version of this page, go to [Web Autocapture Schema](https://amplitude.com/docs/data/web-autocapture-schema). For native iOS and Android Autocapture event properties, go to [Mobile Autocapture Schema](https://amplitude.com/docs/data/mobile-autocapture-schema). ## Shared conventions - Property names in bold (for example, **Page URL**) reflect how they appear in Amplitude. - Autocapture prefixes some properties with `[Amplitude]`. Amplitude generates these automatically and marks them as read-only. - Configure which events Amplitude captures through `AutocaptureOptions` in the Browser SDK 2. ## Sessions ### Session started Captures when a user session begins, either on first page load or after a period of inactivity. | Property Name | Description | | --- | --- | | _No properties collected_ | | ### Session ended Captures when a user session ends due to inactivity or the browser tab closing. | Property Name | Description | | --- | --- | | _No properties collected_ | | ## Page views ### Page viewed Captures each time a user loads or navigates to a page, including single-page app route changes. | Property Name | Description | | --- | --- | | **Page Domain** | The full hostname from the current web address, including any subdomains such as `www` or `app`. | | **Page Location** | The full URL of the current page, including any URL Search Parameters. | | **Page Path** | The pathname of the current page. This excludes any URL Search Parameters and URL Fragments. | | **Page Title** | The title of the page. | | **Page URL** | The URL of the page excluding the URL Search Parameters. | ## File downloads ### File downloaded Captures when a user clicks a link that triggers a file download. | Property Name | Description | | --- | --- | | **File Extension** | The extension of the downloaded file. For example: .pdf, .docx, .zip, and so forth. | | **File Name** | The full pathname of the downloaded file. This can include more than just the filename of the file. | | **Link ID** | The ID of the link element. | | **Link Text** | The text content of the link element. | | **Link URL** | The link address of the file download. | ## Form interactions Autocapture captures forms that use the `<form>` tag. ### Form started Captures when a user initially interacts with a form element, including modifications to a text input, radio button, or dropdown. | Property Name | Description | | --- | --- | | **Form Destination** | The action attribute of the form element. For example, for `<form action="/subscribe">`, the value is `/subscribe`. | | **Form ID** | The ID of the form element. | | **Form Name** | The name attribute of the form element. | ### Form submitted Captures when a user submits the form. | Property Name | Description | | --- | --- | | **Form Destination** | The action attribute of the form element. For example, for `<form action="/subscribe">`, the value is `/subscribe`. | | **Form ID** | The ID of the form element. | | **Form Name** | The name attribute of the form element. | ## Element interactions ### Element clicked Captures clicks on page elements. The default configuration captures user interactions with interactive elements on your page. The default eliminates event noise such as clicks to highlight text and white-space clicks. The default captures the following: - All clicks on form elements: `<a>`, button, input, select, text area, label, and elements where `contentEditable` is set to `true`. - All clicks on video and audio elements. - Clicks on select elements that result in a change on your page (for example, a modal appearing) or navigation to another page. These elements include divs, spans, and headers. - All clicks on elements with an attribute of `data-amp-default-track` or a class of `amp-default-track`. - You can customize this configuration to add or remove selectors. You can choose whether Amplitude always tracks those selectors or only when the click results in a change to the page. | Property Name | Description | | --- | --- | | **Element ID** | The `id` attribute of the HTML element. For example, an element with `id="myID"` produces the value `myID`. | | **Element Class** | The `class` attribute of the HTML element. For example, an element with `class="myClass"` produces the value `myClass`. | | **Element Tag** | The tag name of the HTML element. For example, an `<a>` element produces the value `a`. | | **Element Text** | The text content (`innerText`) of the HTML element. Only applies to the Element Clicked event. For example, a link with text "Home" produces the value `Home`. | | **Element Href** | The `href` attribute of the HTML element. Only applies to `<a>` tags on the Element Clicked event. Amplitude truncates values longer than 128 bytes. | | **Element Position Left** | The distance of the element from the left of the screen view, in pixels. For example, a value of `600` means the element was 600px from the left. | | **Element Position Top** | The distance of the element from the top of the screen view, in pixels. For example, a value of `400` means the element was 400px from the top. | | **Viewport Height** | The height of the viewport in pixels when the element was clicked. For example, a value of `900` means the viewport was 900 pixels tall. | | **Viewport Width** | The width of the viewport in pixels when the element was clicked. For example, a value of `1200` means the viewport was 1200 pixels wide. | | **Page URL** | The URL of the page where the element was clicked. | | **Page Title** | The page title of the page where the element was clicked. | | **Element Hierarchy** | DOM elements and attributes of the element clicked and its parent or sibling elements. Amplitude uses this for visual labeling. | | **Element Selector** | **Deprecated** in favor of Element Hierarchy. A unique CSS selector of the element. For example, an element with `id="myID"` produces the value `#myID`. | | **Element Attributes** | Unique attributes associated with click events through the `dataAttributePrefix` setting. For example, an element with attribute `id="feature-start"` produces a property `[Amplitude] Element Attributes.id` with the value `feature-start`. | | **Element Aria Label** | The `aria-label` of the element, used for interactive elements without visible text. For example, an element with `aria-label="Close"` produces the value `Close`. | | **Element Parent Label** | The text label in the parent element (or upper ancestors if not found in the one-level parent) of the element. | ### Element changed Captures form element interactions, such as changes to a dropdown or entering text in a text box. | Property Name | Description | | --- | --- | | **Element ID** | The `id` attribute of the HTML element. | | **Element Class** | The `class` attribute of the HTML element. | | **Element Tag** | The tag name of the HTML element. | | **Element Position Left** | The distance of the element from the left of the screen view, in pixels. | | **Element Position Top** | The distance of the element from the top of the screen view, in pixels. | | **Viewport Height** | The height of the viewport in pixels when the element changed. | | **Viewport Width** | The width of the viewport in pixels when the element changed. | | **Page URL** | The URL of the page where the element changed. | | **Page Title** | The page title of the page where the element changed. | | **Element Hierarchy** | DOM elements and attributes of the element changed and its parent or sibling elements. Amplitude uses this for visual labeling. | | **Element Selector** | **Deprecated** in favor of Element Hierarchy. A unique CSS selector of the element. | | **Element Attributes** | Unique attributes associated with change events through the `dataAttributePrefix` setting. | | **Element Aria Label** | The `aria-label` of the element, used for interactive elements without visible text. | | **Element Parent Label** | The text label in the parent element (or upper ancestors if not found in the one-level parent) of the element. | ## Network requests Captures when the application makes a network request. By default, Amplitude tracks network requests with a response code in the range 500-599 and excludes requests made to any `amplitude.com` domain. To enable network request tracking, set `config.autocapture.networkTracking` to `true` in your SDK configuration. | Property Name | Description | | --- | --- | | **\[Amplitude\] URL** | The URL of the network request with sensitive information masked. | | **\[Amplitude\] URL Query** | The query parameters of the URL. | | **\[Amplitude\] URL Fragment** | The fragment identifier of the URL. | | **\[Amplitude\] Request Method** | The HTTP method used for the request (for example, GET, POST, PUT, or DELETE). | | **\[Amplitude\] Status Code** | The HTTP status code of the response. | | **\[Amplitude\] Error Code** | The local error code if the request failed without a status code. | | **\[Amplitude\] Error Message** | The local error message if the request failed without a status code. | | **\[Amplitude\] Start Time** | The timestamp when the request started, in milliseconds since Unix epoch. | | **\[Amplitude\] Completion Time** | The timestamp when the request completed, in milliseconds since Unix epoch. | | **\[Amplitude\] Duration** | The duration of the request in milliseconds. | | **\[Amplitude\] Request Body Size** | The size of the request body in bytes. | | **\[Amplitude\] Response Body Size** | The size of the response body in bytes. | | **\[Amplitude\] Request Body** | The captured JSON request body (when you configure a `requestBody` capture rule). | | **\[Amplitude\] Response Body** | The captured JSON response body (when you configure a `responseBody` capture rule). | For more information about configuring network tracking, including advanced capture rules and filtering options, refer to [Track network requests](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-network-requests) in the Browser SDK 2 documentation. ## Web Vitals Captures Core Web Vitals performance metrics when the browser tab hides. | Property Name | Description | | --- | --- | | **Page Domain** | The full hostname from the current web address, including any subdomains such as `www` or `app`. | | **Page Location** | The full URL of the current page, including any URL Search Parameters. | | **Page Path** | The pathname of the current page. This excludes any URL Search Parameters and URL Fragments. | | **Page Title** | The title of the page. | | **Page URL** | The URL of the page excluding the URL Search Parameters. | | **LCP (Largest Contentful Paint)** | The time it takes for the largest content element to become visible in the viewport. Measured in milliseconds. | | **FCP (First Contentful Paint)** | The time it takes for the first content element to be painted on the screen. Measured in milliseconds. | | **INP (Interaction to Next Paint)** | The time from a user interaction to the next paint. Measured in milliseconds. | | **CLS (Cumulative Layout Shift)** | The sum of all individual layout shift scores for unexpected layout shifts. A dimensionless value. | | **TTFB (Time to First Byte)** | The time from the navigation start to when the first byte of the response is received. Measured in milliseconds. | Each metric includes a performance rating (good, needs-improvement, or poor) based on Web Vitals thresholds and timing data. ================================================================================ # Web Autocapture Schema URL: https://amplitude.com/docs/data/web-autocapture-schema ================================================================================ # Web Autocapture Schema This reference lists Autocapture event types and event property names for web when you use the [Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2). Use it when you need a stable contract for pipelines, partners, or validation. For Autocapture setup steps, go to [Autocapture](https://amplitude.com/docs/get-started/autocapture). For full property descriptions with examples, go to [Autocapture events and properties](https://amplitude.com/docs/data/autocapture-events-and-properties). For native iOS and Android Autocapture event properties, go to [Mobile Autocapture Schema](https://amplitude.com/docs/data/mobile-autocapture-schema). ## Shared conventions - **Event type** values match what Amplitude stores as `event_type` (for example, `Page viewed`). - Web event types don't use the `[Amplitude]` prefix, except for `[Amplitude] Network Request`. - **Property names** appear in Amplitude exactly as listed here. - Session events carry no additional properties beyond standard user and session context. ## Machine-readable schema ```json { "description": "Web Autocapture event types and event property names for the Amplitude Browser SDK 2.", "documentation": "/docs/data/web-autocapture-schema", "web": { "sdk": "Browser SDK 2", "events": { "Session Started": { "properties": [] }, "Session Ended": { "properties": [] }, "Page viewed": { "properties": ["Page Domain", "Page Location", "Page Path", "Page Title", "Page URL"] }, "File Downloaded": { "properties": ["File Extension", "File Name", "Link ID", "Link Text", "Link URL"] }, "Form Started": { "properties": ["Form Destination", "Form ID", "Form Name"] }, "Form Submitted": { "properties": ["Form Destination", "Form ID", "Form Name"] }, "Element Clicked": { "properties": [ "Element ID", "Element Class", "Element Tag", "Element Text", "Element Href", "Element Position Left", "Element Position Top", "Viewport Height", "Viewport Width", "Page URL", "Page Title", "Element Hierarchy", "Element Attributes", "Element Aria Label", "Element Parent Label" ] }, "Element Changed": { "properties": [ "Element ID", "Element Class", "Element Tag", "Element Position Left", "Element Position Top", "Viewport Height", "Viewport Width", "Page URL", "Page Title", "Element Hierarchy", "Element Attributes", "Element Aria Label", "Element Parent Label" ] }, "[Amplitude] Network Request": { "properties": [ "[Amplitude] URL", "[Amplitude] URL Query", "[Amplitude] URL Fragment", "[Amplitude] Request Method", "[Amplitude] Status Code", "[Amplitude] Error Code", "[Amplitude] Error Message", "[Amplitude] Start Time", "[Amplitude] Completion Time", "[Amplitude] Duration", "[Amplitude] Request Body Size", "[Amplitude] Response Body Size", "[Amplitude] Request Body", "[Amplitude] Response Body" ] }, "Web Vitals": { "properties": [ "Page Domain", "Page Location", "Page Path", "Page Title", "Page URL", "LCP (Largest Contentful Paint)", "FCP (First Contentful Paint)", "INP (Interaction to Next Paint)", "CLS (Cumulative Layout Shift)", "TTFB (Time to First Byte)" ] } } } } ``` ## Web (Browser SDK 2) Configure which events Amplitude captures using `AutocaptureOptions` in the Browser SDK 2. Go to [Autocapture (Browser SDK 2)](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#autocapture-replaces-defaulttracking) for configuration options. | Event type | When it fires | Typical event properties | | --- | --- | --- | | `Session Started` | Session begins on first page load or after inactivity. | None. | | `Session Ended` | Session ends due to inactivity or browser tab closing. | None. | | `Page viewed` | User loads or navigates to a page, including single-page app route changes. | `Page Domain`, `Page Location`, `Page Path`, `Page Title`, `Page URL`. | | `File Downloaded` | User clicks a link that triggers a file download. | `File Extension`, `File Name`, `Link ID`, `Link Text`, `Link URL`. | | `Form Started` | User initially interacts with a form element (text input, radio button, or dropdown). | `Form Destination`, `Form ID`, `Form Name`. | | `Form Submitted` | User submits a form. | `Form Destination`, `Form ID`, `Form Name`. | | `Element Clicked` | User clicks an interactive page element. | `Element ID`, `Element Class`, `Element Tag`, `Element Text`, `Element Href`, `Element Position Left`, `Element Position Top`, `Viewport Height`, `Viewport Width`, `Page URL`, `Page Title`, `Element Hierarchy`, `Element Attributes`, `Element Aria Label`, `Element Parent Label`. | | `Element Changed` | User changes a form element such as a dropdown or text input. | `Element ID`, `Element Class`, `Element Tag`, `Element Position Left`, `Element Position Top`, `Viewport Height`, `Viewport Width`, `Page URL`, `Page Title`, `Element Hierarchy`, `Element Attributes`, `Element Aria Label`, `Element Parent Label`. | | `[Amplitude] Network Request` | Application makes a tracked HTTP request (response codes 500–599 by default). | `[Amplitude] URL`, `[Amplitude] URL Query`, `[Amplitude] URL Fragment`, `[Amplitude] Request Method`, `[Amplitude] Status Code`, `[Amplitude] Error Code`, `[Amplitude] Error Message`, `[Amplitude] Start Time`, `[Amplitude] Completion Time`, `[Amplitude] Duration`, `[Amplitude] Request Body Size`, `[Amplitude] Response Body Size`, `[Amplitude] Request Body`, `[Amplitude] Response Body`. | | `Web Vitals` | Browser tab hides; Amplitude collects Core Web Vitals. | `Page Domain`, `Page Location`, `Page Path`, `Page Title`, `Page URL`, `LCP (Largest Contentful Paint)`, `FCP (First Contentful Paint)`, `INP (Interaction to Next Paint)`, `CLS (Cumulative Layout Shift)`, `TTFB (Time to First Byte)`. | ================================================================================ # Mobile Autocapture Schema URL: https://amplitude.com/docs/data/mobile-autocapture-schema ================================================================================ # Mobile Autocapture Schema This reference lists Autocapture event types and event property names for native iOS and Android when you use the [iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk) and [Android-Kotlin SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk). Use it when you need a stable contract for pipelines, partners, or validation. > **Note:** React Native packages > > Amplitude doesn't ship a separate React Native Autocapture package. React Native apps that need comparable behavior typically instrument events manually or bridge to native SDKs. This schema applies to native iOS and Android Autocapture only. For Autocapture setup steps, go to [Autocapture](https://amplitude.com/docs/get-started/autocapture). For web Autocapture event properties, go to [Autocapture events and properties](https://amplitude.com/docs/data/autocapture-events-and-properties). For a machine-readable web schema, go to [Web Autocapture Schema](https://amplitude.com/docs/data/web-autocapture-schema). ## Machine-readable schema ```json { "description": "Native mobile Autocapture event types and event property names for Amplitude iOS Swift SDK and Android-Kotlin SDK. React Native is not included.", "documentation": "/docs/data/mobile-autocapture-schema", "ios": { "events": { "[Amplitude] Start Session": { "properties": [] }, "[Amplitude] End Session": { "properties": [] }, "[Amplitude] Application Installed": { "properties": ["[Amplitude] Version", "[Amplitude] Build"] }, "[Amplitude] Application Updated": { "properties": [ "[Amplitude] Version", "[Amplitude] Build", "[Amplitude] Previous Version", "[Amplitude] Previous Build" ] }, "[Amplitude] Application Opened": { "properties": [ "[Amplitude] Version", "[Amplitude] Build", "[Amplitude] From Background" ] }, "[Amplitude] Application Backgrounded": { "properties": [] }, "[Amplitude] Screen Viewed": { "properties": ["[Amplitude] Screen Name"] }, "[Amplitude] Deep Link Opened": { "properties": ["[Amplitude] Link URL", "[Amplitude] Link Referrer"] }, "[Amplitude] Network Request": { "properties": [ "[Amplitude] URL", "[Amplitude] URL Query", "[Amplitude] URL Fragment", "[Amplitude] Request Method", "[Amplitude] Status Code", "[Amplitude] Error Code", "[Amplitude] Error Message", "[Amplitude] Start Time", "[Amplitude] Completion Time", "[Amplitude] Duration", "[Amplitude] Request Body Size", "[Amplitude] Response Body Size", "[Amplitude] Request Body", "[Amplitude] Response Body", "[Amplitude] Request Headers", "[Amplitude] Response Headers" ] }, "[Amplitude] Element Interacted": { "properties": [ "[Amplitude] Action", "[Amplitude] Target View Class", "[Amplitude] Target Text", "[Amplitude] Target Accessibility Label", "[Amplitude] Target Accessibility Identifier", "[Amplitude] Action Method", "[Amplitude] Gesture Recognizer", "[Amplitude] Hierarchy", "[Amplitude] Screen Name" ] }, "[Amplitude] Rage Click": { "properties": [ "[Amplitude] Begin Time", "[Amplitude] End Time", "[Amplitude] Duration", "[Amplitude] Click Count", "[Amplitude] Clicks", "[Amplitude] Action", "[Amplitude] Target View Class", "[Amplitude] Target Text" ] }, "[Amplitude] Dead Click": { "properties": [ "[Amplitude] Begin Time", "[Amplitude] End Time", "[Amplitude] Duration", "[Amplitude] Action", "[Amplitude] Target View Class", "[Amplitude] Target Text" ] } } }, "android": { "events": { "[Amplitude] Start Session": { "properties": [] }, "[Amplitude] End Session": { "properties": [] }, "[Amplitude] Application Installed": { "properties": ["[Amplitude] Version", "[Amplitude] Build"] }, "[Amplitude] Application Updated": { "properties": [ "[Amplitude] Version", "[Amplitude] Build", "[Amplitude] Previous Version", "[Amplitude] Previous Build" ] }, "[Amplitude] Application Opened": { "properties": [ "[Amplitude] Version", "[Amplitude] Build", "[Amplitude] From Background" ] }, "[Amplitude] Application Backgrounded": { "properties": [] }, "[Amplitude] Screen Viewed": { "properties": ["[Amplitude] Screen Name"] }, "[Amplitude] Fragment Viewed": { "properties": [ "[Amplitude] Screen Name", "[Amplitude] Fragment Class", "[Amplitude] Fragment Identifier", "[Amplitude] Fragment Tag" ] }, "[Amplitude] Deep Link Opened": { "properties": ["[Amplitude] Link URL", "[Amplitude] Link Referrer"] }, "[Amplitude] Network Request": { "properties": [ "[Amplitude] URL", "[Amplitude] URL Query", "[Amplitude] URL Fragment", "[Amplitude] Request Method", "[Amplitude] Status Code", "[Amplitude] Error Message", "[Amplitude] Start Time", "[Amplitude] Completion Time", "[Amplitude] Duration", "[Amplitude] Request Body Size", "[Amplitude] Response Body Size" ] }, "[Amplitude] Element Interacted": { "properties": [ "[Amplitude] Action", "[Amplitude] Target Class", "[Amplitude] Target Resource", "[Amplitude] Target Tag", "[Amplitude] Target Text", "[Amplitude] Target Source", "[Amplitude] Hierarchy", "[Amplitude] Screen Name" ] }, "[Amplitude] Rage Click": { "properties": [] }, "[Amplitude] Dead Click": { "properties": [] } } } } ``` ## Shared conventions - **Event type** values match what Amplitude stores as `event_type` (for example, `[Amplitude] Screen Viewed`). - **Property names** use the `[Amplitude] ...` prefix in the product and in this doc. - Session events typically carry only standard user and session context unless you add more in code. ## iOS (Swift SDK) Enable options through `AutocaptureOptions`. Go to [Autocapture (iOS)](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#autocapture) for configuration options. | Event type | When it fires | Typical event properties | | --- | --- | --- | | `[Amplitude] Start Session` | Session starts | User properties (when you enable user property collection). | | `[Amplitude] End Session` | Session ends | User properties (when you enable user property collection). | | `[Amplitude] Application Installed` | First open after install | `[Amplitude] Version`, `[Amplitude] Build`. | | `[Amplitude] Application Updated` | First open after update | `[Amplitude] Version`, `[Amplitude] Build`, `[Amplitude] Previous Version`, `[Amplitude] Previous Build`. | | `[Amplitude] Application Opened` | Launch or foreground after first open | `[Amplitude] Version`, `[Amplitude] Build`, `[Amplitude] From Background` (when applicable). | | `[Amplitude] Application Backgrounded` | App enters background | None. | | `[Amplitude] Screen Viewed` | UIKit screen appears | `[Amplitude] Screen Name`. | | `[Amplitude] Deep Link Opened` | Deep link opens | `[Amplitude] Link URL`, `[Amplitude] Link Referrer`. | | `[Amplitude] Network Request` | SDK captures HTTP traffic (per SDK rules) | `[Amplitude] URL`, `[Amplitude] URL Query`, `[Amplitude] URL Fragment`, `[Amplitude] Request Method`, `[Amplitude] Status Code`, `[Amplitude] Error Code`, `[Amplitude] Error Message`, `[Amplitude] Start Time`, `[Amplitude] Completion Time`, `[Amplitude] Duration`, `[Amplitude] Request Body Size`, `[Amplitude] Response Body Size`, plus optional experimental body and header properties when you enable them. | | `[Amplitude] Element Interacted` | `UIControl` / gesture interaction | `[Amplitude] Action`, `[Amplitude] Target View Class`, `[Amplitude] Target Text`, `[Amplitude] Target Accessibility Label`, `[Amplitude] Target Accessibility Identifier`, `[Amplitude] Action Method`, `[Amplitude] Gesture Recognizer`, `[Amplitude] Hierarchy`, `[Amplitude] Screen Name`. | | `[Amplitude] Rage Click` | Frustration (rage click) | Go to [Track frustration interactions](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#track-frustration-interactions) for more information. | | `[Amplitude] Dead Click` | Frustration (dead click) | Same as [Rage Click](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#track-frustration-interactions). | ## Android (Kotlin SDK) Enable options through `AutocaptureOption`. Go to [Autocapture (Android)](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk#autocapture) for configuration options. | Event type | When it fires | Typical event properties | | --- | --- | --- | | `[Amplitude] Start Session` | Session starts | User properties (when you enable user property collection). | | `[Amplitude] End Session` | Session ends | User properties (when you enable user property collection). | | `[Amplitude] Application Installed` | First open after install | `[Amplitude] Version`, `[Amplitude] Build`. | | `[Amplitude] Application Updated` | First open after update | `[Amplitude] Version`, `[Amplitude] Build`, `[Amplitude] Previous Version`, `[Amplitude] Previous Build`. | | `[Amplitude] Application Opened` | Launch or foreground after first open | `[Amplitude] Version`, `[Amplitude] Build`, `[Amplitude] From Background` (when applicable). | | `[Amplitude] Application Backgrounded` | App backgrounds | None. | | `[Amplitude] Screen Viewed` | Activity appears | `[Amplitude] Screen Name`. | | `[Amplitude] Fragment Viewed` | Fragment appears | `[Amplitude] Screen Name`, `[Amplitude] Fragment Class`, `[Amplitude] Fragment Identifier`, `[Amplitude] Fragment Tag`. | | `[Amplitude] Deep Link Opened` | Deep link opens | `[Amplitude] Link URL`, `[Amplitude] Link Referrer`. | | `[Amplitude] Network Request` | SDK captures HTTP traffic (plugin) | `[Amplitude] URL`, `[Amplitude] URL Query`, `[Amplitude] URL Fragment`, `[Amplitude] Request Method`, `[Amplitude] Status Code`, `[Amplitude] Error Message`, `[Amplitude] Start Time`, `[Amplitude] Completion Time`, `[Amplitude] Duration`, `[Amplitude] Request Body Size`, `[Amplitude] Response Body Size`. | | `[Amplitude] Element Interacted` | Clickable view or Compose | `[Amplitude] Action`, `[Amplitude] Target Class`, `[Amplitude] Target Resource`, `[Amplitude] Target Tag`, `[Amplitude] Target Text`, `[Amplitude] Target Source`, `[Amplitude] Hierarchy`, `[Amplitude] Screen Name`. | | `[Amplitude] Rage Click` | Frustration (optional) | Go to [Track frustration interactions](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk#track-frustration-interactions) for more information. | | `[Amplitude] Dead Click` | Frustration (optional) | Same as [Rage Click](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk#track-frustration-interactions). | ================================================================================ # Manage your Amplitude Data settings URL: https://amplitude.com/docs/data/amplitude-data-settings ================================================================================ # Manage your Amplitude Data settings On the Amplitude Data settings page, you configure and govern your Amplitude Data project, from naming and schema rules to integrations, API tokens, and permissions. Use these settings to: - Name your project and specify the naming conventions you use for events and properties. - Specify whether you require team reviews for all changes to main. - Set the Amplitude projects for your environments. - Add integrations. - Generate API tokens. - Delete your Amplitude Data project. These settings and features appear on five tabs: General, Environments, Integrations, API Tokens, and Schema Settings. This article describes each tab. > **Note:** > > Configure your settings before setting up your first Amplitude Data project. ## Roles and permissions in Amplitude Data > **Note:** Role-based Access Controls (RBAC) > > For Enterprise organizations with Role-based Access Controls (RBAC) enabled, review the available [Data Roles and Permissions](https://amplitude.com/docs/admin/account-management/role-based-access-controls-rbac#rbac-permission-reference). | Role | Permissions | | --- | --- | | Admin | Configure workspace settings, approve tracking plan changes, and modify the tracking plan. | | Manager | Approve tracking plan changes and modify the tracking plan. | | Member | Modify the tracking plan for approval. | | Viewer | View the tracking plan and comment. | You can also restrict data management access while keeping permissions the same for other areas of Amplitude. Refer to [The Permissions tab](#the-permissions-tab) for more details. > **Info:** > > If you disable the **Require team reviews to make changes to the main branch** option in the project settings, members can modify the tracking plan, but approval isn't required. All other permissions remain the same. ## General The General tab is where you set the project **name**, the event and property **naming conventions**, **team review requirements** for changes on main, and where you **delete your project**. It's also where you find a **public link** to a read-only version of your tracking plan, so you can share it with stakeholders across your organization. ### Naming conventions Amplitude Data requires a consistent naming convention for events and properties. Without one, your tracking plan becomes harder to read and manage, because multiple events or properties can share the same name with different capitalization. Specify a custom naming convention, or choose from the following: - lower case. - Sentence case. - Title Case. - CamelCase. - lowerCamelCase. - snake\_case. ### Team reviews For larger teams and organizations, require team reviews for changes made to main. With this option, make any changes to your tracking plan in a branch other than main. Specify the number of reviewers required for approval, up to seven. ### Public link to your tracking plan To share your tracking plan, use the public link on the **General** tab. Copy it to your clipboard and paste it into an email or Slack message. Stakeholders can read it but can't make changes. You can also enable or disable the public link, which changes the availability for the selected project. Click **Create Public Link** or **Delete Public Link**. ## Integrations Integrate Amplitude Data with existing tools to streamline your analytics workflow. To integrate a platform, click **Connect** or **Add** next to its name. ## API Tokens Use API tokens to authenticate to Amplitude Data using credentials other than your email address and password. Tokens authorize applications to use the same roles and permissions you have when you log in personally. To create an API token, click **Create Token**. Amplitude Data generates the token and displays it in a modal window. Click **Copy to clipboard** immediately, because you can't retrieve the token later. ## Schema Settings Amplitude Data might receive data from your app that it doesn't know what to do with. This is usually the result of a schema violation, meaning your schema doesn't account for the received data. This usually happens when you don't plan for a particular data type or value when first setting up your schema. Configure your schema settings to tell Amplitude how to handle these situations. For any unplanned events, event properties, event property types, user properties, or user property types, tell Amplitude Data to either mark them as **unexpected** or to **reject** them outright. Amplitude Data ingests any unexpected events or properties and sends a notification to everyone subscribed to this schema. If you reject unexpected data, Amplitude Data doesn't ingest or store the rejected data, but subscribers still receive a notification. Click **Save** to apply any changes to your schema settings. ## The Permissions tab Data permissions restrictions limit who can perform Data Management functions. For example, you might want most users to have the Member role so they can create dashboards and charts, but limit custom event creation and other data management features to managers or administrators. In the Permissions tab, add restrictions for selected roles to limit data management access while keeping other permissions unchanged for those roles. Under Restrict access in Amplitude Data, choose from the following options to restrict permissions to the viewer level on a per-project basis: - Use Default Restrictions. - Restrict Members. - Restrict Members and Managers. Then click **Save**. Permission restrictions are available for Enterprise customers only. Only administrators can access the Permissions tab. ### Copy to other projects Click **Copy to Other Projects** to apply the current permission restriction settings to another project. ## Autocapture The Autocapture settings in Amplitude Data let you change the configuration of the Analytics Browser SDK directly from within Amplitude, so you can make changes without code changes or releases. These settings merge with any configuration you defined locally in your SDK initialization code on your website. ### Availability Autocapture settings are available on projects that use version 2.10.0 or higher of the [Amplitude Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) with `fetchRemoteConfig` enabled. To disable remote configuration, set `fetchRemoteConfig` to `false`. Disabling `fetchRemoteConfig` doesn't disable the remote configuration options in Data Settings. > **Note:** Remote configuration by default > > SDK version 2.16.1 and higher enable `fetchRemoteConfig` by default. ### How it works When the SDK initializes with `fetchRemoteConfig` enabled, the SDK retrieves configuration settings from Amplitude's servers using the project's API key. These remote settings merge with any local configuration you defined on your site. After merging, the SDK completes its initialization along with any plugins using this combined configuration. Remote configuration doesn't impact the load time of pages on your site but may impact SDK initialization time. > **Note:** Configuration timeout > > If the configuration takes longer than 5 seconds to load from Amplitude's servers, the SDK falls back to the local configuration set during initialization. On the Settings page, each configuration category offers three options: - **Default**: Keeps the local configuration in the SDK as-is. Settings in the UI don't override it. - **On**: Overrides the local configuration and sets the category to true. All settings within the category (for example, Element Interactions) follow the configuration in the UI. - **Off**: Overrides the local configuration and sets the category to false. > **Note:** Disabling Session Tracking > > If you use Session Replay, ensure your Session Replay SDK version is 1.12.1 or above. Changes made through the UI take effect after 10 minutes. ### Element interactions When you enable Element Interactions, several options appear: | Option | Purpose | | --- | --- | | CSS Selector Allowlist | Selectors for elements that users interact with, such as links and form elements. If you have custom or non-standard elements that users interact with, specify them here. | | Action Click Allowlist | Amplitude tracks the elements in this list only when a user clicks them and the click results in a page or DOM change. | | Page URL Allowlist | Specify URLs or URL patterns (using glob or regular expression) on which Amplitude tracks element click and change events. | | Data Attribute Prefix | Specify a prefix for data attributes, for example `data-amp-track`. Amplitude saves the value of these attributes as event properties. | [Zoning Insights](https://amplitude.com/docs/zoning-insights) also uses element interaction data to analyze engagement within defined areas of your pages. To use Zoning Insights, enable element interactions (and optionally configure allowlists) here or in your [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-element-interactions) initialization. > **Tip:** Lower event volume > > These options can help you control event volume. By ignoring dead clicks, the Action Click Allowlist is the most efficient method to reduce volume while still tracking relevant interactions. ================================================================================ # User properties and event properties URL: https://amplitude.com/docs/data/user-properties-and-events ================================================================================ # User properties and event properties User properties describe the person triggering an event (plan type, country, device). Event properties describe a single event instance (the song played, the button clicked, the checkout total). User properties persist across all of a user's events; event properties belong to one event each. Attach an attribute as a user property when it describes the person and you'd want to filter or segment by it across their full activity. Attach it as an event property when the attribute only makes sense in the context of one specific action. Amplitude supports both kinds: 1. **User properties**: Attributes of individual users. Common user properties include device type, location, User ID, and whether the user is a paying customer. A user property can reflect either current or previous values, depending on its nature and how often it updates. 2. **Event properties**: Attributes of a particular event. The values are current for the moment the event occurred. For example, the event `JoinCommunity` could have an event property `Type`, which denotes the kind of community joined _at the time_ of that event. > **Info:** > > For more on events, users, and properties, take this course in [the Amplitude Academy](https://academy.amplitude.com/amplitude-getting-started-with-analytics/1092674/scorm/40m548g557cd). ## User properties A user property is an attribute that describes a useful detail about the user it's attached to. Amplitude sends user properties with every event. Amplitude's SDKs track these user properties by default: - Platform. - Device Type. - Device Family. - Country. - City. - Region. - Start Version. - Version. - Carrier. - OS. - Language. - Library. - IP Address. You can find definitions of each property in the [user property definitions](https://amplitude.com/docs/get-started/user-property-definitions). You can also set up custom user properties. Choose characteristics and traits that are intrinsic to the user or to the device they're using; otherwise, the data you collect from your user properties isn't as useful. Common examples of custom user properties include referral source, plan type, number of friends, or current level in a game. You can tell the difference between default Amplitude user properties and custom user properties by looking for the Amplitude logo. If you see it, the property is a default user property. The names of custom user properties aren't prefixed by that logo. Amplitude customers typically implement up to 20 custom user properties, along with the default properties. ### How Amplitude updates user properties When a user triggers an event that Amplitude captures, the event includes the current values for each user property, but these values can change over time. For example, a user might move from New York to Dallas, or convert from a free user to a paying one. When this happens, Amplitude updates the user properties and applies the new values to events the user sends from that point forward. Amplitude doesn't apply user property updates retroactively, and older values remain in your historical data. Property values reflect the values at the time of the event. For example, this user viewed an article at 10:11 AM. The value for the `City` property was `San Francisco`. This user also viewed an article about a week earlier. When you select that event, the `City` property displays as `New York`, which was the value at the time the user triggered the `view article` event. The user properties displayed with each event in a user's [individual event stream](https://amplitude.com/docs/analytics/user-data-lookup) capture the value of the user property _at the time of the event_. Amplitude derives this information from the most recent event sent or an Identify call. > **Note:** > > You don't need to send custom user properties with every event. After you set a user property, the value persists, and Amplitude applies it to all subsequent events until the value changes. If you forget to apply custom user properties to your events, you can update user properties later through the [Identify API](https://amplitude.com/docs/apis/analytics/identify). If you query on this event in Amplitude later, the updated user property doesn't appear with the event and applies only to events from that point forward. #### When old and new user property values overlap When a user property's value changes, Amplitude charts can show the user in both the new and the old user property categories. This overlap applies only for the specific day on which the property value changed. For example, on July 1st, a user logs into your game app at version 1.8 and plays a few games. Later that day, the user updates to version 2.0 and plays more. If you segment the daily active user chart by version, and compare version 1.0 and 2.0, that user appears in both segments for that day. Starting July 2nd, the user appears only in the version 2.0 segment until they update to a newer version. Something similar can happen when you've applied a user segment to a chart. Amplitude shows `(none)` values if the user had no value for a user property at the time of the event. If a user initially had `isPaying` = `(none)` for their first `PlaySong` event, but then had `isPaying` = `True` for the next `PlaySong` event, the user shows up in both buckets. If you go to the [User Activity](https://amplitude.com/docs/analytics/user-data-lookup) page for that user, only their most recent value for that property appears in the top section of their profile. ### How Amplitude applies user properties to events You can apply user properties to events in three ways: 1. Update the user property before you send an event. Update the property's value in the user property table and apply it to the next event you send to Amplitude. This is the recommended method for updating user properties so that Amplitude correctly applies the updated value to the event. 2. Update the user property after you send an event. You send an event to Amplitude, then update the property's value in the user property table. The updated value doesn't appear in the user interface until you send another event. - If you send an Identify call after the event, the updated value doesn't appear with the event. It displays at the top of the user's profile, but doesn't appear in chart results until you send another event after the Identify call. 3. Send a user property with an event. For events sent through the [HTTP API](https://amplitude.com/docs/apis/analytics/http-v2), you can include user properties with the server-side call. The updated property appears in the user interface as soon as Amplitude receives the event. The user property table also updates after Amplitude ingests the event. Future events have the updated property value until it updates again. Send an event with, or directly after, a new property value to ensure the value displays in the UI. You can update user properties with the [Identify API](https://amplitude.com/docs/apis/analytics/identify). ## Event properties Event properties are attributes of the events your users trigger and that you send to Amplitude. Each event has its own set of event properties. The nature of these properties depends on the type of product you have and the specific information you want to discover. For instance, if `Swipe` is an event you're tracking, the event property `Direction` could have the values `Left` or `Right`. Example event properties include description, category, type, duration, level, percent completed, count, source, status, number, lives, authenticated, error number, rank, action, and mode. Use event properties to reduce the number of events you're tracking and to better analyze your events. > **Note:** > > Amplitude is an event-based platform. As a result, Amplitude logs events with event and user properties at the time a user triggers an event. Amplitude's charts reflect this. If your chart doesn't return the expected results, your query may reference the wrong property type. For example, if you have a user property and an event property both called `email`, verify which property you query on in a chart. Otherwise, your chart returns data that you may not expect. ## Hide properties You can [hide old or buggy properties as needed](https://amplitude.com/docs/data/remove-invalid-data). Hiding event or user properties only hides them from the platform UI and doesn't delete them. You can unhide the properties if you change your mind. ## Automatic deletion of user properties Amplitude automatically deletes user properties for users with no event data in the last 14 months. As long as a user has activity in your application or website over the last 14 months, Amplitude retains user properties associated with them. ================================================================================ # Official events and properties URL: https://amplitude.com/docs/data/official-events-and-properties ================================================================================ # Official events and properties Mark the events and properties your team trusts as _official_ to show that they're vetted, authoritative, and safe to use in analyses. Official designations help analysts and product managers build charts on reliable data, and Amplitude's AI agents favor official events and properties when they answer questions. Tracking-plan owners and data governors manage these designations as part of taxonomy maintenance. Use official designations for the events and properties in your tracking plan. To endorse reusable analysis objects like metrics, custom events, cohorts, and segments instead, use [Object management](https://amplitude.com/docs/data/object-management). ## How official designations work An official event or property is one a tracking-plan owner reviewed and endorsed as a source of truth. Marking an item official doesn't change the underlying data or how Amplitude ingests it. Instead, it adds a trust signal across Amplitude: - Event and property selectors show an **Official** filter, so you can narrow long lists to endorsed items. - Amplitude's AI agents weigh official events and properties more heavily when they choose data for an answer. ## Mark an event or property as official Changing an event or property's official status requires the _Manage tracking plans_ permission. Members without it can view which items are official but can't change the designation. 1. In Amplitude Data, go to _Events_ or _Properties_. 2. Click the event or property name to open its details panel. 3. Click the **Official** control to mark the item official. Click it again to remove the designation. To update several items at once, select them in the _Events_ or _Properties_ table, then set their official status from the menu at the top of the table. ## Find official events and properties - In a chart's event or property selector, apply the **Official** filter to choose only endorsed items. - In Amplitude Data, filter the _Events_ or _Properties_ table by official status to review which items your team endorsed. > **Note:** > > Marking an event or property official is a trust signal only. It doesn't block, hide, or transform data. To control which data Amplitude ingests, use blocking and [transformations](https://amplitude.com/docs/data/transformations). ================================================================================ # Time to Live (TTL) URL: https://amplitude.com/docs/data/time-to-live ================================================================================ # Time to Live (TTL) Time to Live (TTL) controls how long event data lives in your Amplitude instance by deleting event data outside a set retention period. Set the retention period for event data at the organization level, and override it at the project level. When you enable TTL, a job runs daily to enforce your retention policy and delete event data outside the retention period. ## Considerations > **Warning:** TTL causes irreversible data loss > > After you enable TTL, Amplitude deletes data outside of the retention period. - Amplitude uses the date the event data reaches the Amplitude server when determining the retention period. Any backfill or migration of event data may affect the retention period for that event data. - When you enable TTL and set a retention period, Amplitude deletes all event data sent to Amplitude outside of your retention period. - Enabling TTL affects existing Amplitude reports. After you enable TTL, Amplitude zeros out charts that query data outside the set retention period. The charts appear as if the data for that period never existed within Amplitude. - The initial deletion may take longer than daily deletions. Depending on an organization's historical event volume, it may take up to 30 days. ## Enable TTL To enable TTL controls for your organization, contact your Account Manager at Amplitude or fill out a [support request](https://help.amplitude.com/hc/en-us/requests/new). ## Configure TTL for your organization Amplitude Admins can configure TTL. 1. Navigate to _Organization Settings_ and click the _Time to Live (TTL)_ tab. 2. Choose the retention period. 3. Confirm your changes. After you confirm, deletion of your event data starts in 24 hours. The initial deletion may take up to 30 days. > **Warning:** Canceling TTL > > To cancel TTL, an admin can rescind the request in the 24-hour period before data deletion begins. After 24 hours, the deletion begins and is irreversible. ### Add a project-level TTL override Amplitude Admins can add overrides. 1. Navigate to _Organization Settings_ and click the _Time to Live (TTL)_ tab. 2. Click **Add Project TTL Override**. 3. Search for and select the project, and set the retention period. 4. Click **Save** to update the project's retention. ================================================================================ # Object management URL: https://amplitude.com/docs/data/object-management ================================================================================ # Object management Object management creates, edits, and deletes the analysis objects you reuse across charts and experiments: [custom events](https://amplitude.com/docs/data/custom-events), [metrics](#metrics), and [segments](https://amplitude.com/docs/analytics/behavioral-cohorts). It also surfaces similar existing objects while you create a new one, and shows where each object is used across your charts, so you don't recreate objects that already exist. Use object management to organize, deduplicate, or endorse these reusable objects. To mark individual events or properties in your tracking plan as trusted instead, use [official events and properties](https://amplitude.com/docs/data/official-events-and-properties). With object management, you can: - Create and update analysis objects. - Remove duplicate analysis objects. - View an analysis object's definition, and the charts it's used in. - Bulk delete analysis objects. ## Common use cases - Look for similar metrics, custom events, or segments during object creation to decide if any existing objects work, instead of creating another duplicate. - Use the metadata (for example, sorting by L30D query volume) to identify the most underutilized objects and remove them from the system. - Filter by object owner to find your own content quickly, or find objects created by experts and power users in your organization. - Admins can designate metrics, custom events, segments, and cohorts as "official," so users know which objects are safe to use. ## Manage your analysis objects Access _Object Management_ from the left nav. From the _Object Management_ page, click **+ Create New** and select the type of object you want to create. Follow the prompts in the modal that appears (it's different for each type). > **Note:** > > A metric is an event-and-measurement pairing saved as a single block, which you can reuse across charts and experiments. A custom metric is an event object made up of a user-defined combination of events and filters. As you define the object (by adding events for custom events and metrics, or by specifying users to include in your cohorts or segments), Amplitude Analytics shows you a list of similar objects at the bottom of the modal. Check your new object against this list to avoid creating unnecessary duplicate objects. Designate the object as "official" by clicking the checkmark next to the title. Designating the object validates it for use in charts and analyses, and Amplitude Analytics considers it to be a source of truth. After you create an analysis object, edit it by clicking its name in the list. The object's drawer opens. Click **Edit**. To find which charts a metric or custom event appears in, click the _Charts_ tab. To create a new chart from an analysis object, click **Open in Chart** from within the object's drawer. You can change the chart type if needed. To duplicate, delete, or copy a link to the analysis object, click **...** and select the appropriate choice from the dropdown. To bulk-delete analysis objects, navigate to the appropriate tab (_Custom Events_, _Metrics_, _Segments_, or _Cohorts_) and click the checkboxes of each object you want to delete. Then click **Delete**. ## Permissions Amplitude users with the Organization-level role of [Member](https://amplitude.com/docs/admin/account-management/user-roles-permissions#member) or higher can create analysis objects, and update or delete analysis objects they own. Only administrators can delete objects created by anyone. Object management doesn't support permissions at the project level. ================================================================================ # Channels URL: https://amplitude.com/docs/data/channels ================================================================================ # Channels A channel classifier buckets acquisition traffic into named groups (Paid Search, Organic Social, Direct, and so on) by applying rules to [UTM parameters](https://amplitude.com/docs/get-started/analyze-acquisition-channels), referrer data, or any other event or user property. Channels store the result as a new property computed dynamically at query time, so they don't touch your raw data and you can change a definition without re-ingesting events. Update a rule (for example, add a new social domain) and every existing chart that groups by that channel reflects the change on the next refresh. Use a channel classifier when you want to bucket traffic into reusable acquisition groups across every chart and Marketing Hub view. If you only need a one-off derived field for a single chart, use a [derived property](https://amplitude.com/docs/data/derived-properties) on that chart instead. ## Amplitude Default Channels Every new Amplitude org and project gets a pre-built classifier called _\[Amplitude\] Default Channels_ automatically. You don't need to configure anything to get started. Amplitude creates the classifier when you first open _Data > Properties > Channels_. It maps UTM parameters and referrer data into 29 GA4-aligned marketing channels, including: - **Paid Search** and **Organic Search**. - **Paid Social** and **Organic Social**. - **Paid Video** and **Organic Video**. - **Partner** and **External Referral**. - **LLM Search** and **Paid LLM Search** (AI-assisted referrals from tools like ChatGPT and Perplexity). - **Email**, **Display**, **Affiliates**, and **Referral**. - **Audio**, **SMS**, and **Mobile Push**. - **Direct**. - **Other** (traffic that doesn't match any rule). The classifier gives Marketing Hub and the Global Agent useful channel breakdowns from day one, without requiring you to build a classifier from scratch. The classifier is fully editable and deletable. You can rename it, modify rules, change conditions, or remove it entirely. > **Note:** Best results with the browser SDK > > The _\[Amplitude\] Default Channels_ classifier works best with the Amplitude Browser SDK when you carefully manage `set()` and `unset()` calls on UTM properties. Inconsistent property handling can classify traffic as "Other" even when UTM values are present. ### Upgrade to GA4-aligned defaults in an existing org If you created your org before Amplitude introduced the GA4-aligned _\[Amplitude\] Default Channels_, you receive an upgrade prompt when you open _Data > Properties > Channels_. Click **Build with the new logic** to open the classifier builder pre-filled with the updated GA4-aligned rule set. Review the rules, rename the classifier if you like, then click **Save** to add it alongside your existing classifiers. Amplitude never overwrites your existing classifiers. Your current channel definitions remain unchanged until you modify or delete them yourself. You can also add the default classifier at any time without the upgrade prompt: 1. Navigate to _Data > Properties > Channels_. 2. Click **+ Add Channel Classifier**. 3. The _\[Amplitude\] Default Channels_ template opens automatically. Rename it if you like. 4. Customize the rules or click **Save** to add it as-is. Amplitude adds the new classifier without changing any of your existing ones. ## Create a channel You must be an Admin or Manager to create a channel. To create a channel, follow these steps: 1. Navigate to the _Properties_ section of Amplitude Data and open the **Channels** tab. 2. Click **+ Add Channel Classifier**. A pre-built, default channel definition screen opens. Optionally, click the default channel title (_Channel_) to edit the name. You can also add a description below it. 3. To begin creating the channel definition, start from the default template or click **Clear Table** to clear the table's contents. The default template uses the same GA4-aligned rule set as _\[Amplitude\] Default Channels_, covering 27 channels including LLM Search, Paid LLM Search, Audio, SMS, and Mobile Push. You can add multiple properties to a row to create a more complex classifier. > **Tip:** > > Amplitude recommends using user properties rather than event properties for channels, because Amplitude applies user properties to future events that a user triggers. For more information, go to [About user properties and event properties](https://amplitude.com/docs/data/user-properties-and-events#how-amplitude-updates-user-properties). 4. Add one row for each channel you'd like to define. For example, you can add rows labeled `Paid`, `Organic`, `Referral`, and `Direct` to create a high-level channel definition. 5. Fill in the values for each row. Each cell must evaluate to `True` for an event to classify to that channel. If you can define a channel as `row A OR row B`, add one row for A and one for B, then set the channel name to the same value for both rows. 6. Click **Save**. Amplitude labels channels in property dropdowns under the _Channels_ category. > **Note:** Channel classifier limits > > Channel classifiers have two limits: > > - **Maximum rows**: 149 rows for each classifier. > - **Maximum cells**: 1,000 total cells (rows × columns). > > Amplitude restricts adding rows when either limit is reached. The effective maximum number of rows depends on the number of columns in your classifier. For example, with 10 columns, you can create approximately 100 rows before reaching the 1,000-cell limit. ## Compare metrics between channels with Data Tables Amplitude's [Data Tables](https://amplitude.com/docs/analytics/charts/data-tables/data-tables-multi-dimensional-analysis) let you define metrics critical to your bottom line, such as CPA, AOV, and ROAS. Evaluate how these metrics perform between different channels by grouping by your channel on the left-hand column. Add other core dimensions like campaigns to break down these channels further. Amplitude attributes metrics in different ways if a user has multiple touch points with different channels before converting. Amplitude has built [attribution modeling](https://amplitude.com/docs/analytics/charts/data-tables/data-tables-attribute-credit) into data tables to enable defining user attribution in your channels. > **Tip:** > > Applying a channel classifier before an attribution model can attribute values in potentially unexpected ways. For example, in a sequence consisting of: > > `CPC --> email --> website` > > Applying a channel classifier of `CPC only` filters out `email` and `website`. In this case, the attribution model attributes to CPC. ## Use cases - **Blended views**: Create top-level blended views of all paid and all organic traffic to review how efficiency and performance have changed over time. - **High-level channels**: Break down your core metrics using the channel definitions you already use in [Google Analytics](https://support.google.com/analytics/answer/6010097?hl=en#zippy=%2Cin-this-article) and [Adobe](https://experienceleague.adobe.com/docs/analytics/components/marketing-channels/c-getting-started-mchannel.html?lang=en). - **Channels with campaigns**: Add a property denoting a campaign as a column in your channel definitions to break down metrics by campaign channel. - **Attribution**: Use channels with attribution models in data tables to evaluate the breakdown of a metric by first touch, last touch, or a custom attribution definition. ## Special values Amplitude evaluates these special values on events: | **Value** | **Description** | | --- | --- | | ANY | Captures explicitly set `none` values, or any other value set on the property. | | (none) | Captures both explicitly and implicitly set `none` values. | | blank | Captures both explicitly and implicitly set `none` values, or any other value set on the property. | > **Note:** Explicit and implicit none values > > `None` values set both explicitly and implicitly appear as `none` in any Analytics chart. > > Explicitly set `none` values appear when Amplitude receives the property with a value of `null`. > > Implicitly set `none` values appear when Amplitude receives a property with no value. ## Common questions ### Who can create and modify channel definitions? The channels classifier is only available to Growth and Enterprise users. You must be an org admin or manager to create a channel and modify channel definitions. ### Are users notified if channel classifiers change? Amplitude doesn't notify users and other admins when channel classifiers change. Any reports sourced from the channel classifier automatically update to reference the most recent definition the next time someone loads or refreshes a report. ### Where can users use these acquisition channels after defining them? Amplitude stores channels as properties, which you can query through any analytics chart type (including Data Tables). Find your channels by navigating to _Properties_ in Amplitude Data. ### What kind of properties can you use when configuring a channel? You can use, mix, and match any (event, user, group) property in the definition. The channel classifier inherits the combination of the property types. ### Are properties defined retroactively when a channel is created? Yes. All existing charts update retroactively to reflect the new definition the next time someone refreshes the report. ### How can I upload a channel definition? You can't upload a channel classifier definition. To create a channel classifier, manually create a column for every individual property you want to include in the definition. ### Why can't I see my channels in a Data Table? If you use the pre-defined sample Channel Classifier, make sure you track the _utm\_medium_ and _referring\_domain_ properties to generate results in your Data Table. If you don't track these, either remove the column containing them from the Channel Classifier, or instrument them as properties to start tracking them. ### Is the referring domain captured by Amplitude, or do I have to pass this value? You must send Referring Domain, as well as any other properties you track for attribution purposes, such as UTM parameters, to Amplitude. ### Should I set channel classifiers to include _initial\_utm_ and _utm\__ properties so that initial and most recent campaign traffic gets bucketed correctly? Unless you want to create a specific "Initial Channel", don't use or mix any of the _initial\_{} properties_. Focus on the standard/non-initial ones. ### Can I input a regex formula when creating a channel classifier? You can enter the regex as free-form text when creating a channel classifier. ### Why am I seeing '(none)' values when grouping by my channel in a Data Table? You see '(none)' values because you're querying on an event that occurred before Amplitude received that user property. When using Amplitude, you query on the value of a user or event property at the time of the event. The '(none)' value showing for the property in the Data Table when grouping by your channel means there's no value for that property. ### Why can't I add more rows to my channel classifier? Channel classifiers have two limits that restrict adding rows: - **Maximum rows**: 149 rows for each classifier. - **Maximum cells**: 1,000 total cells (rows × columns). Amplitude restricts adding rows when either limit is reached. The UI tooltip shows the 149-row limit, but the 1,000-cell limit may prevent you from reaching that number. For example, with 10 columns, you can create approximately 100 rows before reaching the cell limit. To add more rows, reduce the number of columns in your classifier, or simplify your channel definitions to use fewer cells. ================================================================================ # Persisted Properties URL: https://amplitude.com/docs/data/persisted-properties ================================================================================ # Persisted Properties Property persistence keeps an event property's value, such as page path or search term, attached to a user's later events for a set period. That way, context like which campaign, channel, or merchandising asset drove engagement stays available across the entire user journey and gives teams consistent, reliable reporting across Amplitude. Go to the [Verify persisted properties](https://amplitude.com/docs/data/persisted-properties/verify-persisted-properties) page to confirm that your persisted properties are working correctly. For example: - Marketing teams can persist page path values across multiple sessions to understand campaign effectiveness over time. - Merchandising teams can use [item-level attribution](#advanced-item-level-attribution) to attribute revenue to the search term, recommendation, or promo that drove each item in a cart. ## Persisted properties operate on event properties Persisted properties only persist event properties. They don't read user properties, and they don't update the user profile. Amplitude evaluates them at query time and applies allocation and expiration rules to event-level data for analysis. That distinction matters when you instrument tracking. If the data you want to persist arrives only as a user property, for example, marketing attribution that some integrations only set at the user level, Amplitude can't use it as an input to a persisted property. To make a value available, capture it as an event property on the events you care about. As of Browser SDK version 2.45.0, the Amplitude Browser SDK does this automatically for marketing attribution by default. Refer to [Capture event properties from the SDK](#capture-event-properties-from-the-sdk). ## What persisted properties are and aren't Persisted properties aren't user properties and don't represent long-lived user state. Amplitude evaluates them at query time and applies allocation and expiration rules to event-level data for analysis. Persisted properties don't update the user profile, don't mutate user state, and don't replace core event or user properties. Their purpose is to control how Amplitude applies context such as marketing or merchandising data during analysis. ### What property persistence does Property persistence defines which property values "stick" beyond the event where they were first experienced and how long they remain valid. Instead of requiring every event to include its own source or merchandising data, Amplitude can remember the property value and apply it automatically to later events until it expires or Amplitude replaces it. Property persistence is especially useful in marketing and merchandising analysis, where you want to connect early engagement with later outcomes. ## User properties compared to persisted properties | User properties | Persisted properties | | --- | --- | | Amplitude stores them on the user profile. | Amplitude doesn't store them on the user profile. | | Amplitude sets them at ingest time. | Amplitude evaluates them at query time (for example, when you use a chart). | | Represent user level state. | Apply allocation and expiration rules to event properties. | | Examples include device type, location, or User ID. | For session or time-bounded analysis context. | ## Key concepts ### Allocation types Allocation decides which property value should "stick" across a series of events for the same user. Amplitude provides the following allocation types: - **Original:** The property value Amplitude captures when it first creates the entity. Typically, the original value occurs at the point of account creation or initial identification. The original value persists and never changes. - **Most recent:** Always the latest value of a property within a defined or active tracking window. Typically, the most recent value is the most recent event or session. Most recent data values are dynamic and shift as Amplitude collects new data. - **First known:** The earliest value recorded for that property, regardless of the entity's creation date. If data collection starts after the creation date, the first known value can come from a later point in time than the Original value. Applies to all events before and after. - **Last known:** The most recent value of a property at any given point in time. Last known values are dynamic and shift as Amplitude collects new data. However, if Amplitude can't collect data, the Last known value may differ from the true state of the property. Applies to all events before and after. > **Note:** Differences between allocation types > > The Original value is the true first value and occurs as soon as Amplitude creates the entity. The First Known value is the earliest recorded value. These values can be the same if tracking begins at entity creation. However, if tracking begins later, these values may differ. > > The Most recent value is the most recent value and occurs every time Amplitude collects new data about the property. The Most recent value always reflects the most recent state of the property. The Last known value is the last recorded value of the property. If tracking doesn't occur or Amplitude stops collecting data, the Last known value may not be the current state of the property. If tracking and data collection are current, the Most recent and Last known values are identical. The table below displays an example of a user's activity, from sign-up through page views to purchase. The first column shows the events and property values as they exist in the dataset. The remaining four columns show different allocation methods and how property values change under each method. | Event | Dataset Value | Original | Most Recent | First Known | Last Known | | --- | --- | --- | --- | --- | --- | | Sign up | page path: not captured | - | - | /gift\_guide ◌ | /best\_seller ◌ | | Page View | page path: /gift\_guide | /gift\_guide ● | /gift\_guide ● | /gift\_guide ● | /best\_seller ◌ | | Page View | page path: /flash\_sale | /gift\_guide ◌ | /flash\_sale ● | /gift\_guide ◌ | /best\_seller ◌ | | Purchase | page path: not captured | /gift\_guide ◌ | /flash\_sale ◌ | /gift\_guide ◌ | /best\_seller ◌ | | Page View | page path: /best\_seller | /gift\_guide ◌ | /best\_seller ● | /gift\_guide ◌ | /best\_seller ● | ● = Property value present on the event ◌ = Property value filled by allocation ### Expiration Expiration defines when a persisted property value stops applying. | Expiration type | What it means | Example use case | | --- | --- | --- | | Session | Value resets when the session ends. | Attribute product engagement per browsing session. | | Custom time | Value expires after a chosen duration. | Maintain campaign context for 7 days or a maximum 30 days. | ## Common use cases Persisted properties make sense any time you want analysis to reflect context from earlier (or later) events than the one being measured. The patterns below come up repeatedly across marketing, merchandising, experimentation, and media analytics. - **Entry-page attribution.** Group conversions by where the session originally started, even when the conversion event doesn't carry Page Path. Config: `Page Path` + Original + Session. - **Campaign attribution across sessions.** Connect early marketing touchpoints to later conversions without forcing every event to carry UTMs. Pairs well with [Browser SDK event-property attribution tracking](#marketing-attribution-browser-sdk-2) (on by default as of version 2.45.0). Config: `utm_campaign` (or similar) + Original + Custom time, for example 30 days. - **Item-level discovery attribution.** Each item in a cart keeps its own discovery source — search, recommendation, or homepage hero — so revenue attributes to the right surface per product. Refer to [Advanced: Item-level attribution](#advanced-item-level-attribution). Config: `discovery_method` + Most recent + Session + item-level binding. - **A/B test exposure persistence.** Carry the variant a user saw forward to all downstream events, even when the experimentation platform only stamps the variant on the exposure event itself. Config: `experiment_variant` + Original or Most recent + Session or User. - **Channel attribution that ignores internal navigation.** Persist the channel that brought a user in without letting internal page-to-page clicks overwrite it. Refer to [Filter internal referrers from attribution](#filter-internal-referrers-from-attribution). Config: channel property + Most recent + Session + Excluded values. - **Retroactive attribution when properties arrive late.** **First known** and **Last known** apply values to events that already happened, not just events going forward. Useful when the trigger event and its attribution data don't arrive together: - Mobile install attribution. `New User` and install events often land in Amplitude before the MMP (AppsFlyer, Adjust) sends the attribution event. A persisted property with Last known allocation attaches the source back to the install, so you can measure which campaign drove each install. - Streaming and media metadata. Real-time play events fire during a session, but properties like `program`, `genre`, or `content_id` are often only sent at session close. A persisted property with Last known allocation applies that metadata backwards to every play event in the session. Config: attribution or metadata property + Last known (or First known) + Session or a longer window. ## Capture event properties from the SDK Persisted properties read from event properties, so the upstream question is making sure the values you want to persist arrive as event properties in the first place. ### Marketing attribution (Browser SDK 2) As of Browser SDK version 2.45.0 and GTM template version 5d7e5, attribution tracking via event properties is on by default. UTM parameters, referrer, referring domain, and click identifiers (for example `gclid`, `fbclid`) automatically attach to every event as event properties. Attribution event properties arrive immediately on Browser SDK 2.45.0+ and GTM template 5d7e5+. First-touch attribution is tracked only with user properties. Multi-touch attribution can use either user properties or event properties, but Amplitude recommends event properties. Event properties retain the campaign context on each event and can be used as inputs to persisted properties and multi-touch attribution models. For details about what event property tracking captures and how to configure it, refer to [Event property tracking](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#event-property-tracking) in the Browser SDK 2 documentation. > **Note:** SDK versions below 2.45.0 or GTM template versions below 5d7e5 > > On older SDK or GTM template versions, event property tracking is opt-in. Enable it by setting `trackingMethod`. > > **SDK (direct installation)** > > ```js > import * as amplitude from '@amplitude/analytics-browser'; > > amplitude.init('AMPLITUDE_API_KEY', { > autocapture: { > attribution: { > trackingMethod: ['userProperty', 'eventProperty'], > }, > }, > }); > ``` > > **Google Tag Manager** > > Set the tracking method through a configuration variable: > > 1. Update your **Amplitude Analytics Browser SDK** tag to the latest version when GTM shows the update. Event-property attribution requires Browser SDK 2.40.0 or later. > 2. Go to _Variables > User-Defined Variables > New_, search the Community Template Gallery for **Amplitude Browser SDK Configuration Variable**, and install it. > 3. Create a variable from that template and set **Tracking method** to `eventProperty`. To keep user-property attribution as well, set both `userProperty` and `eventProperty`. Amplitude recommends this while migrating. > 4. In the Amplitude `init` tag, set **New configuration options** to your variable (`{{Your Variable}}`). > 5. Publish the container. > > **New configuration options** replaces the entire `autocapture` object (shallow merge), so list the autocapture features you use, not just `trackingMethod`. Otherwise the tag drops those features. For more information, refer to [New configuration options](https://amplitude.com/docs/data/source-catalog/google-tag-manager#new-configuration-options). > > For example, mirroring a typical setup: > > ```js > { > autocapture: { > pageViews: true, > sessions: true, > formInteractions: true, > attribution: { > trackingMethod: ["userProperty", "eventProperty"] > } > } > } > ``` ### Auto-captured page and interaction properties When you enable [Autocapture](https://amplitude.com/docs/get-started/autocapture), Amplitude automatically captures event properties such as Page Path, Page URL, Page Title, Element Text, and File Name on the relevant events. Any of these can become an input to a persisted property — for example, persisting Page Path with `Original` allocation captures the entry page that started the session. ### Custom event properties You can persist any event property your team sends, including custom properties such as `discovery_method`, `experiment_variant`, or `internal_search_term`. As long as the value travels on at least one event for the user, persisted properties can carry it forward. ## Set up persisted properties The following section contains examples for using the _Persistence and Advanced settings_. Review each one as they apply to different ways you can implement persisted properties. 1. Navigate to the _Properties_ section of Data Settings and then click to create a new persisted property. Give this persisted property a name, such as `Entry Page`. In the description, provide additional information such as the allocation method and expiration. The description helps make sure that anyone using this property in a chart or data table understands the configuration. 2. Select the event property you want to persist. For this example, use `Page Path`. 3. Choose an **Allocation** method. In the example, because you want to identify the `Entry Page`, select **Original**. Selecting **Original** makes sure you include the first touchpoint. 4. Set the **Expiration**. By default, the persisted property expires at the end of the session. 5. (_Optional_) Configure **Excluded values**. Add any property values you want the persisted property to ignore — for example, internal traffic markers, test values, or specific channels you don't want to overwrite the persisted source. Amplitude doesn't treat excluded values as new property values during allocation, so a previously valid value continues to persist through them. For a common use case, refer to [Filter internal referrers from attribution](#filter-internal-referrers-from-attribution). If your analysis involves merchandising (item-level attribution), refer to the [Advanced: Item-level attribution](#advanced-item-level-attribution) section. Otherwise, go to [Use persisted properties across analyses](#use-persisted-properties-across-analyses). ## Filter internal referrers from attribution When a user navigates within your own site, the referrer is your own domain. If you classify referrers into channels and persist that channel with **Most recent** allocation, every internal page-to-page click can overwrite the original marketing source — attribution flips to "internal" or "direct" the moment the user moves to a second page. Use **Excluded values** on the persisted property to skip internal navigation during allocation. The previously valid value — the campaign or external referrer that originally brought the user in — continues to apply through any internal events. ### set up a filter for internal referrers: 1. **Create a channel** in _Data → Channels_ that classifies your traffic sources. Add a definition that maps your own domain (in the `referrer` event property) to a channel value such as `internal`. 2. **Create a persisted property** in _Data → Properties_ that uses your channel as the event property. Set **Allocation** to **Most recent** and **Expiration** to match your analysis (commonly **Session**). 3. In the persisted property's **Excluded values** field, add the channel value you want to ignore — for example, `internal`. Persisted properties treat excluded values as if the property weren't on the event at all, so allocation rolls forward from the previous valid value. 4. Use the persisted property in your charts. Internal navigation no longer resets the persisted source; the original campaign or referrer continues to attribute downstream events such as `Add to Cart` or `Purchase`. The same pattern works for any value you want allocation to ignore — internal QA traffic, bot signatures, or test events — not just internal referrers. ## Achieve last non-direct touch attribution Last non-direct touch attribution assigns credit to the most recent marketing channel a user engaged with before converting, skipping over direct visits. Persisted properties can replicate this model. This is the attribution model used for user-scoped and session-scoped dimensions in Google Analytics. Attribution event properties such as `referrer` and UTM parameters attach to every event by default on Browser SDK 2.45.0+ and GTM template 5d7e5+. You don't need to change your SDK or GTM configuration before following these steps. ### How it works Persisted property allocation automatically skips events where the property has no value, so direct visits with no channel value don't overwrite the persisted source. If a user enters through Paid Search, browses, returns directly later, and converts, the conversion event still attributes to Paid Search. The setup combines two configurations: - A channel classifier that doesn't assign "Direct" as a catch-all fallback. Direct sessions arrive without a channel value rather than with a Direct value. - A persisted property that renames `(none)` to "Direct" for display, so genuinely unattributed users still appear under a named value rather than blank. ### Set up the persisted property 1. Go to _Data → Properties_ and create a new persisted property. 2. Select your channel classifier output (for example, `Marketing Channel`) as the event property. 3. Set **Allocation** to **Most recent**. 4. Set **Expiration** to a window that matches your business cycle, such as 7 days. 5. In **Rename (none) values**, enter `Direct`. Users with no attributed channel display as "Direct" rather than blank. ### Configure the channel classifier In _Data → Channels_, make sure your classifier defines explicit rules for each channel — Paid Search, Organic Social, Email, and so on. Don't add a catch-all rule that assigns Direct to everything else. With no catch-all, direct sessions arrive without a channel value, and the persisted property carries the most recent non-direct channel forward. ### Supported metrics This approach works with **Event Totals**, **Session Totals**, and **Unique counting** mechanisms in Data Tables. Amplitude doesn't support changing the attribution method within data tables when you use a persisted property as a group-by, so multi-touch attribution models don't apply. ### Related pattern: Excluded values for named traffic If you want to skip specific _named_ values during allocation — for example, an "internal" channel for same-domain referrers, QA traffic, or bot signatures — use **Excluded values** on the persisted property. Refer to [Filter internal referrers from attribution](#filter-internal-referrers-from-attribution). The Rename `(none)` approach above is the right tool when direct visits arrive as fully unattributed sessions; Excluded values is the right tool when allocation needs to skip a specific value the classifier emits. ### Verify the setup After you configure the property and the classifier, follow the [verify persisted properties guide](https://amplitude.com/docs/data/persisted-properties/verify-persisted-properties) to confirm direct visits don't overwrite the persisted channel for users who arrived through marketing. ## Advanced: Item-level attribution Item-level attribution typically powers merchandising analyses. It ties a persisted property to a specific item inside a cart event, rather than to the user or the session as a whole. When a cart contains multiple items, each item keeps its own persisted context (the search term, recommendation, or promo that influenced that specific item). Metrics such as `Revenue` reflect the source that drove each item individually. This is the configuration that powers the [Product Discovery hub](https://amplitude.com/docs/analytics/ootb-ecommerce-analytics#product-discovery) in Out-of-the-box E-commerce Analytics. For example, a single cart contains three items, and the user discovered each one a different way: - The user discovered Item 1 through Search. - The user discovered Item 2 from the Popular Products display. - The user discovered Item 3 from Recommendations. Without item-level attribution, Amplitude credits all conversion events for the entire order to a single discovery method. With **Original** allocation, on-site Search receives all the credit. With **Most Recent**, Recommendations receives the credit. Item-level attribution instead credits the correct discovery method to each item in the cart. ### Set up the persisted property 1. Create a new persisted property called `Most recent Finding Method`. 2. Select the event property you want to persist. For this example, use `discovery_method`. 3. Choose an **Allocation** method. Because you want the last touchpoint, select **Most Recent**. 4. To credit the first touchpoint instead, select **Original**. 5. Set the **Expiration**. By default, the persisted property expires at the end of the session. After you create the property, configure item-level attribution. ### Configure item-level attribution 1. Select the product identifier you use. Ideally, use an item property in an `Object Array` such as `product.item_id`. For more on object arrays, refer to [Cart Analysis](https://amplitude.com/docs/analytics/charts/cart-analysis). 2. Select one or more **linking events**. These are events that carry both the persisted property value (such as `discovery_method`) and the item identifier (`product.item_id`). These are typically the events where the user interacts with an item, such as `View Item Details`, `Home Hero Clicked`, `Promotion Clicked`, `Recommendation Clicked`, or `Add to Cart`. Linking events let Amplitude tie the engagement signal to the specific item. Amplitude then carries the persisted value forward to cart events (`Add to Cart`, `Remove from Cart`, `Purchase`) per item, using the product identifier as the join key. ### Verify the setup After you save the property, the persisted value appears as a column on the linking and cart events. Use the [Verify a property with item-level attribution](https://amplitude.com/docs/data/persisted-properties/verify-persisted-properties#verify-a-property-with-item-level-attribution) section of the verify guide to confirm each item shows the expected value. ## Use persisted properties across analyses After you define a persisted property (such as `Entry Page` or `Most Recent Finding Method`), Amplitude automatically applies it to upstream/downstream events based on the allocation and expiration rules you've configured. You don't need to manually re-attribute or make sure the original property exists on every event. You can use persisted properties anywhere you select event properties in Amplitude: - **Data Tables**: Group, filter, and break down rows by persisted properties. - **Event Segmentation**: Segment, group by, or filter charts using persisted properties. - **Funnels**: Apply persisted properties to funnel steps or as group-bys for downstream conversion analysis. - **Cohorts**: Define audiences using persisted property values, including in inline cohorts. Persisted properties appear in property selectors alongside standard event properties under the name you gave them in Data Settings (for example, `Entry Page`). You can access the context you captured earlier wherever you analyze outcomes. For example: - **Entry Page (Original, Session)**: A user lands on `/mens-shoes`, browses several pages, then completes a purchase. Even though the `Purchase` event doesn't include `Page Path`, your persisted `Entry Page` still displays `/mens-shoes`, letting you group purchases by where sessions originally started. - **Most recent Finding Method (Most recent, Session)**: A user first discovers a product through `Search`, later clicks a `Recommendation`, and finally adds the item to cart. Because you set the allocation to `Most recent`, the persisted value on `Add to Cart` and `Purchase` is `Recommendation`, reflecting the last touchpoint before conversion. For merchandising teams using the advanced setup: - Amplitude carries product-level context (such as `Finding Method` or `homepage module`) forward to cart and purchase events using the product identifier you configured. - If a cart contains multiple items, each item keeps its own persisted value. Amplitude attributes revenue, AOV, and add-to-cart metrics to the correct source for each product. This lets you: - Group or filter outcome events (`Add to Cart`, `Purchase`, or `Revenue`) by persisted properties in data tables. - Measure which entry pages, homepage modules, or recommendation zones drive conversions. - Analyze results consistently across charts without rebuilding attribution logic each time. ## Product Discovery hub The [Product Discovery hub](https://amplitude.com/docs/analytics/ootb-ecommerce-analytics#product-discovery) in E-comm Analytics uses persisted properties to power its **Which properties describe how users discover your product?** breakdown. The hub lets you attribute purchases and revenue to the discovery method that influenced each item in the cart. For example, if a user discovers one product through on-site search and another through a homepage recommendation, item-level attribution assigns revenue to the correct discovery source for each product individually. To configure a persisted property for Product Discovery: 1. Create a persisted property that captures your discovery context. For example, `Most Recent Finding Method` using the `discovery_method` event property. 2. Set **Allocation** to **Most Recent** to capture the last discovery action before the cart event. 3. Set **Expiration** to **Session** so discovery context resets at the end of each session. 4. Enable **Item-level attribution** and select your product identifier (for example, `product.item_id`). 5. Select the events where both your discovery property and product identifier are present (for example, `View Item Details` or `Add to Cart`). After you configure the property, select this persisted property in the Product Discovery hub under **Which properties describe how users discover your product?**. Amplitude uses item-level attribution to credit each item's revenue to the correct discovery source. For a detailed walkthrough of setting up item-level attribution, refer to [Advanced: Item-level attribution](#advanced-item-level-attribution). ## Multiple groupbys You can group by more than one property in the same data table to combine persisted context with regular event data. For example, you can group purchases by `Entry Page` and `Most Recent Finding Method` to understand how session entry points and discovery behavior work together. Add additional groupbys by clicking **Add top-level group-by** at the top of a data table column. When you include multiple properties in the same analysis, Amplitude evaluates each property independently. **If both properties are persisted:** - Amplitude populates each property using its own allocation and expiration rules. - For example, `Entry Page` reflects where the session started (`Original`, `Session`), while `Most recent Finding Method` reflects the last discovery action before conversion (`Most recent`, `Session`). - Both values appear on outcome events such as `Add to Cart` or `Purchase`, even if those events didn't originally contain them. **If only some properties are persisted:** - Persisted properties retain their computed values based on their configuration. - Amplitude takes non-persisted properties directly from the outcome event being analyzed. For example, `Entry Page` comes from persistence, while `Device Type` comes from the `Purchase` event itself. **If none are persisted:** - All property values come as-is from the outcome events, with no carryover from earlier interactions. You can combine journey context and event-level attributes in a single table, knowing that persisted properties keep their defined behavior while regular properties reflect what happened at the moment of conversion. ## Availability and limitations - You can use persisted properties in Data Tables, Event Segmentation, Funnels, and Cohorts. - Support in Stickiness, Composition, Growth Accounting, Revenue LTV, Impact, and Customer Journeys is coming soon. - Persisted properties don't appear on the user profile. - Raw data exports such as BigQuery don't include persisted property values. Amplitude computes them at query time, not at ingest, so they aren't materialized on the underlying events. - Data tables support a 6-month time range when you select a persisted property. ## Attribution compared to persistence Persistence controls how long property context remains available, while attribution controls how Amplitude assigns conversion credit. They solve related, but distinct, problems. You configure them independently. If, after reading this article, the difference between attribution and persistence in Amplitude still isn't clear, review the following summary: | Concept | Attribution | Property persistence | | --- | --- | --- | | Scope | Metric-level (applies across properties) | Property-level (applies across Metrics). | | What it does | Assigns conversion credit to a campaign, product, or channel. | Keeps those property values active across time. | | Where defined | In Data Tables. | In project-level data settings. | | Where it's used | In Data Tables. | In Data Tables, Event Segmentation, Funnels, and Cohorts. | | Used for | Deciding who gets credit. | Making sure the right context exists for that credit. | | Example | "Which campaign drove this purchase?" | "Which campaign or product should this purchase be associated with?" | | Supported Allocation Models | Linear, Participation, U-shaped, J-shaped, Inverse J-shaped, Data driven, Custom. | Original (First touch), Most recent (Last touch), First known, Last known. | | Multi-property semantics (Data tables) | Amplitude applies attribution only to the outermost groupby property. The rest of the properties follow the attributed event: [attribution with multiple properties](https://amplitude.com/docs/analytics/charts/data-tables/data-tables-attribute-credit#attribution-with-multiple-properties). | If there are multiple persisted properties, Amplitude persists each property individually. The persisted property also doesn't have to be the outermost [groupby property](#multiple-groupbys). | ================================================================================ # Aggregated Metric Calculations URL: https://amplitude.com/docs/data/warehouse-metric-calculations ================================================================================ # Aggregated Metric Calculations When you create an Aggregated Metric, Amplitude provides calculation definitions (Sum, User Average, Min, and Max) that determine how numeric values aggregate from your connected warehouse table. These calculation types help you choose the right measurement for your business or product question. ## Sum calculation Use the Sum calculation to measure total values, for example, total revenue, total purchases, or total number of sign-ups during a period. This option adds up all numeric values from the selected column (such as `revenue` or `count`) across all rows returned from your warehouse query. ### Definition Adds all numeric values from newly imported rows. Amplitude doesn't apply per-user grouping. Each row contributes its full value to the total. ### Example | User ID | Daily Spend | Timestamp | | --- | --- | --- | | U1 | 2 | 01 Jan 2025 | | U1 | 5 | 06 Jan 2025 | | U2 | 3 | 01 Jan 2025 | | U3 | 10 | 03 Jan 2025 | | U3 | 0 | 04 Jan 2025 | | U3 | 5 | 06 Jan 2025 | $$ \text{Sum of Daily Spend = } 2 + 5 + 3 + 10 + 0 + 5 = 25 $$ ### When to use Sum | Use Case | Description | | --- | --- | | Revenue and spend tracking | Measure total revenue or spend from all users. | | Event counts | Count total events (such as purchases or sessions). | | Operational totals | Aggregate numeric values like impressions or transactions. | Example question: > What's the total revenue generated this month? ## User Average calculation Use the User Average calculation to measure average user-level behavior, for example, the average weekly spend per user or average number of sessions per user. ### Definition Amplitude first aggregates data per user (summing values such as daily spend to get weekly totals), then computes the average of those per-user totals across all users. Each user contributes equally to the final metric. ### Example | User ID | Daily Spend | Timestamp | | --- | --- | --- | | U1 | 2 | 01 Jan 2025 | | U1 | 5 | 06 Jan 2025 | | U2 | 3 | 01 Jan 2025 | | U3 | 10 | 03 Jan 2025 | | U3 | 0 | 04 Jan 2025 | | U3 | 5 | 06 Jan 2025 | Step 1: Per-user roll-up (SUM) | User | User Sum | | --- | --- | | U1 | 7 | | U2 | 3 | | U3 | 15 | Step 2: Average across users $$ \frac{7 + 3 + 15}{3} = 8.33 $$ Each user contributes one aggregated value (sum) to the final average. ### When to use User Average | Use Case | Description | | --- | --- | | Experiment metrics | Align with Experiment's User Average computation for A/B testing. | | Per-user KPIs | Measure average user engagement, revenue, or behavior. | | Behavioral analysis | Understand what a _typical_ user does, rather than total activity. | Example question: > What's the average total spend per user this week? ## Min calculation Use the Min calculation when you need to find the lowest value observed within the selected time window or user group. Min answers questions like "What's the minimum purchase amount a user made this week?" or "What's the lowest daily spend among all users?" ### Definition Amplitude first determines each user's minimum value within the selected column and time bucket, then selects the lowest value overall. ### Example | User ID | Daily Spend | Timestamp | | --- | --- | --- | | U1 | 2 | 01 Jan 2025 | | U1 | 5 | 06 Jan 2025 | | U2 | 3 | 01 Jan 2025 | | U3 | 10 | 03 Jan 2025 | | U3 | 0 | 04 Jan 2025 | | U3 | 5 | 06 Jan 2025 | Per-user minimums: | User | Min Spend | | --- | --- | | U1 | 2 | | U2 | 3 | | U3 | 0 | $$ \text{Overall Min} = 0 $$ ### When to use Min | Use Case | Description | | --- | --- | | Performance baselines | Track the lowest measured metric (such as minimum daily revenue). | | Data quality checks | Identify outliers or unexpected zeros. | | Threshold analysis | View the minimum observed value across users or segments. | Example question: > What's the minimum spend any user recorded this month? ## Max calculation Use the Max calculation to find the highest value observed within the selected time window or user group. Max answers questions such as "What's the maximum amount a user spent in a day?" or "What's the peak Lifetime Value (LTV) achieved so far?" ### Definition Amplitude first finds each user's maximum value within the selected column and time bucket, then returns the highest value overall. ### Example | User ID | Daily Spend | Timestamp | | --- | --- | --- | | U1 | 2 | 01 Jan 2025 | | U1 | 5 | 06 Jan 2025 | | U2 | 3 | 01 Jan 2025 | | U3 | 10 | 03 Jan 2025 | | U3 | 0 | 04 Jan 2025 | | U3 | 5 | 06 Jan 2025 | Per-user maximums: | User | Max Spend | | --- | --- | | U1 | 5 | | U2 | 3 | | U3 | 10 | $$ \text{Overall Max} = 10 $$ ### When to use Max | Use Case | Description | | --- | --- | | Performance tracking | Track the highest spend, usage, or value recorded. | | Capacity analysis | Monitor peak activity levels or spikes. | | Goal attainment | Identify the best performing users or time periods. | Example question: > What's the maximum amount a single user spent in one day? ## Summary: Choose between calculation types | Calculation | Aggregation Logic | Use When You Want to Measure… | Example Metric | | --- | --- | --- | --- | | Sum | Adds all numeric values (no per-user grouping) | Total activity or revenue | Total Purchases | | User Average | Sum per user, then average across users | Typical user behavior | Average Weekly Spend per User | | Min | Minimum per user, then select lowest value | Minimum observed value | Lowest Daily Spend | | Max | Maximum per user, then select highest value | Maximum observed value | Peak Daily Spend | ================================================================================ # Data Mutability Features URL: https://amplitude.com/docs/data/data-mutability ================================================================================ # Data Mutability Features Data mutability applies `INSERT`, `UPDATE`, and `DELETE` operations from your warehouse to event data already in Amplitude, so corrections, late-arriving rows, and deletions in your source of truth propagate to your analytics. Mirror Sync delivers these operations from Snowflake, Databricks, Google BigQuery, and Amazon S3. Turn on Mirror Sync when your warehouse is the source of truth and rows there change after first write, such as GDPR or CCPA deletions, backfilled corrections, or late-arriving updates. Stay on standard append-only ingestion when events never change after they land. If you only need to fix mislabeled or duplicate data without connecting a warehouse, use [transformations](https://amplitude.com/docs/data/transformations) instead. ## Supported data sources Data Mutability is available through the following warehouse integrations. ### Snowflake - **Mirror Sync** strategy with Change Data Capture (CDC). - Supports `INSERT`, `UPDATE`, and `DELETE` operations. - Requires Change Tracking enabled on source tables. - [Learn more about Snowflake integration →](https://amplitude.com/docs/data/source-catalog/snowflake). ### Databricks - **Mirror Sync** strategy with Change Data Feed (CDF). - Supports `INSERT`, `UPDATE`, and `DELETE` operations. - Requires Change Data Feed enabled on Delta tables. - [Learn more about Databricks integration →](https://amplitude.com/docs/data/source-catalog/databricks). ### Google BigQuery (Beta) - **Mirror Sync** strategy with BigQuery's `CHANGES()` change history. - Supports `INSERT`, `UPDATE`, and `DELETE` operations for the Event data type. - Requires change history enabled on source tables (`enable_change_history = TRUE`). - [Learn more about BigQuery integration →](https://amplitude.com/docs/data/source-catalog/bigquery#mirror-sync-with-change-data-capture-cdc). ### Amazon S3 - **Mirror Sync** strategy for file-based mutations. - Supports `INSERT`, `UPDATE`, and `DELETE` operations. - Requires structured mutation metadata in your data files. - [Learn more about Amazon S3 integration →](https://amplitude.com/docs/data/source-catalog/amazon-s3). ## How Mirror Sync works When you enable Mirror Sync with data mutability: 1. **Change detection**: The integration monitors your warehouse for data changes using native change tracking features (CDC for Snowflake, CDF for Databricks, `CHANGES()` change history for BigQuery, or file metadata for S3). 2. **Operation processing**: Amplitude processes three types of operations: - `INSERT`: Adds new events to Amplitude. - `UPDATE`: Modifies existing events in Amplitude. - `DELETE`: Removes events from Amplitude. Amplitude finds matching events based on the combination of `user_id`, `insert_id`, and `event_time`. All three fields must match before Amplitude can identify and modify the correct event. 3. **Data synchronization**: Changes apply to keep consistency between your warehouse and Amplitude. ## Enrichment services > **Warning:** Enrichment Services Disabled > > When using Mirror Sync with data mutability, Amplitude disables enrichment services, including: > > - ID resolution and user merging. > - Property and attribution syncing. > - Location resolution. > - Taxonomy validation. > > Disabling enrichment ensures your data remains exactly as it exists in your source of truth. ## General requirements - **User ID required**: All events must contain a user ID. Mirror Sync doesn't support anonymous events. - **Unique Insert ID**: Each event should have a unique and immutable `insert_id` to prevent duplication. - **Chronological order**: Process events in chronological order when possible. ## Event volume considerations > **Note:** Event Volume Impact > > Data mutations count toward your event volume: > > - **Warehouse sources (Snowflake, Databricks, BigQuery)**: Multiple operations on the same event within a sync window count as one event. > - **File sources (S3)**: Each operation counts separately toward your event volume. > > Monitor your usage and contact sales if you need additional event volume. ### Data retention - **Snowflake**: `DATA_RETENTION_TIME_IN_DAYS` must be ≥ 1 (recommended: ≥ 7 days). - **Databricks**: Change Data Feed retention must cover your sync frequency. - **BigQuery**: The table's time-travel window must cover your sync frequency (default seven days, configurable from two to seven days). - **S3**: Files must remain accessible throughout processing. ## Best practices Keep the following best practices in mind as you enable data mutability. ### Plan your implementation 1. **Start with a test project**: Create a dedicated test environment to validate your mutation logic before implementing in production. 2. **Design for idempotency**: Build your mutation operations so you can retry them safely without causing data inconsistencies. 3. **Monitor data quality**: Implement validation checks to ensure mutations apply correctly. ### Data privacy compliance When using data mutability for privacy compliance: 1. **Stop data flow first**: Before you delete user data, ensure you send no new data about that user to Amplitude. 2. **Use User Privacy API**: For complete user deletion, use the [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy) with warehouse deletions. 3. **Verify deletion**: Confirm that deleted data no longer appears in your analytics. ### Performance optimization - **Batch operations**: Group related mutations together when possible. - **Optimize sync frequency**: Balance data freshness needs with processing overhead. - **Monitor resource usage**: Track warehouse compute costs associated with change tracking. ## Migrate to data mutability If you're migrating from a standard ingestion strategy to Mirror Sync, follow these steps. ### Recommended migration steps 1. **Create cutoff strategy**: - Modify the existing connection with a time filter (for example, `WHERE time < {cutOffDate}`). - Set the cutoff date to tomorrow in milliseconds since epoch. 2. **Wait for cutoff**: Allow the cutoff date to pass and verify no new data flows through the old connection. 3. **Create new Mirror Sync source**: - Configure the new source with a complementary filter (for example, `WHERE time >= {cutOffDate}`). - Enable Mirror Sync with the mutation settings you want. 4. **Clean up**: Remove the old source connection after verifying the new one works correctly. ## Common issues ### Events don't update - Verify that change tracking is enabled on source tables. - Check that events contain required user IDs. - Confirm sync frequency settings. ### Missing deletions - Ensure DELETE operations are properly configured in your source. - Verify that deleted events had valid user IDs. - Check that change retention periods haven't expired. ### Data inconsistencies - Review mutation operation ordering. - Verify that Amplitude disabled enrichment services as expected. - Check for timing issues between warehouse changes and sync execution. ================================================================================ # Source catalog URL: https://amplitude.com/docs/data/source-catalog Updated: 2024-07-25 ================================================================================ # Source catalog ================================================================================ # Understand the data differences between Amplitude, Snowflake, and the Export API URL: https://amplitude.com/docs/data/sources/export-api-differences ================================================================================ # Understand the data differences between Amplitude, Snowflake, and the Export API Amplitude charts, Snowflake data, Redshift data, and Export API results can show different data for the same date range. These differences often relate to the [event time](https://amplitude.com/docs/analytics/user-data-lookup) that each platform uses. [Snowflake](https://amplitude.com/docs/data/destination-catalog/snowflake) and the [Export API](https://amplitude.com/docs/apis/analytics/export) use UTC event time. Amplitude charts use the project's configured time zone. ## Why Amplitude and Snowflake data can differ If the Amplitude project time zone differs from UTC, Amplitude charts and Snowflake can show different data. When you compare data, compare equivalent queries. For example, if you query event totals in Snowflake, compare those results to the event totals tab in the Event Segmentation chart. ## Why Amplitude and Export API data can differ The date range in an Export API query uses the time when Amplitude servers received the event data. This time corresponds to the `server_upload_time` field. Because Export API queries use `server_upload_time`, Export API results can differ from the data shown in Amplitude charts. ================================================================================ # Profiles URL: https://amplitude.com/docs/data/profiles ================================================================================ # Profiles Profiles join customer profile data from your data warehouse with the behavioral product data already in Amplitude. Profiles act as standalone properties. Each one attaches to a user profile instead of to a specific event, so it differs from a traditional user property and supports more expansive analyses. Profiles always display the most current data synced from your warehouse. Use Profiles when you need the current value of a user attribute, such as a propensity score or account tier. To import precomputed metric values that change over time, such as revenue or health scores, use [Aggregated Metrics](https://amplitude.com/docs/data/warehouse-metrics) instead. ## Before you begin Regardless of whether you're using Snowflake or Databricks, Change Data Capture (CDC) doesn't support replacing existing tables. Instead, you must use incremental modeling. If the table you integrate with drops and replaces data, the connection breaks. ### Profiles limits | Plan | Limits | | --- | --- | | Enterprise | 1 billion operations (insert / update / delete) per month | | Growth | 300 million operations (insert / update / delete) per month | Each profile must reference a `user_id`. ### Snowflake users If this is your first time importing data from this table, set a data retention time and enable change tracking in Snowflake with the following commands: ```sql ALTER TABLE DATAPL_DB_STAG.PUBLIC.PROFILES_PROPERTIES_TABLE_1 SET DATA_RETENTION_TIME_IN_DAYS = 7; ALTER TABLE DATAPL_DB_STAG.PUBLIC.PROFILES_PROPERTIES_TABLE_1 SET CHANGE_TRACKING = TRUE; ``` On Snowflake Standard Edition plans, the maximum retention time is one day. If you're on this plan, set the frequency to 12 hours in later steps. ### Databricks users Follow these instructions to [enable change tracking](https://docs.databricks.com/en/delta/delta-change-data-feed.html#enable): - If you're working with a new table, set the table property `delta.enableChangeDataFeed = true` in the `CREATE TABLE` command: `CREATE TABLE student (id INT, name STRING, age INT) TBLPROPERTIES (delta.enableChangeDataFeed = true)` Also set `spark.databricks.delta.properties.defaults.enableChangeDataFeed = true` for all new tables. - If you're working with an existing table, set the table property `delta.enableChangeDataFeed = true` in the `ALTER TABLE` command: `ALTER TABLE myDeltaTable SET TBLPROPERTIES (delta.enableChangeDataFeed = true)` Set a [data retention period](https://docs.databricks.com/en/delta/history.html#configure-data-retention-for-time-travel-queries). The period must be at least one day, but in most cases set this period to seven days or longer. If your retention period is too short, the import process can fail. ## Set up a profile (Snowflake users) To set up a profile in Amplitude, follow these steps: 1. In Amplitude Data, navigate to _Connections Overview_. Then in the _Sources panel_, click **Add More**. Scroll down until you find the Snowflake tile and click it. 2. On the _Set Up Connection_ tab, connect Amplitude to your data warehouse by filling in all the relevant fields under _Snowflake Credentials_, which the [Snowflake Data Import guide](https://amplitude.com/docs/data/source-catalog/snowflake#set-up-and-verify-the-connection) outlines. You can either create a new connection, or reuse an existing one. Click **Next** when you're done. 3. You can find a list of your tables under _Select Table_. To begin column mapping, click the table you want. 4. In the list of required fields under _Column Mapping_, enter the column names in the appropriate fields to match columns to required fields. To add more fields, click **+ Add field**. 5. On the _Select Data_ tab, select the `profiles` data type. Amplitude pre-selects the required change data capture import strategy for you, which appears under the _Select Import Strategy_ dropdown: - **Insert**: Always on, creates new profiles when added to your table. - **Update**: Syncs changes to values from your table to Amplitude. - **Delete**: Syncs deletions from your table to Amplitude. 6. When you're done, click **Test Mapping** to verify your mapping information. Then click **Next**. 7. Name the source and set the frequency at which Amplitude refreshes your profiles from the data warehouse. Set the frequency to 12 hours if you're on Snowflake Standard Edition. ## Set up a profile (Databricks users) To set up a profile in Amplitude, follow these steps: 1. In Amplitude Data, navigate to _Connections Overview_. Then in the _Sources_ panel, click **Add More**. Scroll down until you find the Databricks tile and click it. 2. In the _Set Up Connection_ tab, connect Amplitude to your data warehouse. Have the following information ready: - **Server hostname**: The hostname of your Databricks cluster. You can find it in your cluster configuration by navigating to _Advanced Options > JDBC/ODBC > Server Hostname_. - **HTTP path**: The HTTP path of the cluster you want to connect to. You can find it in your cluster configuration by navigating to _Advanced Options > JDBC/ODBC > HTTP Path_. - **Personal access token**: Use the personal access token to authenticate with your Databricks cluster. [Learn how to create them here](https://docs.databricks.com/en/dev-tools/auth/index.html#common-tasks-for-databricks-authentication). Click **Next** when you're done. 3. You can find a list of your tables under _Select Table_. To begin column mapping, click the table you want. 4. In the list of required fields under _Column Mapping_, enter the column names in the appropriate fields to match columns to required fields. To add more fields, click **+ Add field**. 5. In the _Data Selection_ tab, select the `profiles` data type. 6. When you're done, click **Test Mapping** to verify your mapping information. Then click **Next**. 7. Name the source and set the frequency at which Amplitude refreshes your profiles from the data warehouse. The default frequency is 12 hours, but you can change it. ## Set up a profile (S3 users) To set up a profile in Amplitude: 1. In Amplitude, navigate to _Data > Sources_ and click **+ Add Source**. Find and click Amazon S3. 2. Connect Amplitude to your S3 bucket. For more information about granting Amplitude access to your S3 bucket, refer to [Amazon S3](https://amplitude.com/docs/data/source-catalog/amazon-s3#give-amplitude-access-to-your-s3-bucket). Additionally, have the following information ready for the _Verify Instrumentation_ tab: - Bucket Name and Prefix where your profiles are stored. - AWS Role ARN, AWS External ID, and AWS Region. Click **Test Credentials** to confirm Amplitude can access your S3 bucket, then click **Next** and name your source. 3. In the _Select File_ tab, select the file type and click **See Preview** to confirm the files to import, then click **Next**. 4. On the _Configure Converter_ tab, select the _Profiles_ data type. Complete source fields for `user_id` and `mutation_type`, and add additional properties if needed. The _Data Preview_ section shows an example of what Amplitude is set to ingest. - `mutation_type` must be exactly one of the following strings, or Amplitude won't ingest the profile: - `INSERT` when creating new files. - `UPDATE` when syncing new values. - `DELETE` to remove profiles. 5. When you're done, click **Save and Enable** to enable the import and refresh of profiles. ## Data specifications | Field | Description | Example | | --- | --- | --- | | `user_id` | Identifier for the user. Must have a minimum length of 5. | | | `Profile Property 1` | Profile property set at the user level. The value of this field is the value from the customer's source since last sync. | | | `Profile Property 2` | Profile property set at the user level. The value of this field is the value from the customer's source since last sync. | | Example: ```json { "user_id": 12345, "number of purchases": 10, "title": "Data Engineer" } ``` Refer to [this article for information on Snowflake profiles](https://amplitude.com/docs/data/source-catalog/snowflake#select-the-data-type). ## SQL template ```sql SELECT AS "user_id", AS "profile_property_1", AS "profile_property_2" FROM DATABASE_NAME.SCHEMA_NAME.TABLE_OR_VIEW_NAME ``` ## Clear a profile value When you remove profile values in your data warehouse, those values sync to Amplitude during the next sync operation. You can also use Amplitude Data to remove unused property fields from users in Amplitude. ## Sample queries ```sql SELECT user_id as "user_id", upgrade_propensity_score as "Upgrade Propensity Score", user_model_version as "User Model Version" FROM ml_models.prod_propensity_scoring ``` ```sql SELECT m.uid as "user_id", m.title as "Title", m.seniority as "Seniority", m.dma as "DMA" FROM prod_users.demo_data m ``` ================================================================================ # Converter configuration reference URL: https://amplitude.com/docs/data/converter-configuration-reference ================================================================================ # Converter configuration reference This reference covers examples and operators for the Amazon S3 Import and Google Cloud Storage (GCS) converter configuration. Read the [S3 guide](https://amplitude.com/docs/data/source-catalog/amazon-s3) or the [GCS guide](https://amplitude.com/docs/data/source-catalog/google-cloud-storage) for more information. ## skip\_user\_properties\_sync Because many cloud storage source imports are batch uploads of historical data, syncing the latest user properties for historical events might not make sense. For this reason, Amplitude sets `$skip_user_properties_sync` to `true` by default. To include user properties with your events, set it to `false` in the converter. For more information about `$skip_user_properties_sync`, refer to the [Data Backfill Guide](https://amplitude.com/docs/data/data-backfill). ## ignoreEventFlag Use `ignoreEventFlag` to selectively skip events from ingestion based on a computed boolean condition. Set `ignoreEventFlag` to a field name (for example, `"$ignore"`), then define that field in `convertToAmplitudeFunc` using any DataLang boolean expression. When the field evaluates to `true` for a given event, Amplitude skips the event without counting it as an error. When it evaluates to `false` or is absent, Amplitude ingests the event normally. This option is useful when your source data contains events you want to filter, such as internal test events, bot traffic, or specific event types, without preprocessing the files upstream. ### Example: filter out specific event types The following example skips any event where `event_type` is `page_view` or `session_start`: ```json { "converterConfig": { "ignoreEventFlag": "$ignore", "convertToAmplitudeFunc": { "event_type": "event_type", "user_id": "user_id", "$ignore": ["or", ["equals", ["path", "event_type"], ["value", "page_view"]], ["equals", ["path", "event_type"], ["value", "session_start"]] ] } } } ``` In this example: - `"ignoreEventFlag": "$ignore"` tells Amplitude to look for a field named `$ignore` in the converted event. - `"$ignore"` in `convertToAmplitudeFunc` defines a boolean expression using the [`or`](#boolean-operators) and [`equals`](#boolean-operators) operators. - If `event_type` is `page_view` or `session_start`, `$ignore` evaluates to `true` and Amplitude skips the event. - Amplitude ingests all other events normally. You can use any [boolean operator](#boolean-operators) or combination of operators to build the condition. ## convertToAmplitudeFunc Conversion rules in `convertToAmplitudeFunc` instruct the ingestion service on how to construct events in Amplitude. ### Example converter with `convertToAmplitudeFunc` ```json { "config_name": ["Event sample converter"], "converterConfig": { "fileType": "parquet", "compressionType": "none", "convertToAmplitudeFunc": { "event_type": "action", "user_id": "user", "device_id": "device", "event_properties": { "business_id_encid": "business_id" }, "user_properties": { "utm_channel_category": "utm_channel_c", "utm_channel_source": "utm_channel_s" }, "time": "epoch", "session_id": "session_id", "app_version": "app_version" } }, "keyValidatorConfig": { "filterPattern": "folder1/folder2/ds=202011[1-2][0-9]/.*\\.parquet" } } ``` ### Example constructed event ```json { "event_type": "watch tv", "user_id": "john", "device_id": "host1", "event_properties": { "business_id_encid": "123" }, "user_properties": { "utm_channel_category": "discovery", "utm_channel_source": "network" }, "time": "1645066434189", "session_id": "1", "app_version": "1" } ``` Values in the event come from the fields specified by `convertToAmplitudeFunc`. For example, the value `watch tv` in field `event_type` comes from field "action" in ingested data files. Because the `event_type` value isn't `["value":"$identify"]` or `["value":"$groupidentify"]`, Amplitude ingests events the same way it ingests events with the HTTP V2 API. ## Operators ### List operators #### Use list operators If the source description is a list, the first item in the list must be a string specifying the function. The rest of the list are the parameters to the function. The "|" character separates non-repeating and repeating arguments. Any arguments after "|" are repeatable, and you can specify them any number of times. The entire list of arguments must be present in any multiple-argument operator (you can't specify just one of three arguments, you must include all three). | Operator | Description | Syntax | | --- | --- | --- | | `path` | Evaluates each SourceDescription sequentially on the returned JsonElement. Equivalent to evaluating a specific path when chaining BasicPaths. This also works with indexing into an array, for example `["path", "foo", "1"]` chooses the element at index 1 (second element) in the array at "foo".**Provide the index as a string.** | `["path",| SOURCE_DESCRIPTION...]` **Example**: `["path", "foo", "bar"] => obj['foo']['bar'].` | | `any` | Returns the first value returned by SOURCE\_DESCRIPTION in the list. | `["any", SOURCE_DESCRIPTION, | SOURCE_DESCRIPTION...] ` | | `value` | Escapes a single JSON value so you can create a static value. | **Example**: `["value", "amplitude-vacuum"...` | | `dict` | Creates a dictionary (object) where the raw\_strings are keys and values are the evaluated SOURCE\_DESCRIPTIONS. | `["dict", "raw_string", SOURCE_DESCRIPTION, |"raw_string", SOURCE_DESCRIPTION...]` | | `array` | Returns an array, where elements are the values returned by evaluating SOURCE\_DESCRIPTIONS. If a SOURCE\_DESCRIPTION fails to evaluate, Amplitude skips it. | `["array", SOURCE_DESCRIPTION, \SOURCE_DESCRIPTION...] ` | | `condition` | Determines the first true BooleanCondition and returns the result of the following SOURCE\_DESCRIPTION. Throws a NoValueFoundAtSource exception if nothing evaluates to true. | `["condition"| "cond", BOOLEAN_SOURCE, SOURCE_DESCRIPTION, | BOOLEAN_SOURCE, SOURCE_DESCRIPTION...]` | | `ifelse` | If the BOOLEAN\_SOURCE evaluates to true, returns the first SOURCE\_DESCRIPTION. Otherwise returns the second SOURCE\_DESCRIPTION. | `["ifelse", BOOLEAN_SOURCE, SOURCE_DESCRIPTION, SOURCE_DESCRIPTION]` | | `sample_md5` | Evaluates the given sampleKey (second arg) with the samplePercent (first arg) to determine whether it should be in the sample. Returns boolean | `["sample_md5", SOURCE_DESCRIPTION, SOURCE_DESCRIPTION] ` | | `iso_time_to_ms` | Assumes the string returned by SOURCE\_DESCRIPTION is an ISO datetime string, for example, `YYYY-MM-DDTHH:MM:SS`, and converts to milliseconds since epoch | `["iso_time_to_ms", SOURCE_DESCRIPTION] ` | | `ms_to_iso_time` | Assumes the string returned by SOURCE\_DESCRIPTION is milliseconds since epoch and converts to ISO datetime string, for example, `YYYY-MM-DDTHH:MM:SS ` | `["ms_to_iso_time", SOURCE_DESCRIPTION]` | | `iso_time_now` | Generates an ISO datetime string for right now | `["iso_time_now"]` | | `ms_time_now` | Generates the milliseconds since epoch for right now | `["ms_time_now"]` | | `int96_time_to_ms` | Assumes the string returned by SOURCE\_DESCRIPTION is a base64-encoded INT96, for example, `AP6qCz41AAAwhCUA`, and converts to milliseconds since epoch | `["int96_time_to_ms", SOURCE_DESCRIPTION]` | | `parse_time_to_ms` | Takes in a RAW\_STRING time format, for example, `M/d/yyyy H:mm:ss`, and a `SOURCE_DESCRIPTION` that returns a string in that format, for example, '1/1/2021 5:06:07', and converts to milliseconds since epoch | `["parse_time_to_ms", RAW_STRING, SOURCE_DESCRIPTION]` | | `parse_json_element` | Assumes the value returned by SOURCE\_DESCRIPTION is a string json blob and returns the parsed json value | `["parse_json_element"| "parse_json_object", SOURCE_DESCRIPTION] ` | | `merge_dicts` | Merges the json objects that each SOURCE\_DESCRIPTION evaluates to | `["merge_dicts", SOURCE_DESCRIPTION, | SOURCE_DESCRIPTION...] ` | | `flatten_dict` | Flattens a nested json object into a single layer json object | `["flatten_dict", "raw_string", INTEGER_SOURCE, SOURCE_DESCRIPTION]` | | `exclude_keys` | Evaluates the specified SourceDescription the returned JsonElement without the requested fields | `["exclude_keys", SOURCE_DESCRIPTION, | "raw_string"...] ` | | `concat` | Treats the results of each SOURCE\_DESCRIPTION as a string and returns the concatenated string | `["concat", SOURCE_DESCRIPTION, | SOURCE_DESCRIPTION...] ` | | `replace_with` | Replace all old\_string within the value returned by SOURCE\_DESCRIPTION with new\_string. Returns a string or raises a NoValueException if SOURCE\_DESCRIPTION can't be evaluated to a string. The old\_string supports Java's regex syntax for matching patterns, more details at https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html | `["replace_with", "old_string", "new_string", SOURCE_DESCRIPTION]` | | `split` | Splits the value returned by SOURCE\_DESCRIPTION by the specified character sequence. Returns a jsonArray or raises a NoValueException if SOURCE\_DESCRIPTION can't be evaluated to a string | `["split", "raw_string", SOURCE_DESCRIPTION] ` | | `lowercase` | Returns the lowercase string | `["lowercase"| "lower", SOURCE_DESCRIPTION] ` | | `typeof` | Returns type of the source description as a string: 'string', 'list', 'dict', 'bool', 'number', 'null' | `["typeof", SOURCE_DESCRIPTION] ` | ### Boolean operators These operators return a JsonPrimitive of type Boolean, so they're valid to use with `cond` and `ifelse`. | Operator | Description | Source | | --- | --- | --- | | `bool` | Evaluates as a static boolean value. Throws an exception during initialization if RAW\_JSON isn't a boolean value. | `["bool", any_json] ` | | `not` | Return whether both arguments are true. Amplitude treats null values as false and casts the string 'true' or 'false' to a boolean. | `["not"|"!", SOURCE_DESCRIPTION] ` | | `and` | Return whether all arguments are true. Amplitude treats null values as false and casts the string 'true' or 'false' to a boolean. | `["and"|"&&", SOURCE_DESCRIPTION, | SOURCE_DESCRIPTION...]` | | `or` | Return whether at least one argument is true. Amplitude treats null values as false and casts the string 'true' or 'false' to a boolean. | `["or"|"||", SOURCE_DESCRIPTION, | SOURCE_DESCRIPTION...]` | | `equals` | Evaluates to `true` if and only if the two args are equal. | `["equals"|"eq"|"=", SOURCE_DESCRIPTION, SOURCE_DESCRIPTION]` | | `contains` | True if the evaluated SourceDescription (second arg) contains the given raw string. If the SourceDescription is null, evaluates to false. | `["contains"|"is_substring", "raw_string", SOURCE_DESCRIPTION]` | ### Integer and float operators The following Operators return a JsonPrimitive of type Integer, barring the `add` Operator which returns JsonPrimitive of type Float. | Operator | Description | Syntax | | --- | --- | --- | | `int` | Evaluates as a static int value. Throws an exception during initialization if RAW\_JSON isn't an int value. | `["int", RAW_JSON]` | | `round` | Round the argument to the nearest integer. Amplitude attempts to convert strings to integers and treats null values as zero. | `["round", SOURCE_DESCRIPTION] ` | | `add` | Return the sum of the arguments as an integer. Amplitude attempts to convert strings to integers and treats null values as zero. | `["add"|"+", SOURCE_DESCRIPTION, | SOURCE_DESCRIPTION...]` | | `subtract` | Subtracts the second argument from the first one. Amplitude attempts to convert strings to integers and treats null values as zero. | `["subtract"|"-", SOURCE_DESCRIPTION, SOURCE_DESCRIPTION]` | | `multiply` | Return the product of the arguments as an integer. Amplitude attempts to convert strings to integers and treats null values as zero. | `["multiply"|"*", SOURCE_DESCRIPTION, | SOURCE_DESCRIPTION...]` | | `divide` | Divides the first argument by the second one. Amplitude attempts to convert strings to integers and treats null values as zero. | `["divide"|"/", SOURCE_DESCRIPTION, SOURCE_DESCRIPTION]` | ### JSON operator | Operator | Description | Syntax | | --- | --- | --- | | N/A | As syntactic sugar, Amplitude converts an object to a "dict" LIST\_OPERATOR | \*The following two descriptions are equivalent: `{"key1": SOURCE_DESCRIPTION,"key2", SOURCE_DESCRIPTION,…}` `["dict","key1", SOURCE_DESCRIPTION,"key2", SOURCE_DESCRIPTION,...]` | ### User property operations The converter supports the same user property operators as the Identify API. Refer to [the Identify documentation](https://amplitude.com/docs/apis/analytics/identify#userproperties-supported-operations) for details. ================================================================================ # Destination catalog URL: https://amplitude.com/docs/data/destination-catalog Updated: 2024-08-14 ================================================================================ # Destination catalog ================================================================================ # IP address, location, user agent, and device properties URL: https://amplitude.com/docs/data/understand-ip-address-and-location ================================================================================ # IP address, location, user agent, and device properties Amplitude derives a user's location, device, and platform properties from data that arrives with each event, rather than requiring you to set those properties yourself. It looks up city, region, and country from the event's IP address with the MaxMind GeoIP database, and parses the user agent string that client-side SDKs send to determine device context, operating system, and web browser information. You can override the location values server-side through the HTTP API, or stop Amplitude from using the IP address by disabling IP tracking in the SDK or dropping IP addresses after ingestion. ## How Amplitude tracks location properties Amplitude uses the [MaxMind](https://www.maxmind.com/en/home) database to look up location information from the user's IP address. Even though MaxMind data is reliable, the [accuracy and availability of city and region information can vary by country](https://www.maxmind.com/en/geoip2-city-accuracy-comparison?country=&resolution=50). By default, Amplitude uses GeoIP to gather location property values based on `location_lat` and `location_long`. You can explicitly define how Amplitude tracks a user's location properties server-side. Amplitude's [HTTP API](https://amplitude.com/docs/apis/analytics/http-v2) lets you send your own `[Amplitude] City`, `[Amplitude] DMA`, `[Amplitude] Region`, and `[Amplitude] Country` values with your events. > **Note:** > > If you send these values, Amplitude doesn't modify them to reflect GeoIP. Always update all four fields together, because setting any one of the fields resets the others. ## How Amplitude determines location properties when IP address is unavailable Amplitude supports both disabling IP address tracking in the SDK configuration and dropping IP addresses after ingestion. The method you choose affects how Amplitude can determine location properties. ### Disable IP address tracking in the SDK When you disable IP address tracking in the SDK configuration (for example, [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#optional-tracking), [Android-Kotlin SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk#disable-tracking), [iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#disable-tracking)), Amplitude never receives the IP address. Amplitude's back-end services can't reconcile the user's location, and any location properties remain empty. ### IP address filtering If you request [Amplitude Support](https://gethelp.amplitude.com) to drop IP addresses after ingestion, Amplitude's back-end services process the IP address to determine location, but the IP address itself doesn't persist in Amplitude. Amplitude fills the event's location properties but leaves the IP address empty. ## How Amplitude parses user agent and device information Amplitude processes device context from client-side SDK fields and, for web events, the user agent string. Amplitude stores the processed values on your events and exposes selected values as built-in properties for analysis. ### User agent parsing Client-side SDKs can send device context that describes: 1. **Device model**: the specific device model (for example, `iPhone 13`, `Samsung Galaxy S21`). 2. **Operating system**: the OS and its version (for example, `iOS 15.4`, `Android 12`). 3. **Browser**: for web traffic, the browser and its version (for example, `Chrome 98.0.4758.102`). 4. **Platform**: the general platform category (for example, `iOS`, `Android`, `Web`). 5. **Manufacturer**: the device manufacturer (for example, `Apple`, `Samsung`). ### Device properties Field names differ between event ingestion, exported events, and the Amplitude UI. This table uses the following terms: - **HTTP V2 API field**: The top-level field that the [HTTP V2 API](https://amplitude.com/docs/apis/analytics/http-v2) accepts when you send an event. - **Export API field**: The field that the [Export API](https://amplitude.com/docs/apis/analytics/export) returns after Amplitude processes the event. - **UI label**: The name that chart and filter property selectors display. For example, the Export API returns `os_name` and `os_version` as separate fields. The UI combines them and displays the result as **OS**. > **Note:** > > This table covers HTTP V2, the Export API, and the corresponding built-in UI properties. SDK payloads, one-off backfills, and destination-specific warehouse schemas can differ. | HTTP V2 API field | Export API field | UI label | Relationship | | --- | --- | --- | --- | | `user_agent` | `os_name` | OS | For web events, Amplitude uses the parsed browser name when you don't send `os_name`. | | `user_agent` | `os_version` | OS | For web events, Amplitude uses the parsed browser major version when you don't send `os_version`. | | `user_agent` | `device_family` | Device Family | Amplitude can use parsed device context when explicit device fields are absent. | | `user_agent` | `device_type` | Device Type | Amplitude can use parsed device context as a fallback. The device type can remain empty when no mapping exists. | | `os_name` | `os_name` | OS | The explicit input takes precedence over the value parsed from `user_agent`. | | `os_version` | `os_version` | OS | The explicit input takes precedence over the value parsed from `user_agent`. | | `device_brand` | `device_family` | Device Family | Amplitude combines this field with the other supplied device components to derive the family. | | `device_manufacturer` | `device_family` | Device Family | Amplitude combines this field with the other supplied device components to derive the family. | | `device_model` | `device_family` | Device Family | Amplitude combines this field with the other supplied device components to derive the family. | | `device_brand` | `device_type` | Device Type | Amplitude combines this field with the other supplied device components and looks up the result in the device mapping. | | `device_manufacturer` | `device_type` | Device Type | Amplitude combines this field with the other supplied device components and looks up the result in the device mapping. | | `device_model` | `device_type` | Device Type | Amplitude combines this field with the other supplied device components and looks up the result in the device mapping. | | `platform` | `platform` | Platform | Amplitude retains the field name. | Amplitude doesn't expose separate built-in `browser` or `browser_version` fields. Browser SDKs send `user_agent`. For web traffic, Amplitude stores the parsed browser name and major version in `os_name` and `os_version`. The UI combines those fields in the **OS** property. Amplitude combines `device_brand`, `device_manufacturer`, and `device_model` to determine standardized `device_family` and `device_type` values. A recognized combination maps to Amplitude's standardized device family and type. An unrecognized family can use a combined description of the supplied device components, while `device_type` can remain empty when no type mapping exists. The UI uses **Device Family** for broad groups such as Apple iPhone or Samsung Galaxy Phone. It uses **Device Type** for specific types such as Apple iPhone 6 or Samsung Galaxy S5. For the complete list of built-in properties, go to [Default user properties](https://amplitude.com/docs/get-started/user-property-definitions). ### How user agent parsing works 1. **Client-side collection**: The Browser SDK sends the user agent string with the event. Other SDKs can send device context through their supported fields. 2. **Server-side parsing**: For web events, Amplitude parses `user_agent` for browser and device context. Explicit `os_name`, `os_version`, and device fields take precedence over values that Amplitude derives from the user agent. 3. **Property assignment**: Amplitude stores processed values in the event fields listed in the Export API column. 4. **Analysis availability**: Amplitude exposes the properties listed in the UI label column for segmentation, filtering, and analysis. ### Controlling device property tracking To disable automatic tracking of certain device properties, use the `trackingOptions` configuration in the SDK. For example, in the Browser SDK: ```javascript amplitude.init(AMPLITUDE_API_KEY, { trackingOptions: { platform: false, language: false, }, }); ``` ### Mobile-specific device information For mobile SDKs (iOS, Android), Amplitude collects additional device information: 1. **iOS**: device model, OS version, and carrier information when available. 2. **Android**: device model, manufacturer, OS version, carrier, and screen dimensions. This information can help you understand how your app performs across different device types and OS versions. ### Custom device properties If you need to track additional device information that Amplitude doesn't automatically capture, you can add custom properties to your events: ```javascript // Example of adding custom device properties amplitude.track("Button Clicked", { screen_resolution: "1920x1080", connection_type: "wifi", battery_level: 85, }); ``` ================================================================================ # How Amplitude calculates session length URL: https://amplitude.com/docs/data/sources/session-length ================================================================================ # How Amplitude calculates session length When you use session ID as the session property, Amplitude calculates session length with this formula: ```plaintext *max(client\_event\_time) - min(client\_event\_time)* ``` In this formula: - `client_event_time` is the local timestamp (UTC) when the device logged the event. - `min(client_event_time)` is the local timestamp (UTC) of the first event logged by the device. - `max(client_event_time)` is the local timestamp (UTC) of the last event logged by the device. Amplitude excludes hidden, inactive, and deleted events from the session length calculation. Example event sequence: Event A --> Event B --> Event C --> Event D If Event C and Event D are [hidden, inactive, or deleted](https://help.amplitude.com/hc/en-us/sections/16805649563163-Clean-up-your-data), Amplitude uses `max(client_event_time)` from Event B instead of Event D. For more information about how Amplitude tracks sessions, refer to [Track sessions](https://amplitude.com/docs/data/sources/instrument-track-sessions). ================================================================================ # Client-side vs Server-side URL: https://amplitude.com/docs/data/client-side-vs-server-side ================================================================================ # Client-side vs Server-side Client-side and server-side describe where the code that sends data to Amplitude runs: on the user's device for client-side sources, or on your own servers for server-side sources. Choose client-side sources for the simplest initial instrumentation, server-side sources to track events from your own servers, or a hybrid of both to combine those benefits. Amplitude also supports third-party sources that import data from platforms you already use, such as ad networks or marketing automation tools. Both Amplitude client-side SDKs and server-side SDKs use API endpoints. These endpoints offer flexibility for implementing custom solutions without relying on Amplitude's SDKs, especially for programming languages Amplitude's SDKs don't support, like PHP. | Name | API endpoints | | --- | --- | | [Analytics and Data SDKs](https://amplitude.com/docs/sdks/analytics) | [HTTP V2 API](https://amplitude.com/docs/apis/analytics/http-v2) and [Batch event upload](https://amplitude.com/docs/apis/analytics/batch-event-upload) | | [Experiment SDKs](https://amplitude.com/docs/sdks/experiment-sdks) | [Evaluation API](https://amplitude.com/docs/apis/experiment/experiment-evaluation-api) | ## Client-side sources Use client-side sources in apps that your users run on their own devices, like mobile, web browser, and desktop apps. In these types of sources, code runs on the user's device. Amplitude's client-side sources include these SDKs: - Web: Browser, Marketing Analytics Browser, React Native. - Mobile: Android, iOS, Unity Plugin, Flutter, React Native. - Game engine: Unity Plugin, Unreal. ## Server-side sources Use server-side sources in secure, multi-user environments like web servers and services that you run on your own servers. In these types of sources, code runs on the server. Amplitude's server-side sources include these SDKs and APIs: - Node.js SDK. - Go SDK. - Python SDK. - Java SDK. ## Third-party sources Third-party is another kind of source. These sources let you import data from other platforms into Amplitude. Third-party sources all require that you have an account with the third-party source, and each has different setup requirements. You can find all third-party sources in the [Source catalog](https://amplitude.com/docs/data/source-catalog). ## How to choose Choosing the kinds of sources you need to use can be daunting, so here's a basic guide to help you make a decision. - **Client-side**: Choose client-side sources for the simplest initial instrumentation. - **Server-side**: Choose server-side sources if you want to track server-side events and use existing user data tracking workflows. - **Hybrid**: Choose a hybrid approach that includes both client-side and server-side sources to get the benefits of simpler implementation and the ability to track server-side events. - **Third party**: Choose third-party sources if you already have a third-party data layer such as ad networks or marketing automation tools.