> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events (Audience)

> Capture and manage user behavior data across all touchpoints

export const NoBadge = () => {
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.5rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: '#F7D0E2',
    color: '#1A1A1A',
    fontWeight: '500'
  }}>
      No
    </span>;
};

export const YesBadge = () => {
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.5rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: '#C7E8F9',
    color: '#1A1A1A',
    fontWeight: '500'
  }}>
      Yes
    </span>;
};

<CardGroup cols={2}>
  <Card title="Issues" href="#troubleshooting" icon="triangle-exclamation" />

  <Card title="FAQ" href="#faq" icon="circle-question" />
</CardGroup>

## Overview

**Events** are the foundation of audience creation in Permutive. An event captures a user action or behavior on your website or app—such as viewing content, engaging with media, watching a video, or completing an action. Events are enriched with **properties** that provide contextual information about the action, enabling you to build precise, behavior-based cohorts for targeting and activation.

Permutive automatically collects standard events appropriate to each platform (such as content view and engagement events), and you can extend this with custom events specific to your business needs. All events are tracked in real-time and stored for historical analysis and cohort building.

## Why Use Events?

**Build cohorts based on real user behavior** — Events enable you to create audience segments based on what users actually do on your properties, not just demographic assumptions. By tracking content views, engagement, video plays, and custom interactions, you gain a complete picture of user behavior that powers precise targeting for advertisers.

**Enrich events with custom properties for granular targeting** — Beyond standard event data, you can include custom properties that capture business-specific context—like article categories, product brands, video titles, or content authors. These properties allow you to build highly specific cohorts that meet advertiser briefs and campaign requirements.

**Real-time data collection for immediate activation** — Events are collected and processed in real-time by the Permutive SDK, enabling immediate cohort evaluation and activation. Users are added to cohorts as soon as they meet the criteria, ensuring your targeting is always current and responsive to user behavior.

## Concepts

### Definitions

* **Event**: A captured action or behavior that a user takes on your site or app. Events have a name (e.g., "Pageview", "VideoPlay", "ContentView") and are associated with a specific user, session, and timestamp.

* **Event Properties**: Additional information associated with an event that provides context about the action. Properties can be standard (collected automatically by Permutive) or custom (defined by you). Examples include `client.url`, `article.title`, `product.brand`, or `video.duration`.

* **Event Schema**: The defined structure for an event, specifying which properties are allowed and their data types (e.g., String, Integer, List). The schema ensures data consistency and enables validation.

* **Standard Events**: Events automatically collected by the Permutive SDK. Standard events vary by platform—for example, web includes page views and engagement, CTV/audio includes video views or audio play events. All platforms collect cohort entry and exit events.

* **Custom Events**: Events you define to track specific behaviors unique to your business, such as video plays, social shares, article comments, or e-commerce transactions. Custom events are tracked using platform-specific SDK methods or direct API calls.

* **Automatic Collection**: The Permutive SDK automatically collects standard content view events and their associated properties appropriate to each platform (e.g., Pageview on web, Video View on CTV).

## Workflows

### Collecting Standard Events

The Permutive SDK automatically collects standard events as users interact with your properties. No additional configuration is required beyond deploying the SDK. Standard events vary by platform and include content views, engagement metrics, and ad events from your configured ad server.

### Defining Custom Events

To track behaviors beyond standard events, you can define custom events with their own schemas. Custom events and schemas are configured by your Permutive team based on your specific business requirements. Work with your Customer Success Manager to identify the events you need to track, and once agreed, Permutive will configure the event schemas in your workspace. You then implement tracking using the appropriate SDK method or API for your platform.

### Viewing Event Data

The Events page in the Permutive Dashboard displays all events being collected for your workspace, including standard and custom events. You can inspect event schemas, view property definitions, and see sample data to verify tracking is working correctly.

## Troubleshooting

Common issues when working with Events:

<AccordionGroup>
  <Accordion title="Events are not appearing in the dashboard">
    If events are not appearing in the Permutive Dashboard, this may be due to:

    * The Permutive SDK is not properly deployed or initialized
    * The SDK is blocked by ad blockers or privacy tools (primarily on web)
    * Events are being rejected due to schema validation errors
    * There is a delay in data processing (typically events appear within a few minutes)

    **Solution**: Verify the SDK is deployed and initialized correctly using platform-specific debugging tools (browser developer console for web, platform logs for mobile/CTV). Check for API calls to Permutive and review any error messages. For web, temporarily disable ad blockers to test. If events are still missing after 10-15 minutes, contact [Support](mailto:support@permutive.com).
  </Accordion>

  <Accordion title="Schema validation errors are rejecting events">
    Events can be rejected if the data sent does not match the event schema. Common causes include:

    * Sending a property that is not defined in the schema
    * Sending a property with the wrong data type (e.g., String instead of Integer)
    * Sending a required property with a null or undefined value
    * Property name typos or case sensitivity issues

    **Solution**: Inspect the event schema in the Permutive Dashboard to verify property names and types. Check your tracking code to ensure properties match the schema exactly. Use your browser's console to inspect the data being sent before it reaches the Permutive API. Add missing properties to the schema if needed, or update your tracking code to match the schema.
  </Accordion>

  <Accordion title="Custom event properties are showing null values">
    If custom event properties are showing null or undefined values, check:

    * The data layer or variables are populated before the event fires
    * The property names in your tracking code match the schema exactly
    * There are no errors preventing the property values from being set
    * The timing of the event firing—data may not be available yet

    **Solution**: Use platform-specific debugging tools to verify that the data you're trying to capture is available when the event fires. Add logging to your tracking code to debug property values. Ensure asynchronous data is loaded before firing events. Consider delaying event tracking until required data is available.
  </Accordion>

  <Accordion title="Content view events are firing multiple times">
    Multiple content view events can occur when:

    * The SDK is initialized multiple times
    * Single-page applications are firing view events on client-side route changes (web)
    * The platform is using a tag manager that fires the SDK more than once (web)

    **Solution**: Verify the SDK is only initialized once. For single-page applications, ensure view tracking is intentionally configured for route changes (this is often desired behavior). For web, review tag manager configuration to prevent duplicate SDK loads.
  </Accordion>

  <Accordion title="Event data is missing specific properties">
    If expected properties are not appearing in your event data:

    * The properties may not be defined in the event schema
    * The properties may be optional and not being sent in some cases
    * Data layer values may not be available when the event fires
    * Property names may have been misspelled in the tracking code

    **Solution**: Verify the property exists in the event schema and note whether it is required or optional. Check that the data source (data layer, page variables) is populated correctly. Review tracking code for spelling and case sensitivity. Add missing required properties or update the schema to include new optional properties.
  </Accordion>
</AccordionGroup>

## Environment Compatibility

#### Core Product

Events are collected across all Permutive SDK platforms:

| Functionality              | Web          | iOS          | Android      | CTV          | API Direct   |
| :------------------------- | :----------- | :----------- | :----------- | :----------- | :----------- |
| Standard event collection  | <YesBadge /> | <YesBadge /> | <YesBadge /> | <YesBadge /> | <YesBadge /> |
| Custom event collection    | <YesBadge /> | <YesBadge /> | <YesBadge /> | <YesBadge /> | <YesBadge /> |
| Real-time event processing | <YesBadge /> | <YesBadge /> | <YesBadge /> | <YesBadge /> | <YesBadge /> |

#### Typical Data by Platform

Events will be defined with your team during onboarding, based on your environments and ad-tech stack. Typical data points collected in each environment include:

**Web:**

* Page View, Engagement (engaged time, scroll depth), Link Click, Ad Impression, Ad Click, Cohort Entry, Cohort Exit

**iOS / Android:**

* Content View, Engagement (engaged time, scroll depth), Ad Impression, Ad Click, Cohort Entry, Cohort Exit

**CTV:**

* Video View, Engagement (engaged time), Video Completion, Ad Play, Ad Completion, Cohort Entry, Cohort Exit

**Audio:**

* Audio Play, Engagement (engaged time), Audio Completion, Ad Play, Ad Completion, Cohort Entry, Cohort Exit

## Dependencies

Events rely on the following products and configurations:

| Dependency    | Required    | Description                                                                                                                                              |
| :------------ | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Permutive SDK | Recommended | The Permutive SDK is typically used and makes it easy to automate collection of standard events. Events can also be tracked by calling our API directly. |
| Event Schemas | Yes         | Event schemas must be defined in the Permutive Dashboard before events can be collected and validated.                                                   |

## Limits

Events adhere to the following specifications and limits.

#### Feature Limits

| Feature                     | Description                                                                | Limit             |
| :-------------------------- | :------------------------------------------------------------------------- | :---------------- |
| Custom events per workspace | Maximum number of custom event types that can be defined.                  | Based on contract |
| Properties per event        | Maximum number of properties that can be defined on a single event schema. | No hard limit     |

#### Usage Limits

| SKU          | Description                                               | Limit             |
| :----------- | :-------------------------------------------------------- | :---------------- |
| Event volume | Maximum number of events that can be collected per month. | Based on contract |

## FAQ

<AccordionGroup>
  <Accordion title="What events does Permutive collect automatically?">
    The Permutive SDK automatically collects several standard events without any additional configuration. Standard events vary by platform:

    **Web:**

    * **Pageview**: Fired on every page load
    * **Pageview Engagement**: Tracks time on page, scroll depth, and completion
    * **Cohort Entry/Exit**: Tracks when users join or leave cohorts

    **Mobile (iOS/Android):**

    * **Content View**: Fired on content navigation
    * **Engagement**: Tracks time on screen and scroll depth
    * **Cohort Entry/Exit**: Tracks when users join or leave cohorts

    **CTV/Audio:**

    * **Video View / Audio Play**: Fired on content playback
    * **Engagement**: Tracks playback duration
    * **Cohort Entry/Exit**: Tracks when users join or leave cohorts

    If you have ad server integration enabled, additional ad events are collected (e.g., Slot Rendered, Slot Clicked, Slot Viewable).

    All other events (video plays, form submissions, link clicks, etc.) must be configured or implemented as custom events.
  </Accordion>

  <Accordion title="How do I track a custom event?">
    To track a custom event:

    1. Define the event schema in the Permutive Dashboard under Events > Create Event
    2. Specify the event name and properties with their data types
    3. Implement tracking using the appropriate method for your platform (e.g., `permutive.track('EventName', { property: 'value' })` on web, or platform-specific SDK methods for mobile/CTV)

    Define the event schema in the Permutive Dashboard under Events > Create Event and implement tracking using the appropriate method for your platform.
  </Accordion>

  <Accordion title="Can I modify an event schema after it's been created?">
    Yes, you can add new optional properties to an event schema at any time. However, changing property data types or removing properties can cause validation errors for events that are already being tracked. It's recommended to add new properties rather than modifying existing ones. Contact [Support](mailto:support@permutive.com) for assistance with schema migrations.
  </Accordion>

  <Accordion title="What is the difference between required and optional properties?">
    * **Required properties** must be included every time the event is tracked. If a required property is missing, the entire event will be rejected.
    * **Optional properties** can be omitted. Events will still be accepted even if optional properties are not provided.

    It's best practice to make properties optional unless they are truly essential to the event's meaning.
  </Accordion>

  <Accordion title="How long is event data stored?">
    Event data retention policies vary by customer agreement. Typically:

    * Recent event data (last 30-90 days) is stored in hot storage for fast querying
    * Historical event data is retained for longer periods based on your data retention policy

    Contact your Customer Success Manager to discuss your specific data retention requirements.
  </Accordion>

  <Accordion title="Can I send events from server-side instead of client-side?">
    Yes, you can send events to Permutive via server-side integration using:

    * **Pixel API**: For simple server-side event tracking
    * **API Direct**: For batch event ingestion without SDK deployment
    * **Connectivity Imports**: For importing historical event data

    See our [API documentation](/api/introduction) for details on server-side event tracking.
  </Accordion>

  <Accordion title="How do I see which events are being collected?">
    To inspect events being collected, use platform-specific debugging tools:

    **Web:**

    1. Open your browser's Developer Tools (F12)
    2. Go to the Network tab
    3. Filter for requests to Permutive's API (look for `permutive.com`)
    4. Reload the page and inspect the API calls to see event payloads

    **Mobile/CTV:**

    * Use platform logs and network debugging tools to inspect API calls to Permutive
    * Check the Permutive Dashboard's Event Inspector for all platforms

    You can also use the Permutive browser extension (if available for web) or check the Permutive Dashboard's Event Inspector.
  </Accordion>

  <Accordion title="Why are my events being rejected?">
    Events are rejected when they fail schema validation. Common reasons:

    * Property name does not exist in the schema
    * Property value does not match the expected data type
    * Required property is missing
    * Property value exceeds maximum length

    Check your browser console for error messages, and verify your event tracking code matches the schema exactly.
  </Accordion>

  <Accordion title="Can I use events to build cohorts?">
    Yes, events are the primary data source for building Custom Cohorts in Permutive. You can create cohorts based on:

    * Which events users have triggered (e.g., "Viewed at least 3 articles")
    * Event property values (e.g., "Viewed articles in the Sports category")
    * Recency (e.g., "In the past 7 days")
    * Frequency (e.g., "At least 5 times")

    See our [Custom Cohorts](/products/signals/cohorts/custom) documentation for more details.
  </Accordion>

  <Accordion title="What event properties are collected on every event?">
    Standard properties collected on all events include:

    * `client.domain`: The domain where the event occurred (web)
    * `client.url`: The URL where the event occurred (web)
    * `client.title`: The page or screen title
    * `client.referrer`: The referring URL (web)
    * `client.type`: The platform type (web, iOS, Android, CTV)
    * `client.user_agent`: The browser or app user agent

    Note: Some properties (like `client.domain`, `client.url`, `client.referrer`) are web-specific. Mobile and CTV platforms collect equivalent properties appropriate to their environment.

    Plus internal properties like `event_id`, `user_id`, `session_id`, `view_id`, and `time`.
  </Accordion>
</AccordionGroup>

## Changelog

<Info>
  For detailed changelog information, visit our
  [Changelog](https://changelog.permutive.com/).
</Info>