# Lytics Implementation ### About this export | Field | Value | | --- | --- | | **content_type** | course | | **platform** | contentstack-academy | | **source_url** | https://www.contentstack.com/academy/courses/lytics-implementation | | **language** | en | | **product_area** | Contentstack Academy | | **learning_path** | standalone | | **course_id** | lytics-implementation | | **slug** | lytics-implementation | | **version** | 2026-08-06 | | **last_updated** | 2026-08-07 | | **status** | published | | **keywords** | ["Contentstack Academy"] | | **summary_one_line** | Overview Lytics Implementation is a comprehensive training program designed to help technical teams, marketers, and content strategists successfully implement, operate, and maintain the Lytics Customer Data Platform. The… | | **total_duration_minutes** | 254 | | **lessons_count** | 19 | | **video_lessons_count** | 1 | | **text_lessons_count** | 18 | | **linked_learning_path** | standalone | | **linked_assessment_ref** | LMS_UNCONFIGURED_COURSE_ASSESSMENT | | **markdown_file_url** | /academy/md/courses/lytics-implementation.md | | **generated_at** | 2026-08-07T05:57:36.297Z | | **intended_audience** | [] | | **prerequisites** | [] | | **related_courses** | [] | > **Academy MD v3** — companion `.md` for Ask AI. Quizzes and graded assessments are **LMS-only**; this file never contains answer keys. ## Course Overview | Metadata | Value | | --- | --- | | Catalog duration | 4h 14m 19s | | Released (if known) | 2026-08-06 | | Product area | Contentstack Academy | ### Description ### Overview **Lytics Implementation** is a comprehensive training program designed to help technical teams, marketers, and content strategists successfully implement, operate, and maintain the Lytics Customer Data Platform. The course walks learners through the full data lifecycle: setting up secure account settings, ingesting real-time events, stitching anonymous browser behavior into unified profiles using identity resolution, and mapping custom data schemas. From there, it focuses on driving measurable business outcomes. Learners discover how to build dynamic audiences, leverage machine learning for predictive lookalike modeling, analyze cross-audience insights, and orchestrate multi-step journey flows. The curriculum wraps up with practical on-site web personalization via Pathfora, ongoing operational maintenance routines, and six ready-to-use capstone blueprints—covering everything from unknown-to-known lead capture to server-side Conversion API exports. ### Learning objectives 1. Follow each lesson in order. 2. Practice in a training stack using placeholders **YOUR_STACK_API_KEY** and **YOUR_DELIVERY_TOKEN** in local `.env` files only. 3. Validate API responses against the official documentation. ### Topics covered Contentstack Academy ## Course structure ```text lytics-implementation/ ├── 01-welcome-to-lytics · text · 12 min ├── 02-account-configuration · text · 21 min ├── 03-data-flow · text · 24 min ├── 04-profile · text · 23 min ├── 05-id-resolution · text · 12 min ├── 06-tag · text · 15 min ├── 07-schema · text · 17 min ├── 08-integrations-connections · text · 17 min ├── 09-audience-building · video · 499s ├── 10-content · text · 14 min ├── 11-audience-insights-app · text · 7 min ├── 12-lookalike-model · text · 14 min ├── 13-reports · text · 11 min ├── 14-flows · text · 14 min ├── 15-pathfora · text · 13 min ├── 16-use-cases · text · 13 min ├── 17-setting-up-personalize · text · 4 min ├── 18-permissions-user-management · text · 4 min ├── 19-ongoing-maintenance · text · 11 min ``` ## Lessons ### Lesson 01 — Welcome to Lytics #### Lesson text Lytics is a Customer Data Platform designed to unify customer data from every source your business uses, enrich it with behavioral intelligence, and put it to work across every channel. Before you can configure integrations, build audiences, or activate campaigns, you need a clear mental model of what the platform does and how it is organized. This section establishes that foundation — you will see why a CDP exists, how data moves through the five-stage pipeline, where to find things in the UI, what the platform makes possible, and how the rest of this course is structured. ## Why Lytics? ### Learning Objectives By the end of this section, you will be able to: * Explain what a Customer Data Platform (CDP) does * Articulate the core value proposition of Lytics * Identify who benefits from the platform and how ### What Problem Does It Solve? Your customer data lives in dozens of different tools — your website, apps, CRM, email platform, and data warehouse. Each tool sees a fraction of who your customers are, but none of these platforms see the whole picture. You can't personalize what you don't know, and you can't act on data that's stuck in silos. A **Customer Data Platform (CDP)** solves this by collecting data from all of your sources, stitching it together into unified profiles, and making those profiles available for segmentation and activation across every channel. **Lytics** is a CDP that does three things well: 1. **Collects data** from your website, apps, CRM, email tools, data warehouse, and more 2. **Builds unified profiles** by resolving identities and enriching each profile with behavioral intelligence and content interests 3. **Lets you act** on those profiles — build audiences, personalize your website, share to ad platforms, and orchestrate multi-step journeys Different teams use the platform in different ways. **Marketers** build audiences and activate them across channels. **Content strategists** use content intelligence to understand what topics resonate with which audiences. **Technical teams** configure data pipelines, manage integrations, and extend the platform through APIs. This course is designed to serve all of you. ### Summary Lytics is a Customer Data Platform that collects data from all your sources, builds unified profiles through identity resolution and behavioral enrichment, and makes those profiles available for segmentation and activation across channels. It serves marketers, content strategists, and technical teams with a shared foundation of unified customer data. ### Documentation Links * [What is Lytics?](https://docs.lytics.com/docs/lytics-overview) * [Getting Started](https://docs.lytics.com/docs/getting-started) ## How It Works: From Data to Action ### Learning Objectives By the end of this section, you will be able to: * Describe the five stages of the data pipeline at a high level * Understand that profiles are the central concept in the platform ### Platform Overview The platform does a lot under the hood, but at a high level your data always follows the same path through five stages: Collect, Unify, Enrich, Segment, and Activate. Once you see how those stages connect, everything else in the product starts to make sense. During collection, or the Collect stage, the platform receives raw events. The Unify stage is when raw events are resolved onto profiles. Profile enrichment happens automatically, thanks to the ML-based processes working under the hood. The Segment stage allows you to group your profiles based on your goals, and ultimately Activate them in downstream tools. While each stage has a dedicated module later in the course, the included overview of each stage below will help you see how the pieces connect so you have a mental map to anchor everything that follows. **1\. Collect** — Data flows into the platform from many sources: your website (via a JavaScript tag), imports from your CRM or email platform, syncs with your data warehouse, and direct API calls. **2\. Unify** — When data arrives, the platform's **identity rules** recognize identifiers — email addresses, cookie IDs, customer IDs — and stitch them, along with the associated event data, together. The goal is to connect all the data that belongs to the same person into a single **profile**, even when that data arrives from different sources and devices. For a deeper look, see [Identity Resolution](/academy/courses/lytics-course/id-resolution). **3\. Enrich** — Once a profile is unified, the platform automatically computes additional intelligence. **Behavioral scores** quantify engagement patterns across dimensions like recency, frequency, and momentum. **Content interest** scores measure each person's interest in your content topics. These computed attributes update continuously as new data arrives. For details, see [Profile](/academy/courses/lytics-course/profile). **4\. Segment** — With enriched profiles in place, you build **audiences** — dynamic segments that automatically update as profile data changes. You can combine any profile attributes: behavioral scores, content affinity, first-party data, warehouse data, pre-existing audiences, etc. Audiences are the central building block for everything you do in the platform. For details, see [Audience Building](/academy/courses/lytics-course/audience-building). **5\. Activate** — Finally, you put your audiences to work. Personalize your website with targeted messages. Export audiences to your ad platforms and email tools. Orchestrate multi-step journeys that respond to user behavior in real time. For a comprehensive treatment of the full pipeline, see [Data Flow](/academy/courses/lytics-course/data-flow). ### Summary Data moves through Lytics in five stages: Collect (ingest raw events from websites, CRMs, warehouses, and APIs), Unify (resolve identities and stitch data into single profiles), Enrich (compute behavioral scores and content interest automatically), Segment (build dynamic audiences from any combination of profile attributes), and Activate (push audiences to ad platforms, personalize your website, or orchestrate journeys). Profiles are the central concept that everything else revolves around. ### Documentation Links * [Data Pipeline Overview](https://docs.lytics.com/docs/data-pipeline) * [Identity Resolution](https://docs.lytics.com/docs/identity-resolution) * [Behavioral Scoring](https://docs.lytics.com/docs/behavioral-scoring) ## Finding Your Way Around ### Learning Objectives By the end of this section, you will be able to: * Identify the main navigation areas of the platform * Understand what kind of work happens in each area ### Platform Navigation Now that you understand the data pipeline, let's take a quick look at where things live in the platform. The navigation is organized around that same pipeline — getting data in, building profiles from it, and then acting on those profiles. You don't need to memorize every menu item right now; you'll spend hands-on time in each area as you progress through the course. Think of this as a quick orientation so nothing feels unfamiliar when you start clicking around. **Home** is your starting point. When you log in, you land on a dashboard that gives you a high-level view of your account's activity and health. **Data Pipeline** is where you manage everything related to getting data into and out of the platform. You'll configure import and export jobs, connect to your data warehouse, manage data streams, and access your account's unique JavaScript tag. If data isn't flowing yet, this is where you start. **Building Profiles** is where raw data becomes unified profiles. You'll work with the profile schema (which defines what fields exist on a profile), configure identity resolution rules, and explore your data. When you need to look up an individual profile, the search tool lives here too. **Using Profiles** is where you act on your data. This is home to audiences, Lytics client-side experiences, composable reports, multi-step flows, and lookalike models. Most of a business user's day-to-day work happens here. **Content** manages the platform's content intelligence engine. It classifies your web content into topics and uses that classification to build content interest scores on profiles. You can browse your content index, manage your topic taxonomy, create custom context layers, and curate content collections for recommendations. **Account** is where you handle administrative tasks — user management (for CDP-only customers), security settings, API tokens, event usage, and account-level configuration. ![Walkthrough of the Lytics UI navigation: Home dashboard, Data Pipeline, Building Profiles, Using Profiles, Content, and Account areas. Show where key tools live and how navigation maps to the data pipeline stages.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ambad89731e1aa6efd/50a5de84b053715c2ca843c4/walkthrough_lytics_ui_navigation_home.gif) ### Summary The Lytics UI is organized around the data pipeline flow. Home provides an activity dashboard. Data Pipeline manages imports, exports, warehouse syncs, and the JavaScript tag. Building Profiles covers schema, identity resolution, and profile search. Using Profiles is where you build audiences, create experiences, run reports, configure flows, and train lookalike models. Content manages the content intelligence engine. Account handles administration and security. ### Documentation Links * [Navigating Lytics](https://docs.lytics.com/docs/navigating-lytics) * [Account Settings](https://docs.lytics.com/docs/account-settings) ## What Can You Do With It? ### Learning Objectives By the end of this section, you will be able to: * Identify high-level use cases for Lytics * Understand that audiences are central to all activation ### Common Use Cases Lytics supports a wide range of use cases, from AI-powered capabilities to predict which customers are likely to convert or churn to personalizing web experiences. While a number of use cases are focused on activation, the platform also provides opportunities to increase reach, improve match rates or optimize ad campaigns. Below is a short preview of some of the most common ones. **Web Personalization** — Your website shows the same content to everyone, but your visitors have different needs. Lytics lets you build audiences based on behavior and interests, then display targeted messages — variants, modals, banners, inline content — to the right people at the right time. **Unknown to Known Conversion** — Anonymous visitors have value, but known contacts have more value. By capturing merge events — logins, account registrations, and lead capture forms — you can stitch together anonymous browsing history into a unified profile, steadily growing your addressable audience with every new identification. **Audience Activation** — Instead of manually exporting CSV lists to your ad platforms, you configure export jobs that continuously push audience membership to Facebook, Google Ads, LinkedIn, and other channels. Audiences stay in sync as people enter and exit segments. **Conversion Event Export** — Beyond syncing audience lists, you can push conversion events — purchases, sign-ups, form submissions, and other key actions — directly to Facebook, Google Ads, LinkedIn, and other ad platforms. This gives each platform's algorithm a richer signal to optimize against, improving bid efficiency, reducing wasted spend, and unlocking smarter lookalike and value-based audience targeting. **Journey Orchestration** — For multi-step campaigns — cart abandonment sequences, onboarding drips, re-engagement programs — you build visual workflows that chain together wait steps, conditional logic, and cross-channel actions based on user behavior. **Churn Prediction and Win-Back** — Machine learning models score each profile on their likelihood of churning, so you can target at-risk users with retention campaigns before they disengage. Each of these use cases is explored in detail in the [Use Cases](/academy/courses/lytics-course/use-cases) module and throughout the course. ### Summary Lytics supports use cases spanning the full customer lifecycle: web personalization to show targeted content based on behavior and interests, unknown-to-known conversion to grow your addressable audience, audience activation to keep ad platforms in sync continuously, conversion event export to improve ad algorithm optimization, journey orchestration for multi-step campaigns, and churn prediction for proactive retention. Audiences are the central building block that powers all of these. ### Documentation Links * [Use Cases](https://docs.lytics.com/docs/use-cases) * [Web Personalization](https://docs.lytics.com/docs/web-personalization) * [Audience Activation](https://docs.lytics.com/docs/audience-activation) ## Your Learning Path ### Learning Objectives By the end of this section, you will be able to: * Understand the course structure and how modules build on each other * Know where to go next ### Course Roadmap You've covered a lot of ground in this overview — the problem the platform solves, how data moves through it, where to find things, and what you can do with it. The rest of this course takes each of those topics and goes deep. The modules are ordered to follow the natural progression of a platform implementation, starting with account setup and working through data collection, profile building, and activation. Each module builds on concepts from the ones before it: 1. **Platform Overview** — You are here 2. [**Account Configuration**](/academy/courses/lytics-course/account-configuration) — Set up your account, security, and API access 3. [**Data Flow**](/academy/courses/lytics-course/data-flow) — Understand how data moves through the platform 4. [**Profile**](/academy/courses/lytics-course/profile) — Learn the structure of unified profiles 5. [**Identity Resolution**](/academy/courses/lytics-course/id-resolution) — Configure how identities are stitched together 6. [**Tag**](/academy/courses/lytics-course/tag) — Install and configure the JavaScript tag 7. [**Schema**](/academy/courses/lytics-course/schema) — Manage your data model and field mappings 8. [**Integrations & Connections**](/academy/courses/lytics-course/integrations-connections) — Connect to external tools and data sources 9. [**Audience Building**](/academy/courses/lytics-course/audience-building) — Build and manage dynamic audiences 10. [**Content**](/academy/courses/lytics-course/content) — Content classification and affinity scoring 11. [**Audience Insights App**](/academy/courses/lytics-course/audience-insights-app) — Marketplace integration 12. [**Lookalike Models**](/academy/courses/lytics-course/lookalike-model) — Predictive modeling and audience expansion 13. [**Reports**](/academy/courses/lytics-course/reports) — Composable reporting and dashboards 14. [**Flows**](/academy/courses/lytics-course/flows) — Multi-step journey orchestration 15. [**Pathfora**](/academy/courses/lytics-course/pathfora) — Web personalization SDK 16. [**Use Cases**](/academy/courses/lytics-course/use-cases) — End-to-end implementation patterns You don't have to complete every module in strict order, but the early modules (Account Configuration through Schema) establish foundational concepts that later modules assume you know. ### Summary The course follows the natural progression of a platform implementation: account setup, data collection, profile building, and activation. Early modules establish foundational concepts that later modules build on. While you can navigate non-linearly, completing Account Configuration through Schema first gives you the strongest foundation. **Next step:** Proceed to [Account Configuration](/academy/courses/lytics-course/account-configuration) to set up your account. ## What You've Learned At this point, you understand what a Customer Data Platform does and why Lytics exists — to break down the data silos between your tools and give you a single, unified view of every customer. You've seen how data moves through the platform's five-stage pipeline, from collection through identity resolution, enrichment, segmentation, and activation. You know where to find things in the UI and how the navigation maps to that same data-to-action flow. You've also gotten a preview of what the platform makes possible — from personalizing your website and converting anonymous visitors into known contacts, to activating audiences to ad platforms and orchestrating multi-step journeys. Most importantly, you know how the rest of this course is structured and that each module ahead will take one of these topics and go deep. You're ready to get started. ### Key Terms > 📘 **Customer Data Platform (CDP)** — A system that collects first-party customer data from multiple sources, resolves identities to create unified profiles, and makes those profiles available for segmentation and activation across channels. > > 📘 **Profile** — A single, unified record representing all known data about one individual across devices and channels. Profiles are the central concept in Lytics. > > 📘 **Audience** — A dynamic segment definition that continuously evaluates profile data. Membership updates automatically as profiles change. > > 📘 **Behavioral Score** — A platform-computed metric that quantifies engagement patterns across dimensions like recency, frequency, and momentum. > > 📘 **Content Affinity** — A platform-computed score measuring each profile's interest in your content topics, based on browsing history. > > 📘 **Identity Resolution** — The process of recognizing identifiers (email, cookie IDs, customer IDs) across sources and stitching them together into a single unified profile. > > 📘 **Activation** — The process of putting audiences to work in downstream systems — ad platforms, email tools, web personalization, or journey orchestration. #### Key takeaways - Connect **Welcome to Lytics** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 02 — Account Configuration #### Lesson text Before you can collect data, build profiles, or activate audiences, you need a properly configured account. That means setting up security policies, creating the right user roles, generating API tokens for your integrations, and installing the SDKs that will send data into the platform. Getting this foundation right prevents problems downstream — misconfigured security leaves your account exposed, missing API tokens block integrations, and an improperly installed tag means no behavioral data flowing in. This module walks you through every step of account setup so you can move into data collection with confidence. ## Account Settings ### Learning Objectives By the end of this section, you will be able to: \- Navigate to the Vault and identify each settings category \- Configure account details including name, domain, and API access \- Apply security policies for login sessions, passwords, and two-factor authentication \- Manage users, assign roles, and control access to PII \- Generate, manage, and revoke API access tokens \- Create and monitor third-party authorizations ### Accessing the Vault The **Vault** — Lytics' centralized account administration area — is where you manage settings, users, security, and SDK setup. You access it by clicking the **Product Switcher** in the top navigation and selecting **Vault**, or by clicking **Account Settings** from the secondary account menu in the bottom-left corner of the UI. The Vault is organized into five top-level sections: Section Path What You Configure **Usage** `/vault/usage` Account quota overview and consumption metrics **Settings** `/vault/settings/...` Account details, JavaScript Tag, API, Content, Security, Data Science, Schema, Company Profile, Audiences **Users** `/vault/users` User accounts, roles, and permissions **Security** `/vault/security/...` Access tokens and third-party authorizations **Setup** `/vault/setup/js` JavaScript Tag installation on your website ![Vault landing page showing the five top-level navigation sections (Usage, Settings, Users, Security, Setup).](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am706541a37c1fef70/1dae4ba926e6313667d82802/vault_landing_page_five_top.png) ### Account Details Navigate to **Settings > Account Details** (`/vault/settings/details`) to configure your core account information. Field Editable Description **Account Name** Yes Label shown in the account switcher for multi-account users **Domain** Yes Primary domain associated with your account **Contact** Yes Email address of your primary account contact **Allow Access via API** Yes Enables profile data sharing via the Personalization API — required for integrations like Google Analytics that read profile data client-side **Account ID** No Unique identifier used in all API calls (`cid` parameter) **Account Number** No Unique account number for quick reference > Your **Account ID** is the value you pass as `cid` when installing the JavaScript Tag. Copy it from this page when setting up SDKs. ### Settings Categories Beyond Account Details, the **Settings** section contains category-specific configuration pages. Each page controls a distinct area of platform behavior: Category Path Sub-Categories **JavaScript Tag** `/vault/settings/tag` v3 Configuration, Legacy v2 Configuration, Client Side Integrations, Personalization Settings, Data Collection **Lytics API** `/vault/settings/api` API Security, Data Collection, Public API **Content** `/vault/settings/content` Content Topics, Content Enrichment, Content Affinities, Content Recommendations **Security** `/vault/settings/security` Login Sessions, Login Policies **Data Science** `/vault/settings/data_science` EntQL fields, decisioning triggers, scoring streams **Schema** `/vault/settings/schema` Private fields, promoted fields, field hiding **Company Profile** `/vault/settings/onboarding` Company information from onboarding **Audiences** `/vault/settings/audience` Audience similarity enforcement The JavaScript Tag and API settings are covered in detail in the [SDKs](#sdks) section below. The remaining categories are introduced here and covered in depth in their respective academy topics. #### Content Settings Content settings control how Lytics classifies and indexes your web content. Key options include: * **Content topic allowlist / blocklist** — Control which topics appear in your content taxonomy * **Content domains allowlist / blocklist** — Restrict which domains Lytics classifies * **Content paths allowlist / blocklist** — Filter URLs by path substring * **Content created since date** — Only include content after a specified date * **Supported content languages** — Languages permitted during enrichment (empty defaults to English only) * **Observe robots.txt** — Options: `robotstxt`, `meta`, or `none` For more on content classification, see [Content](/academy/courses/lytics-course/content). #### Schema Settings Schema settings control which fields are treated as sensitive and which are surfaced for data science: * **Private fields** — Fields containing PII. These are hidden from users without Admin, Data Manager, or User Search roles. * **Promoted fields** — Fields outside the defaults that you want leveraged in data science modeling and reporting. * **Hide Private Fields** — When enabled, hides PII from exports and segment scans for non-privileged users. > Verify with Lytics Support that field hiding in the segment scan is also enabled for your account to ensure private fields are hidden everywhere. #### Data Science Settings Data Science settings control AI-driven features: * **EntQL Fields** — Fields evaluated via EntQL in the merger before indexing an entity * **Enable Decisioning Triggers** — Auto-trigger Experiences configured for decisioning * **Streams to Allow for Scoring** — Custom streams containing behavioral signals for scoring * **Enable Decisioning Scores** — Enrich profiles with `needs_message` score and `next_event` timestamp per stream ### Security Settings Navigate to **Settings > Security** (`/vault/settings/security`) to configure login and password policies. #### Login Sessions Setting Description **Logon session days** Number of days before forcing re-authentication **Logon session timeout minutes** Minutes of inactivity before forcing re-authentication #### Login Policies Setting Description **Enforce password complexity** Requires minimum 8 characters, at least 1 uppercase (A–Z), 1 lowercase (a–z), 1 digit (0–9), and 1 special character (!@#$&\*) **Enforce password history** Prevents re-use of previous passwords per user **Enforce password bad count** Locks account after too many failed login attempts **Password max age** Maximum days before a password change is required (set to `0` to disable) **Enforce two-factor authentication** Requires 2FA for all account users via Authy SoftToken — users must provide a phone number > Enable 2FA for all production accounts. It adds a second authentication factor (a code that changes every 20 seconds) after the standard password step. ![Security settings page showing login session and login policy configuration options.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am356bdc3a05ba9079/f76f83eb19ebff55a5986e8d/security_settings_page_login_session.png) #### Single Sign-On (SSO) Lytics supports SAML-based SSO using Google Cloud Identity Platform as the service provider. SSO is SP-initiated only (IdP-initiated is deprecated). To configure SSO, contact Lytics Support and provide: * **Entity ID** from your identity provider * **Sign In URL** from your identity provider * **X509 Signing Certificate** from your identity provider Lytics provides the **ACS URL**, **Service Provider Entity ID**, and **Sign-in URL** in return. SSO supports role assignment via group names in the format `lytics__` (for example, `lytics_123_admin` or `lytics_123_content_manager`). Lytics has published configuration guides for both Okta and OneLogin. ### User Management Navigate to **Users** (`/vault/users`) to manage who has access to your account. #### Inviting Users 1. Click **Create New** from the user list. 2. Enter the user's email address. 3. Select one or more roles. 4. The user receives an email with a login link. ![Walk through inviting a new user: click Create New, enter email, assign roles, and show the resulting invitation. Then demonstrate editing roles on an existing user.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am9f6561352bf55ef7/194853f2e36b1d179e52b1ce/walk_inviting_user_click_create.gif) #### Roles and Permissions Lytics provides granular role-based access control. Each user can be assigned one or more roles: Role Access Level **Admin** Full read/write access to all features and management functions **Data Manager** Read/write access to schemas, queries, users, content, integrations; includes PII access **Audience Manager** Read/write access to audiences **Campaign Manager** Read/write access to campaigns and audiences; no PII, cannot publish campaigns **Content Manager** Read/write access to content classification, collections, topics **Experience Manager** Read/write access to Experiences **Goal Manager** Read/write access to Goals and Experiences **Marketer** Read/write access to audiences and campaigns; no PII **Observer** Read-only access to audiences and campaigns **User Search** Ability to search users and view profiles **Discovery Insights** Access to explore discovery insights > Only users with **Admin**, **Data Manager**, or **User Search** roles can view fields marked as private (PII). Assign roles deliberately to limit PII exposure across your team. #### Managing Your Profile Each user can manage their own profile by navigating to **Manage My User** from the account menu. You can update your name, email, and phone number (required for 2FA). Password changes are self-service — navigate to **Manage My Profile > Change Password**. Changing your password immediately invalidates all current sessions. ### Access Tokens Navigate to **Security > Access Tokens** (`/vault/security/tokens`) to manage API tokens. An access token is a credential that authenticates API requests to Lytics — each token is scoped to specific roles and has a configurable expiration. #### Creating a Token 1. Click **Create New**. 2. Fill in the required fields: Field Required Options **Name** Yes Descriptive label for the token **Description** No Explain the token's purpose and which system uses it **Expiration** Yes 90 days, 30 days, 7 days, or No expiration **Roles** Yes Fine-grained permission selection matching user roles 3. Click **Create**. The token value appears in a one-time dialog. 4. **Copy the token immediately** — you cannot view it again after dismissing the dialog. ![Demonstrate creating an access token: click Create New, fill in name/description/expiration/roles, click Create, and copy the one-time token value.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am7bef78007522ae3d/cb28687212ac0abc5d3e1dec/demonstrate_creating_access_token_click.gif) #### Token Best Practices * **Name tokens descriptively** — include the system or integration that uses the token (for example, `segment-export-prod` or `gtm-data-collection`). * **Set expiration dates** — use 90-day or shorter expirations for production tokens and rotate before they expire. * **Use least-privilege roles** — scope each token to only the permissions it needs. * **Store securely** — keep tokens in a secrets manager or environment variable, never in source code. * **Delete unused tokens promptly** — deletion is irreversible and immediately breaks dependent processes, so confirm which systems rely on a token before removing it. #### Managing Tokens The token list is sortable and filterable by name, description, creator, and expiration status. Click any token to view its assigned roles, creation date, and expiration date. ### Authorizations Navigate to **Security > Authorizations** (`/vault/security/authorizations`) to manage credentials for third-party integrations. An authorization is a stored credential that grants Lytics permission to exchange data with a third-party service (email provider, ad platform, data warehouse, etc.). #### Creating an Authorization 1. Click **Create New** to open the authorization wizard. 2. **Choose the provider** — select the third-party tool you are connecting to. 3. **Select the authorization method** — some providers offer a single method, others offer multiple (API key, OAuth, personal/business user tokens). The method you choose determines which job types (real-time vs. bulk) are available. 4. **Add a name, description, and complete the configuration** specific to that provider. ![Walk through creating an authorization: open the wizard, select a provider, choose the authorization method, complete the configuration, and verify health status.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am84b1e1ae7ef39120/b3dff2264a5554c12d0bd6b7/walk_creating_authorization_open_wizard.gif) #### Authorization Health Lytics checks authorization status daily and reports one of three states: Status Meaning **Healthy** Authorization is valid and active **Unhealthy** Authorization is invalid or expired — jobs using it will fail **Unknown** Status could not be determined #### Managing Authorizations * **Edit** — You can rename and revise the description, but you cannot change the configuration (credentials). To change credentials, create a new authorization. * **Delete** — You can only delete an authorization if no active jobs (running, sleeping, or paused) reference it. * **Activity Metrics** — For select providers (Facebook, Iterable, Salesforce, SendGrid, and others), you can view request counts on hourly, daily, weekly, and monthly timescales. * **Associated Jobs** — Each authorization's detail page shows a table of all active jobs using it. #### Monitoring and Alerts You can configure alerts on any job or authorization to receive notifications when failures occur. Alert channels include: * **Slack** * **Microsoft Teams** * **Email** Alerts include the latest error message for quick diagnosis. For detailed troubleshooting, use the Job Logs API. ### Platform Limits Lytics enforces limits that affect account configuration decisions. Key limits to keep in mind: Resource Limit Max user profile size 1 MB Max profile identifier size 256 bytes Max user attribute values 1,000 (includes complex field types) Max stitched identifiers per profile 50 Max single event input size 4 KB Max batch record size 16 KB Max total batch size 1 GB Max audiences 500 Max conditions per audience 1,000 Max active import integrations 100 Max active export integrations 200 Max integration creations per hour 10 Max Cloud Connect data models 100 Completed job retention 90 days ### Summary The Vault is the centralized hub for all account administration. Account details (name, domain, API access) and security policies (session timeouts, password complexity, 2FA, SSO) establish your account's baseline configuration. User management follows a role-based access model where each user gets the minimum permissions needed — only Admin, Data Manager, and User Search roles can access PII. Access tokens authenticate API integrations and should be named descriptively, scoped to least-privilege roles, and rotated on a schedule. Authorizations store credentials for third-party services and should be monitored for health status. Platform limits (max audiences, profile size, integration counts) should inform your configuration decisions from the start. ### Documentation Links * [Account Settings](https://docs.lytics.com/docs/account-settings) * [User Management](https://docs.lytics.com/docs/user-management) * [Access Tokens](https://docs.lytics.com/docs/api-tokens) * [Authorizations](https://docs.lytics.com/docs/authorizations) * [Platform Limits](https://docs.lytics.com/docs/platform-limits) ## SDKs ### Learning Objectives By the end of this section, you will be able to: \- Install the Lytics JavaScript Tag on a web property \- Configure the tag with required and optional parameters \- Identify the available mobile SDKs and their configuration patterns \- Verify that the SDK is correctly collecting and transmitting event data \- Use the Chrome DevTools extension for debugging ### JavaScript Tag Installation The JavaScript Tag (jstag) — Lytics' client-side SDK for web properties — is the primary mechanism for collecting behavioral data from your website. It tracks user behavior, resolves identity, surfaces profile data for personalization, and loads the Pathfora SDK for web experiences. Version 3 is the current recommended version. #### Installation Methods **Direct installation** — Copy the tag snippet from **Setup > Website (JS Tag)** (`/vault/setup/js`) in the Vault and paste it into your site's `` section: ```html ``` Replace `YOUR_ACCOUNT_ID` with the Account ID from your **Account Details** page. **Google Tag Manager** — If you use GTM: 1. Log into your GTM account. 2. Click **New Tag > Tag Configuration**. 3. Under Custom, select **Custom HTML**. 4. Paste the Lytics JavaScript Tag snippet. 5. Name the tag `Lytics JavaScript Tag`. 6. Set the trigger to **All Pages**. 7. Click **Save**, then **Submit** to publish. ![Demonstrate both installation methods: direct snippet installation in a site's HTML head, and Google Tag Manager setup with Custom HTML tag and All Pages trigger.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ama7505f0b0263439c/64fa60912826345b5a536022/demonstrate_both_installation_methods_direct.gif) #### What the Tag Does When the tag loads on a page, it performs four functions: 1. **Tracks behavior** — Automatically collects page views, referral data, device information, and user language. Each event is sent to the Lytics collection endpoint. 2. **Resolves identity** — Manages the `_uid` cookie to maintain a persistent anonymous identifier across sessions. When you send known identifiers (email, user ID), the tag associates them with the anonymous profile. 3. **Surfaces profile data** — Retrieves the current user's profile from the Personalization API, including audience membership and behavioral scores, making it available client-side for personalization logic. 4. **Loads Pathfora** — When enabled, loads the Pathfora SDK to evaluate and display web Experiences (modals, bars, slideouts) based on audience membership. #### Automatically Collected Fields The tag automatically collects these fields on every event: Field Example Description `_e` `pv` Event type (`pv` = page view) `_ref` `www.lytics.com` Referral domain `_tz` `-7` Timezone offset from UTC `_ul` `en-US` User language `_sz` `2560x1440` Display size `_ts` `1504306728695` Timestamp (milliseconds since epoch) `_nmob` `t` Mobile device indicator `_device` `desktop` Device type `url` `www.example.com/page` Current page URL `_uid` `74481.3222228897` Lytics cookie ID `_v` `3.0.2` JavaScript Tag version ### JavaScript Tag Configuration The `jstag.init()` call accepts a configuration object with required and optional parameters. #### Required Parameters Key Type Description `src` string URL of the tag script: `https://c.lytics.io/api/tag/{YOUR_ACCOUNT_ID}/latest.min.js` > The `cid` (Account ID) is embedded in the `src` URL. You do not need to pass it separately in v3. #### Optional Parameters Key Type Default Description `loadid` boolean `false` Enable cross-domain user identification using third-party cookies `stream` string `getlytics` Name of the data stream for collection `sessecs` integer `1800` Session timeout in seconds — time between requests before a new session starts `qsargs` string\[\] — Array of URL query parameters to capture (e.g., `['utm_source', 'utm_medium']`) `serializer` string `default` Serializer type (`default` or `legacy` for v2 compatibility) `cookies` object — Cookie domain configuration for cross-subdomain tracking #### Custom User Identification When you have an authenticated user, pass their identifier at initialization to link anonymous and known profiles: ```javascript var user = getAuthenticatedUser(); var config = { src: 'https://c.lytics.io/api/tag/YOUR_ACCOUNT_ID/latest.min.js' }; if (user) { config.entity = { byFieldKey: 'custom_uuid', byFieldValue: user.uuid }; } jstag.init(config); ``` #### Sending Custom Events Use `jstag.send()` to send custom event data beyond automatic page views: ```javascript // Send user identity data jstag.send({ email: 'user@example.com', name: 'Jane Doe', company: 'Acme Corp' }); // Send a custom event jstag.send({ event: 'purchase_complete', currency: 'USD', value: 49.99 }); // Send to a specific stream with a callback jstag.send('custom_stream', { action: 'signup' }, function(response) { console.log(response); }); ``` #### Single Page App (SPA) Configuration For single page applications, you need to manually trigger page views and re-fetch the profile on route changes: ```javascript var onRouteChange = function() { // Track route change as a page view jstag.pageView(); // Re-fetch profile and re-evaluate Experiences jstag.loadEntity(function(profile) { console.log(profile.data); }); }; ``` #### Account-Level Tag Settings In addition to the client-side `init()` configuration, you control tag behavior through account settings at **Settings > JavaScript Tag** (`/vault/settings/tag`). These settings are organized into sub-categories: **v3 Configuration** — Core settings for the current tag version: \- **JavaScript Tag TTL** — Cache duration in seconds (lower for testing, higher for production) \- **Enable pageview event on first send** — Automatically adds a `_e: pv` event type on the first `send` call per page load **Client Side Integrations** — Enable or disable automatic data sync with third-party platforms. Configurable integrations include Amazon DSP, Criteo, Google Ads, GA4, DV360, Lotame, Taboola, The Trade Desk, and Yahoo Ads. Additional integrations (AdRoll, Facebook Ads, Google Analytics, GTM, Pathfora, and others) activate automatically. **Personalization Settings** — Control Pathfora and Experiences behavior: \- **Allow Pathfora** — Enable or disable the Pathfora personalization library \- **Allow Event Block** — `0` (off), `1` (active Experiences only), `2` (permanently on) \- **Global Stylesheet URL** — Custom CSS for Lytics-managed Experiences \- **URL Allowlist for Orchestration** — Restrict which URLs evaluate Experiences **Data Collection** — Control how the tag collects incoming data: \- **Custom Cookie Keys** — Cookie names to automatically collect \- **Custom Data Layer** — JavaScript variables to automatically collect \- **Integrations Blocklist** — Prevent specific integrations from syncing ### Mobile SDKs Lytics provides native mobile SDKs for iOS, Android, and React Native. Each SDK follows the same core pattern: initialize with your API token, then use `track`, `identify`, and `consent` methods. #### iOS SDK **Requirements:** iOS 14.0+, Xcode v14.2+ **Installation:** Add the Swift package from `https://github.com/lytics/ios-sdk` via Xcode's **File > Add Packages**. ```swift Lytics.shared.start(apiToken: "YOUR_API_TOKEN") { configuration in configuration.defaultStream = "ios_sdk" configuration.logLevel = .debug configuration.maxQueueSize = 10 configuration.uploadInterval = 10 configuration.sessionDuration = 1200 } ``` #### Android SDK **Requirements:** Android 8+, Android Studio v2021.3.1+ **Installation:** Add the JitPack repository and the dependency `com.github.lytics:android-sdk:`. ```kotlin Lytics.init(applicationContext, LyticsConfiguration( apiKey = "YOUR_API_TOKEN", defaultStream = "android_sdk", logLevel = LogLevel.DEBUG, maxQueueSize = 10 )) ``` #### React Native SDK **Installation:** `yarn add react-native-lytics` ```javascript import { start } from 'react-native-lytics'; start({ apiToken: 'YOUR_API_TOKEN', defaultStream: 'react_native_sdk', logLevel: LogLevel.debug, maxQueueSize: 10 }); ``` #### Common Mobile SDK Configuration Parameters All three mobile SDKs share these configuration options: Parameter Default Description `apiKey` / `apiToken` — Your Lytics API token (required) `defaultStream` SDK-specific Default stream name for events `primaryIdentityKey` `_uid` Strongest identifier key for identity resolution `uploadInterval` `10` seconds How often the SDK flushes queued events `maxQueueSize` `10` Maximum events queued before an automatic flush `sessionDuration` `1200` seconds Inactivity timeout before starting a new session `requireConsent` `false` When `true`, no data is sent until the user opts in `enableSandbox` `false` When `true`, events are validated but not persisted `logLevel` `.error` Logging verbosity (`.error`, `.info`, `.debug`) #### Mobile SDK Core Methods Each SDK provides the same core methods: * **`track`** — Send a custom event with properties * **`identify`** — Associate the current device with a known user identity * **`consent`** — Record proof of user consent with document references * **`optIn` / `optOut`** — Enable or disable data collection (useful for consent management) For detailed mobile SDK documentation, see the Lytics developer documentation. ### Verification and Testing After installing any SDK, verify that it is working correctly. #### Browser Console Verification (JavaScript Tag) Open your browser's developer console on a page where the tag is installed and run these checks: ```javascript // Check that the tag is loaded jstag.isLoaded // Expected: true // Check the tag version jstag.config.version // Expected: "3.x.x" // Check audience membership jstag.getSegments() // Expected: array of audience slugs // Get the anonymous ID jstag.getid(function(id) { console.log(id); }); // Expected: Lytics _uid value ``` #### Network Verification 1. Open **Developer Tools > Network** tab. 2. Filter requests for `lytics.io`. 3. Look for requests to the `/c` endpoint (data collection) — these confirm events are being sent. 4. Look for requests to the `/personalize` endpoint — these confirm profile data is being retrieved. #### Entity Ready Callback To verify that the full profile (including audience membership and Experiences) is being returned: ```javascript jstag.call('entityReady', function(profile) { console.log('Audiences:', profile.data.user.segments); console.log('Experiences:', profile.data.experiences); }); ``` #### Testing Best Practices * **Use incognito mode** — This clears cookies and caches, giving you a clean anonymous user for each test. * **Document test results** — Record the date, time, and results of each verification check. * **For known users** — Use unique test email addresses. You can leverage email punctuation (e.g., `test+1@example.com`) to create distinct identities. * **For anonymous users** — Retrieve the cookie ID with `jstag.getid(id => console.log(id))` to look up the test profile in the Lytics UI. #### Chrome DevTools Extension Install the **Lytics Dev Tools Extension** from the Chrome Web Store for a visual debugging experience. The extension provides four tabs: Tab What It Shows **Status** Real-time SDK installation and operational status **Debugger** Active configuration, live event monitoring, installation validation **Profile** Current visitor's profile: behavioral scores, custom attributes, audience membership **Personalization** Log of active Lytics Experiences and campaigns evaluated for this visitor ![Lytics Dev Tools Chrome extension side panel showing the Status tab: JavaScript SDK version, Account ID, stream, cookie name, profile key, and last-activity indicator confirming a healthy tag install.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amb3dfba931b26e21d/36a91aac9550bfbd2a94f376/demonstrate_verifying_javascript_tag_installation.png) #### Hosting the Tag Locally (Advanced) In strict security compliance or air-gapped environments, you can host the tag on your own infrastructure: 1. Navigate to **Setup > Website (JS Tag)** and copy the `src` URL. 2. Open the URL in a browser and save the file. 3. Host the file on your web server. 4. Update the `src` parameter in `jstag.init()` to point to your hosted copy. > Hosting the tag locally voids SLAs, requires manual updates for bug fixes, and disables dynamic account settings. Only use this approach when required by compliance. #### Subresource Integrity (SRI) For environments that require SRI verification, you can host the tag files yourself and add integrity attributes. The four files you need to host and verify are: 1. **Core Tag** — `//c.lytics.io/api/tag/{ACCOUNT_ID}/latest.min.js` 2. **Pathfora JS** — `//c.lytics.io/static/pathfora.min.js` 3. **Pathfora CSS** — `//c.lytics.io/static/pathfora.min.css` 4. **Experience Config** — `//c.lytics.io/api/experience/candidate/{ACCOUNT_ID}/config.js` ### Summary The JavaScript Tag (v3) is the primary data collection mechanism for web properties — it tracks behavior, resolves identity, retrieves profile data for personalization, and loads Pathfora for web experiences. Installation is either direct (paste the snippet) or via Google Tag Manager. Account-level tag settings in the Vault control caching, client-side integrations, personalization behavior, and data collection parameters. For mobile apps, native SDKs for iOS, Android, and React Native follow the same pattern: initialize with an API token, then use `track`, `identify`, and `consent` methods. Always verify installation using browser console commands, network inspection, and the Lytics Dev Tools Chrome extension. ### Documentation Links * [JavaScript Tag Overview](https://docs.lytics.com/docs/javascript-tag) * [JavaScript Tag Configuration](https://docs.lytics.com/docs/jstag-configuration) * [iOS SDK](https://docs.lytics.com/docs/sdk-ios) * [Android SDK](https://docs.lytics.com/docs/sdk-android) * [React Native SDK](https://docs.lytics.com/docs/sdk-react-native) * [Chrome DevTools Extension](https://docs.lytics.com/docs/chrome-extension) ## What You've Learned You now know how to configure a Lytics account from scratch. You've walked through the Vault's five top-level areas — Usage, Settings, Users, Security, and Setup — and understand how to configure account details, enforce security policies, manage users with role-based access, create and rotate API tokens, and set up third-party authorizations. You've also installed and configured the JavaScript Tag for web data collection, learned the available mobile SDKs and their shared configuration patterns, and verified that data is flowing correctly using console commands, network inspection, and the Chrome DevTools extension. ### Key Terms > 📘 **Vault** — The centralized account administration area in Lytics where you manage settings, users, security, and SDK setup. > > 📘 **Access Token** — A credential used to authenticate API requests to Lytics. Each token is scoped to specific roles and has a configurable expiration. > > 📘 **Authorization** — A stored credential that grants Lytics permission to exchange data with a third-party service (email provider, ad platform, data warehouse, etc.). > > 📘 **JavaScript Tag (jstag)** — The Lytics client-side SDK for web properties. It tracks user behavior, resolves identity, surfaces profile data for personalization, and loads the Pathfora SDK for web experiences. > > 📘 **Account ID** — The unique identifier for your Lytics account, passed as the `cid` parameter in API calls and embedded in the JavaScript Tag's `src` URL. > > 📘 **Personalization API** — The client-side API that returns the current user's profile data, including audience membership and behavioral scores, for use in personalization logic. > > 📘 **Pathfora** — The Lytics web personalization SDK that evaluates and displays Experiences (modals, bars, slideouts) based on audience membership. **Next step:** Proceed to [Data Flow](/academy/courses/lytics-course/data-flow) to understand how data moves through the platform's collection and processing pipeline. #### Key takeaways - Connect **Account Configuration** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 03 — Data Flow #### Lesson text Everything Lytics knows about your customers starts with data flowing into the platform. Before you can build profiles, create audiences, or activate campaigns, you need to understand how raw events enter the system, how they're organized into streams, and how Lytics interprets that data into profile attributes. This module covers the full data pipeline — from the moment an event arrives through ingestion, stream organization, and schema mapping — so you can make informed decisions about how to structure your data collection and ensure the right information reaches the right profiles. ## Raw Events ### Learning Objectives By the end of this section, you will be able to: \- Describe what a raw event is and identify its key/value structure \- Identify common event types and the data they carry \- Navigate to the Data Streams view and inspect raw event keys ### What is an Event? Every piece of data that enters Lytics arrives as an event — an action or activity performed by a user, such as visiting a webpage, making a purchase, or subscribing to a newsletter. Events are the atomic unit of data in the platform. An event is a flat collection of key/value pairs that describes something that happened at a specific point in time. Here is a typical web page view event sent by the JavaScript Tag: ```json { "_e": "pv", "_uid": "74481.3222228897", "_ts": "1504306728695", "_v": "3.0.2", "url": "www.example.com/pricing", "_ref": "www.google.com", "_device": "desktop", "_sz": "2560x1440", "_ul": "en-US", "_tz": "-7" } ``` Every event contains: \- **Data keys** — The field names (e.g., `_e`, `url`, `_uid`) that describe the event. \- **Data values** — The corresponding values for each key. \- **A timestamp** — When the event occurred (`_ts`) and when Lytics received it. \- **A stream association** — Which data stream the event belongs to (e.g., `default` for JavaScript Tag data). Events are independent — they do not reference each other or assume any ordering. Lytics processes each event individually and uses [Fields and Mappings](#fields-and-mappings) to translate event keys into profile attributes. ### Common Event Types Events fall into several categories based on what they describe. The following tables list the predefined fields that Lytics automatically maps from the `default` web stream. #### Page View Events The JavaScript Tag automatically collects page views. Each page view carries these fields: Field Profile Field Description `_e` — Event type (`pv` = page view) `url` `hashedurls` Current page URL (hashed and counted) `_ref` `refdomain` Referral domain `_device` `devices` Device type (desktop, mobile, tablet) `_sz` — Display size `_ul` — User language `_tz` `timezone` Timezone offset from UTC Over time, page view events aggregate into visit-level profile fields: Profile Field Description `lastvisit_ts` Time of last visit `firstvisit_ts` Time of first visit `visitct` Total number of visits `pageviewct` Total page view count `channels` All channels used `domains` Domains visited `is_mobile` Has accessed mobile web #### Identity Events When you send known user data via `jstag.send()` or an API call, these fields map to the profile: Event Key Profile Field Description `email` `email` Email address `user_id` `user_id` Custom user identifier `name` `name` Full name `first_name` `first_name` First name `last_name` `last_name` Last name `phone` `phone` Phone number `company` `company` Company name `city` `city` City `state` `state` State `country` `country` Country #### Conversion Events When you send an event with `event: "conversion"`, Lytics maps these standard conversion fields: Profile Field Description `cvt_last_time` Most recent conversion time `cvt_first_time` Oldest conversion time `cvt_last_campaign` Most recent campaign attributed to conversion `cvt_campaigns` All campaigns converted from `cvt_value` Most recent conversion value `cvt_currency` Most recent currency used `cvt_history` Conversion values by campaign ```javascript jstag.send({ event: "conversion", campaign_id: "spring_promo", variation_id: "hero_banner_a", currency: "USD", value: 49.99 }); ``` #### UTM Campaign Events Google UTM parameters are automatically captured from the URL and mapped to profile fields: Profile Field Description `utm_campaign` UTM campaign referred by `utm_source` UTM source referred by `utm_medium` UTM medium referred by `utm_content` UTM content referred by `utm_campaign_last` Last UTM campaign `utm_source_last` Last UTM source `utm_medium_last` Last UTM medium #### Form Submission Events When you send form data with a `form_name` key and fields prefixed with `formdata_`, Lytics maps: Profile Field Description `last_form_submitted_by_date` Last time a web form was submitted `form_submitted` Web forms submitted `form_data` Web form data collected ### Exploring Events in the UI You view raw events by navigating to **Conductor > Pipeline > Streams** (`/conductor/pipeline/streams`). Select a stream from the dropdown to see its events. #### The Raw Keys Table Below the event ingress graph, the raw keys table shows every unique key observed on the stream: Column Description **Name** The key name as it appears in the event **Predicted Type** Data type inferred by sampling values **First Seen** Date the key first appeared **Last Seen** Date the key was last observed **Times Seen** Number of events containing this key **Unique Values** Number of distinct values observed **Times Used** Number of user fields mapped to this key Click any key to see a sample of its values — useful for verifying that data matches your expectations. The table supports four filters: Filter Shows **Used** Keys mapped to at least one user field **Unused** Keys collected but not mapped to any field **Common** Keys that appear frequently relative to others **Uncommon** Keys that appear infrequently > Keys comprising less than 0.1% of a stream's volume or not seen in 7 days are automatically hidden to reduce clutter. You can hide additional keys manually, but unhiding requires the API — keep a record of hidden keys. ![Navigate to Conductor > Pipeline > Streams, select a stream, explore the event ingress graph, and walk through the raw keys table including filters (Used, Unused, Common, Uncommon) and clicking a key to sample values.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am48f6d6deba9bcaae/4a2f13207055356b65c4d75d/navigate_conductor_pipeline_streams_select.gif) ### Summary Every piece of data in Lytics arrives as a flat key/value event with a timestamp and stream association. The platform automatically maps common event types — page views, identity, conversions, UTM parameters, and form submissions — into profile fields. The Data Streams view in Conductor lets you inspect raw keys, check mapping status, and sample actual values to verify data is arriving as expected. ### Documentation Links * [Data Streams](https://docs.lytics.com/docs/data-streams-1) * [Data Collection & Onboarding](https://docs.lytics.com/docs/data-collection-onboarding) ## Ingestion Methods ### Learning Objectives By the end of this section, you will be able to: \- List all available data ingestion methods and their characteristics \- Choose the right ingestion method for a given data source and use case \- Explain the difference between real-time and batch ingestion Lytics accepts data through multiple ingestion paths. The method you choose depends on the data source, the volume of data, and whether you need real-time or batch processing. ### JavaScript Tag The JavaScript Tag is the primary method for collecting web behavioral data. Once installed on your site, it automatically sends page views and any custom events you configure to the `default` stream (unless you specify a different stream). ```javascript jstag.send({ email: "user@example.com", first_name: "Jane", last_name: "Doe" }); ``` **Best for:** Real-time web behavioral data, client-side identity resolution, page view tracking. For installation and configuration details, see [Account Configuration — SDKs](/academy/courses/lytics-course/account-configuration#sdks). ### Image Pixel When the JavaScript Tag cannot be installed (email messages, online ads), the Image Pixel provides an alternative. It sends event data as query parameters on an image URL that fires on load: ```html ``` The pixel URL contains three components: 1\. **Account ID** — Your Lytics account identifier 2\. **Stream name** — The target data stream (e.g., `default`) 3\. **Query parameters** — Event data as key/value pairs **Best for:** Email open tracking, ad impression tracking, environments where JavaScript is unavailable. ### Collection API The Collection API (`https://c.lytics.io/c/{ACCOUNT_ID}/{STREAM}`) accepts real-time event data via HTTP requests. Use this for server-side event tracking when the JavaScript Tag is not applicable. Events are sent as JSON: ```json [ {"event": "purchase", "email": "user@example.com", "value": 29.99}, {"event": "login", "email": "user@example.com"} ] ``` **Best for:** Server-side events, backend systems, real-time data from custom applications. ### Bulk API and File Imports For large volumes of offline or historical data, Lytics provides the Bulk API (`https://bulk.lytics.io/collect/bulk/{STREAM}`) and file-based import via SFTP and Amazon S3. #### Bulk API Upload CSV or newline-delimited JSON files directly: ```bash curl -s -H "Authorization: $LIOKEY" \ -H 'Content-type: application/csv' \ --data-binary @customer_data.csv \ "https://bulk.lytics.io/collect/bulk/crm_import" ``` #### File Imports (SFTP / S3) Lytics can pull files from SFTP or S3 on a schedule. Key requirements: * **File naming** — Use consistent naming with a time-based suffix (e.g., `crm_data_20240115.csv` or `crm_data_1705305600.csv`). Lytics matches files by root filename and uses the modified timestamp to determine import order. * **Compression** — Files may be zip-compressed; Lytics decompresses automatically. * **Timestamps** — Individual records should include a timestamp in `YYYY-MM-DDTHH:MM:S` format. If omitted, Lytics timestamps records on ingestion. * **JSON format** — For bulk imports, use newline-delimited JSON (one object per line): ```json {"event":"register","email":"user1@example.com","date":"2024-01-15"} {"event":"purchase","email":"user2@example.com","date":"2024-01-15","value":59.99} ``` **Best for:** CRM data, historical backfills, data warehouse exports, large offline datasets. ### Third-Party Integrations Lytics provides hundreds of out-of-the-box integrations for importing data from email service providers, advertising platforms, CRM systems, and more. Each integration creates its own data stream(s) — for example, an email integration typically creates both a user stream (subscriber attributes) and an activity stream (opens, clicks, bounces). You configure integrations through **Authorizations** (credentials) and **Jobs** (import/export tasks). For details, see [Account Configuration — Authorizations](/academy/courses/lytics-course/account-configuration#authorizations). **Best for:** Automated ongoing data sync from supported third-party tools. ### Cloud Connect Cloud Connect lets you run SQL queries directly against your data warehouse and stream the results into Lytics as profile attributes and audiences. It integrates with: \- Google BigQuery \- Amazon Redshift \- Microsoft Azure \- Snowflake \- Databricks Rather than moving data out of your warehouse, you write standard SQL to extract the attributes you need, and Cloud Connect streams the results into materialized user profiles. Common use cases include: * **Time-window queries** — All users who did not log in last month * **Join-based queries (B2B)** — All users associated with accounts missing a specific feature * **Rollup queries** — All users with a premium subscription who purchased at least two products **Best for:** Complex aggregations, data already in a warehouse, maintaining the warehouse as source of truth. > Don't have a warehouse? Lytics provides **Lytics Warehouse** (powered by Google BigQuery) to all customers as part of Conductor. Contact your account manager for access. ### Mobile SDKs The iOS, Android, and React Native SDKs collect behavioral data from mobile applications. They follow the same pattern as the JavaScript Tag: initialize with your API token, then use `track`, `identify`, and `consent` methods. **Best for:** Native mobile app behavioral data, in-app identity resolution. For SDK configuration details, see [Account Configuration — Mobile SDKs](/academy/courses/lytics-course/account-configuration#mobile-sdks). ### Webhooks Lytics supports inbound webhooks as a flexible option for receiving data from any system that can make HTTP requests. Lytics also supports outbound webhooks for triggered delivery of audience membership changes (enters and exits) to a destination URL. **Best for:** Event-driven integrations, custom applications, systems without a dedicated Lytics integration. ### Choosing the Right Method Method Latency Volume Complexity When to Use **JavaScript Tag** Real-time Medium Low Web behavioral data, anonymous/known user tracking **Image Pixel** Real-time Low Low Email, ads, no-JavaScript environments **Collection API** Real-time Medium Medium Server-side events, backend systems **Bulk API / File Imports** Batch High Medium CRM imports, historical backfills, offline data **Third-Party Integrations** Varies Varies Low Supported platforms with OOTB connectors **Cloud Connect** Batch (scheduled) High Medium Warehouse data, complex SQL aggregations **Mobile SDKs** Real-time Medium Medium Native mobile app data **Webhooks** Real-time Low Medium Custom integrations, event-driven systems ### Summary Lytics offers multiple ingestion paths, each suited to different data sources and latency requirements. Real-time methods (JavaScript Tag, Image Pixel, Collection API, Mobile SDKs, Webhooks) are best for behavioral and event-driven data. Batch methods (Bulk API, File Imports, Cloud Connect) handle large offline datasets, historical backfills, and warehouse-based aggregations. Third-party integrations provide automated sync with supported platforms, each creating its own data streams. The right choice depends on the source, volume, and whether you need real-time or scheduled processing. ### Documentation Links * [Data Collection & Onboarding](https://docs.lytics.com/docs/data-collection-onboarding) * [Streams API](https://docs.lytics.com/docs/streams-api) * [Stream Routing API](https://docs.lytics.com/docs/stream-routing-api) * [What is Cloud Connect?](https://docs.lytics.com/docs/cloud-connect-intro) ## Structuring Streams ### Learning Objectives By the end of this section, you will be able to: \- Explain what streams are and why logical separation matters \- Configure stream settings including slug, channel, and metadata \- Use stream route rules to split or filter event data \- Monitor stream health using the event ingress graph and raw keys table ### What is a Stream? Streams are how Lytics organizes incoming events into logical groupings — each stream represents a continuous flow of events from a specific source or type, providing logical separation of data within the platform. Each stream represents a distinct data source or data type. For example: * `default` — Web behavioral data from the JavaScript Tag * `crm_users` — Customer records from your CRM system * `email_activity` — Email engagement data (opens, clicks, bounces) * `email_users` — Email subscriber attributes * `purchase_history` — Transaction data from your e-commerce system This separation matters because streams define where mappings apply. A mapping that transforms `email_address` into the `email` profile field can be scoped to a specific stream, ensuring that data from different sources is processed with the right transformation logic. > Many integrations create multiple streams automatically. For example, an email integration typically produces a user stream (subscriber attributes) and an activity stream (opens, clicks). Integration streams are prefixed to identify their source. ### Creating and Configuring Streams Streams are created automatically when data arrives on a new stream name, or you can create them explicitly via the API. #### Stream Parameters Parameter Type Required Description `slug` string Yes Raw identifier for the stream, used in queries and the collection API URL `channel` string Yes Data collection method: `web`, `email`, `mobile`, `ad`, `sms`, `pos` `label` string No User-friendly name displayed in the UI `description` string No Additional context about the stream's purpose `method` string No `bulk` or `streaming` — indicates the ingestion pattern `providers` string\[\] No Names of providers sending data to this stream `hidden` boolean No Whether to hide the stream from the stream stats view #### Stream Naming Best Practices * **Use descriptive slugs** — Name streams after the source and data type (e.g., `salesforce_contacts`, `shopify_orders`). * **Separate attributes from activity** — Keep user attribute data (who someone is) on a different stream from activity data (what someone did). This distinction simplifies mapping. * **Prefix integration streams** — When using data routers like Segment or Rudderstack that combine multiple sources, use prefixes to maintain logical separation (e.g., `segment_web`, `segment_mobile`). * **Keep it consistent** — Establish a naming convention (e.g., `{source}_{type}`) and apply it across all streams. ### Monitoring Streams Navigate to **Conductor > Pipeline > Streams** to monitor your data streams. #### Event Ingress Graph The graph shows the number of events collected on a stream over a configurable time period (past day, week, month, 3 months, or year) and interval (hourly, daily, weekly, monthly). Above the graph, you see: * **Last message received** — The most recent event timestamp * **Source** — The data source for the stream * **Number of fields** — Count of raw keys in the stream > The "last message received" timestamp strives for real-time accuracy but may lag during bulk imports. #### Raw Keys Table Below the graph, the [raw keys table](#the-raw-keys-table) shows every unique key observed on the selected stream. Use it to verify that data is arriving as expected, check whether keys are mapped to user fields, and sample actual values. ### Stream Route Rules Route rules — configurations that redirect events from one stream to another based on an expression, or ignore specific subsets of events — let you reshape your stream structure without modifying the data source. Two common use cases: 1. **Split a monolithic stream** — Route events from a single `customer_activity` stream into separate streams for `web_activity`, `email_activity`, and `transactions` based on event content. 2. **Filter unwanted data** — Ignore all events from `localhost` during development by routing them to a divert stream. #### Route Rule Properties Property Type Description `name` string Descriptive name for the rule `active` boolean Whether the rule is currently evaluating events `priority` integer Evaluation order (higher priority first) `expression` string Logic condition to evaluate (use `"true"` to route all events) `input` string Source stream `output` string Destination stream #### Example: Filtering Localhost Events ```json { "active": true, "expression": "contains(`_url`, \"localhost\")", "input": "default", "name": "Ignore events from localhost", "output": "default_divert", "priority": 1 } ``` This rule matches any event on the `default` stream where the URL contains "localhost" and reroutes it to `default_divert`, keeping your production stream clean. > Route rules are cached and take up to **10 minutes** to take effect after creation or modification. #### Route Rule Behavior * **Exported data** — When raw activity data is exported, routed events are associated with the **output** stream only, not the input stream. * **Behavioral scoring** — If you enable behavioral scoring on a stream, target the **output** stream (the stream that receives the routed data), not the input stream. ![Conductor > Pipeline > Streams view showing the event ingress graph, stream metadata, and raw keys table for a sample stream.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amf3347ed3e5011834/6ef3dfbc1eec214ebb96f8da/conductor_pipeline_streams_view_event.png) ### Summary Streams provide logical separation of incoming data by source and type. Each stream has a slug, channel, and optional metadata, and serves as the scope for field mappings. Descriptive naming conventions (e.g., `{source}_{type}`) and separating attributes from activity data keep your stream structure manageable. Route rules let you split monolithic streams or filter unwanted events without modifying the data source. Monitor stream health through the event ingress graph and raw keys table in Conductor. ### Documentation Links * [Data Streams](https://docs.lytics.com/docs/data-streams-1) * [Stream Routing API](https://docs.lytics.com/docs/stream-routing-api) ## Schema on Read ### Learning Objectives By the end of this section, you will be able to: \- Explain the difference between schema-on-read and schema-on-write approaches \- Describe how fields and mappings translate raw events into profile attributes \- Identify merge operators and when to use each one \- Understand schema versioning, auditing, and governance tools ### How Schema on Read Works In a traditional data system, you define a rigid schema before you can ingest data — if the data does not match the schema, it is rejected. This is **schema on write**. Lytics uses a **schema on read** approach: you send any key/value pairs you want, and Lytics stores the raw event data regardless of whether it matches a predefined structure. You then define **fields** and **mappings** that tell Lytics how to interpret and transform that raw data into profile attributes. This interpretation happens when data is processed through the pipeline, not when it arrives. The flow works like this: 1. **Raw event arrives** on a data stream with arbitrary key/value pairs. 2. **Lytics stores the raw event** in its entirety — nothing is dropped. 3. **Mappings evaluate** — each mapping expression checks whether its conditions are met and transforms the data accordingly. 4. **Fields receive values** — the transformed data is written to profile fields using the field's merge operator to resolve conflicts with existing data. 5. **The profile materializes** — the unified profile reflects all mapped data from all streams. > Any key/value pair can be sent to Lytics. However, only data that has been mapped to user fields is available for use in audiences and segmentation. Unmapped data is still stored and can be mapped later without re-ingestion. #### Benefits * **Start collecting immediately** — You do not need to design a schema before sending data. Begin collecting events and define mappings as your understanding of the data evolves. * **Iterate without re-ingestion** — Add new mappings at any time to surface previously unmapped data. The raw events are already stored. * **Handle diverse sources gracefully** — Different data sources can send different key names for the same concept (e.g., `email_address` from one source, `EmailAddress` from another). Mappings normalize these into a single profile field. * **Evolve without migration** — As business requirements change, add or modify mappings without downtime or data migration. #### Trade-offs * **Unmapped data is invisible to segmentation** — If you forget to map a key, the data exists in raw storage but cannot be used in audiences until mapped. * **Governance requires discipline** — Without upfront schema constraints, it is possible to create redundant or conflicting mappings. Use the Schema Audit to monitor field health. * **Mappings apply forward only** — When you publish a new mapping, it applies to events processed from that point forward, not retroactively to historical data already on profiles. > It is important to have fields and mappings in place before data is ingested on a stream. While data will still be stored, the initial processing pass will not apply mappings that do not yet exist. ### Fields and Mappings A field is a named attribute on the user profile with a defined data type, merge operator, and optional retention policy — fields are the building blocks of the profile schema. A mapping is an expression that transforms raw event data into a profile field value, scoped to a specific stream and optionally gated by conditions. #### Creating a Field Navigate to **Schema > Fields** and click **\+ Create New**. Each field has these properties: Property Description **ID** Alphanumeric key defining how the field is stored on the profile **Short Description** User-friendly label shown throughout the UI **Data Type** The type of data stored (see table below) **Merge Operator** How conflicting values are resolved (see [Merge Operators](#merge-operators)) **Identity Key** Whether this field links events from different sources (true/false) **Keep Days** Number of days to retain values (0 = unlimited) **Capacity** Maximum number of values in set/map fields (0 = unlimited) **PII Key** Whether the field contains personally identifiable information **Categories** Optional classification: Identity, Governance, Interests, Behavior, First Party, Intelligence, Activation #### Data Types **Standard types:** Type Description `string` Sequence of characters, no length limitation `integer` Whole numbers (positive or negative), 64-bit `number` Decimal numbers (positive or negative), 64-bit `boolean` True or false `date` Datetime value **Advanced types:** Type Description `[]string` Array of unique string values `[]time` Array of unique datetime values `ts[]string` Time-ordered unique array of strings `map[string]datatype` Key/value pairs where the key is a unique string and the value is one of: `string`, `int`, `number`, `bool`, `time` #### Creating a Mapping Navigate to **Schema > Mappings** and click **\+ Create New**. Each mapping requires: Property Required Description **Stream** Yes The stream this mapping applies to **Expression** Yes The transformation rule to apply **Condition** No A logical expression that must be true for the mapping to execute #### Mapping Expression Examples Given this incoming event: ```json { "email_address": "hello@lytics.com", "_uid": "123e4567-e89b-12d3-a456-426614174000", "utm_campaign": "exciting_campaign", "url": "www.lytics.com/get-started", "event_type": "page-view" } ``` You could define these mappings: Expression What It Does `email_address` Takes the value as-is (no transformation) `email(email_address)` Validates that the email is syntactically correct before storing `email(oneof(email_address, EmailAddress))` Coalesces two possible key names and validates the result `count(event_type) IF event_type == "page-view"` Increments a counter only when the event type is `page-view` Lytics provides a comprehensive library of mapping functions including string manipulation, hashing, date/time parsing, URL extraction, aggregation (count, sum, min, max, set), and conditional logic. For the full function reference, see [Schema](/academy/courses/lytics-course/schema). ### Merge Operators When multiple events map data to the same profile field, the merge operator determines how the values are combined: Operator Behavior Use When **Latest** Keep the value with the most recent timestamp You want the current state (e.g., current email, current city) **Oldest** Keep the value with the oldest timestamp You want the original value (e.g., signup date, first purchase) **Minimum** Keep the smallest value You want the floor (e.g., lowest price seen) **Maximum** Keep the largest value You want the ceiling (e.g., highest order value) **Sum** Add numeric values together You want a running total (e.g., lifetime spend) **Merge** Take the union of two sets You want all values (e.g., all products purchased, all pages viewed) Choosing the right merge operator is critical for data accuracy. A field tracking `first_purchase_date` should use **Oldest** so that earlier values are never overwritten. A field tracking `total_spend` should use **Sum** so that each new purchase adds to the running total. ### Schema Governance Lytics provides several tools to maintain schema quality as your data sources grow. #### Schema Versions Changes to fields and mappings are not applied immediately. Instead, they accumulate as an unpublished draft. You review and publish changes from **Schema > Versions**: 1. Navigate to **Schema > Versions** to review unpublished changes. 2. Click **Publish Changes** and review the full list of field, mapping, and ranking modifications. 3. Provide a description for the version. 4. Publish. To undo a change, you can **Discard Changes** (resets to the last published version) or **Revert to Schema** (rolls back to a specific previous version by creating a new unpublished draft). > Mappings only apply to data processed after the version is published. They do not retroactively reprocess historical events. #### Schema Audit Navigate to **Data > Schema Audit** to review the health of your schema. The audit provides: * **Field coverage** — What percentage of defined fields are actively receiving data * **Field utilization** — What percentage of fields are used in audience definitions * **Multi-source fields** — What percentage of fields merge data from multiple streams * **Data type distribution** — Breakdown of field types (note: `map` types are more expensive and should be used deliberately) Each field row shows its ID, name, data type, source streams, population count (users with the field), approximate cardinality, and audience usage count. #### Schema Copilot Schema Copilot uses AI to analyze new data sources and suggest fields and mappings. Provide a JSON or CSV sample, select the target stream, and Copilot generates a suggested schema that you can review and edit before publishing. This is particularly useful when onboarding a new data source — rather than manually inspecting every key and writing mappings, Copilot provides an informed starting point. ![Walk through creating a field and mapping: navigate to Schema > Fields, create a new field with data type and merge operator, then navigate to Schema > Mappings, create a mapping with an expression and condition, publish the schema version, and check the Schema Audit for field health.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ama2c0a623318abc00/3203ffcfdfdbc092f44bbbfd/walk_creating_field_mapping_navigate.gif) ### Summary Lytics uses a schema-on-read approach: raw events are stored in full regardless of structure, and fields and mappings define how that data is interpreted into profile attributes. Fields have a data type, merge operator (Latest, Oldest, Sum, etc.), and optional retention policy. Mappings are scoped to a stream and can include transformation functions and conditions. Schema changes accumulate as unpublished drafts and must be published to take effect — and they apply forward only, not retroactively. The Schema Audit and Schema Copilot help maintain quality as your data sources grow. ### Documentation Links * [Schema Overview](https://docs.lytics.com/docs/schema) * [Fields and Mappings](https://docs.lytics.com/docs/fields-and-mappings) * [Merge Operators](https://docs.lytics.com/docs/merge-operators) * [Schema Audit](https://docs.lytics.com/docs/schema-audit) ## What You've Learned You now understand the full path data takes through Lytics — from raw events arriving via multiple ingestion methods, through stream organization and schema-on-read interpretation, to materialized profile attributes. You've seen how events are structured as flat key/value pairs, how the platform offers real-time and batch ingestion options for different data sources, how streams provide logical separation that scopes your mappings, and how fields and merge operators control exactly how incoming data shapes unified profiles. With this foundation, you're ready to explore the profile itself and see what all this data produces. ### Key Terms > 📘 **Event** — An action or activity performed by a user (e.g., page view, purchase, form submission). Events are the atomic unit of data in Lytics, structured as flat key/value pairs with a timestamp and stream association. > > 📘 **Data Stream** — A continuous flow of events from a specific source or type, providing logical separation of data within Lytics. Streams scope where mappings apply. > > 📘 **Field** — A named attribute on the user profile with a defined data type, merge operator, and optional retention policy. Fields are the building blocks of the profile schema. > > 📘 **Mapping** — An expression that transforms raw event data into a profile field value. Mappings are scoped to a specific stream and can include conditions and transformation functions. > > 📘 **Merge Operator** — The rule that determines how conflicting values are combined when multiple events map to the same profile field (e.g., Latest, Oldest, Sum, Merge). > > 📘 **Schema on Read** — Lytics' approach to data interpretation: raw events are stored in full regardless of structure, and fields/mappings define how that data is translated into profile attributes at processing time. > > 📘 **Route Rule** — A configuration that redirects events from one stream to another based on an expression, or ignores specific subsets of events. > > 📘 **Cloud Connect** — A feature that lets you run SQL queries directly against your data warehouse and stream the results into Lytics as profile attributes and audiences. > > 📘 **Schema Copilot** — An AI tool that analyzes new data sources and suggests fields and mappings, providing an informed starting point for schema configuration. **Next step:** Proceed to [Profile](/academy/courses/lytics-course/profile) to learn the structure of unified profiles and what all this collected data produces. #### Key takeaways - Connect **Data Flow** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 04 — Profile #### Lesson text The profile is the central object in Lytics — every audience, personalization rule, export, and predictive model operates on profiles. Before you can build audiences or activate data, you need to understand how profiles are constructed from events, what fields exist on them by default, how identity rules connect data from different sources into a single record, and how to extend profiles with custom fields. This module gives you that foundation: navigating profiles in the UI, reading the schema layers, configuring custom fields, and using the Identity Explorer to inspect and debug individual profiles. ## Overview and Navigation ### Learning Objectives By the end of this section, you will be able to: * Define what a Lytics profile is and explain how it is constructed from events * Navigate to an individual profile using two different paths in the UI * Identify the three primary tabs of the profile view and what each contains ### What Is a Lytics Profile? A profile — also referred to as an entity — is the unified representation of a single individual in Lytics, constructed from all known events and attributes across every connected data source. Every event that enters the platform — a page view, an email open, a purchase, a form submission — is identity-resolved and merged into a profile. The result is a continuously updated record that reflects everything Lytics knows about one individual, whether they are anonymous or identified. A profile is not a static export. It updates in real time as new events arrive and as Lytics recomputes behavioral models. Everything Lytics does — audience segmentation, web personalization, predictive modeling, export jobs — operates on profiles. #### How a Profile Is Built Profiles are the output of two parallel processes that run every time an event arrives: 1. **Identity Resolution** — Lytics examines the identifiers in the event (email, cookie, customer ID) and determines which profile this event belongs to. If the event introduces a new identifier that connects two previously separate profiles, those profiles are merged. For the full identity resolution model, see [Identity Resolution](/academy/courses/lytics-course/id-resolution). 2. **Profile Materialization** — Once identity is resolved, Lytics applies the schema's field mappings to the event data and updates the matching profile fields. Merge operators control how conflicting values are reconciled when data from different streams disagrees. For schema and merge operator configuration, see [Schema](/academy/courses/lytics-course/schema). The result: every profile represents the most current, most complete view of that individual, built automatically from every source you've connected. ### Finding a Profile in the UI There are two paths to look up an individual profile. #### Path 1: Building Profiles > Search 1. In the left navigation, expand **Building Profiles**. 2. Select **Search**. 3. In the search box, select the identifier type from the dropdown (default is **Email**) and enter the value. 4. Click the matching result to open the profile. This path opens the Identity Explorer — the full profile examination interface covered in [Anatomy of a Profile](#anatomy-of-a-profile). #### Path 2: Using Profiles > Audiences > Find a User 1. In the left navigation, expand **Using Profiles**. 2. Select **Audiences**. 3. In the expanded menu, select **Find a User**. 4. Select the identifier field from the dropdown and enter the value. > If a search returns multiple profiles for a single identifier, identity fragments have not yet merged — or your identity resolution strategy has a gap. Contact Lytics support if you see this consistently. ![Building Profiles > Search interface showing the identifier type dropdown and search results for an example profile.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am4e06b256981c76f3/8626dfca2adacc4b88db470f/building_profiles_search_interface_identifier.png) ### The Profile View: Three Tabs When you open a profile from the standard view (not the Identity Explorer), it is organized into three tabs: Tab What It Contains **Intelligence** Behavioral scores, content affinity, recent activity by channel, event heatmap, and unique identifiers **Audiences** All current audience memberships for this profile, with audience sizes **Details** Raw field values from every data source — each value shows the contributing stream Use the **Intelligence** tab to assess a user's engagement state at a glance. Use the **Details** tab to verify what data is on the profile and which stream provided it. Use the **Audiences** tab to confirm that a profile is resolving into the correct segments. > The **Details** tab is your primary debugging tool. When a profile isn't behaving as expected in an audience or personalization rule, start here — verify the raw field values before investigating schema or audience logic. ![Profile view showing the Intelligence tab with behavioral scores, content affinity, and event heatmap for a sample profile.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amba41acc1cca88a91/3b364f05b4b660edbb4db99c/profile_view_intelligence_tab_behavioral.png) ### Summary A profile is a real-time, unified view of a single individual, built automatically from events across all connected data sources through identity resolution and schema mappings. You can look up profiles through two paths: **Building Profiles > Search** (which opens the Identity Explorer) or **Using Profiles > Audiences > Find a User**. The standard profile view organizes data into three tabs — Intelligence for behavioral scores and engagement signals, Audiences for current segment memberships, and Details for raw field values with source attribution. If a search returns multiple profiles for a single identifier, that indicates an identity resolution gap. ### Documentation Links * [User Profiles](https://docs.lytics.com/docs/user-profiles) * [Profile Search](https://docs.lytics.com/docs/profile-search) ## Common Schema ### Learning Objectives By the end of this section, you will be able to: * Distinguish between the universal schema and the common schema * Name the key field categories in the universal schema and explain their purpose * Identify which common schema fields are automatically populated from managed integrations ### Two Schema Layers on Every Profile Every Lytics profile has access to two schema layers: the **universal schema** and the **common schema**. Neither requires manual configuration — they are automatically populated as data flows in and as Lytics runs its models. The universal schema is a set of computed, intelligent attributes applied to every profile in Lytics, regardless of data source, age, or whether the profile is anonymous or known. The common schema is a set of standard profile attributes that provide consistency across integrations — common fields normalize source-specific field names into a single canonical representation. ### Universal Schema Fields The universal schema is divided into five categories. #### Identifiers These fields link events from different sources to the same profile. Field Description Example `_id` Lytics-assigned unique profile ID `"4fafb5b3-b199-58f2-a68b-4b266b363dd1"` `_uids` All web cookie IDs associated with this profile `["50b772f5-a0be-42f2-8828-84b8db5d5a23"]` `email` Email address (auto-standardized to lowercase) `"test@lytics.com"` `email_sha256` SHA-256 hash of the email — auto-computed when an email is present `"e43763..."` `external_id` Custom first-party ID for linking to your proprietary systems `"abc123"` #### Metafields Metafields are system-level attributes that describe the health and breadth of the profile itself. Field Description Example `_created` Timestamp when the profile was first created `"2024-02-28T02:45:51Z"` `_modified` Timestamp of the last profile modification `"2024-02-28T02:45:51Z"` `_last_scored` Timestamp of the last behavioral scoring run `"2024-02-28T02:45:51Z"` `_num_events` Total number of events processed for this profile `81` `_num_days` Distinct days with recorded activity `3` `_num_streams` Number of distinct data streams contributing data `2` `_streamnames` Names of contributing streams `["default"]` `_num_aliases` Number of identity aliases, as calculated by identity resolution `5` Use metafields to assess profile quality. A profile with high `_num_events` and `_num_streams` is well-populated across multiple sources. A profile with `_num_events: 1` and `_num_streams: 1` may be a thin or unstitched fragment. #### Behavioral Scores Lytics automatically computes nine behavioral scores for every profile. Each score is a 0–100 value relative to other profiles in your account — not an absolute measure. Field What It Measures `score_quantity` Cumulative volume of activity over the profile's lifetime `score_frequency` How often the user interacts, relative to your most frequent users `score_recency` How recently the user was active, measured over a 1-year window `score_intensity` Depth of a typical session — not just how often, but how much per visit `score_momentum` Rate of change in engagement frequency — rising vs. declining `score_propensity` Likelihood to re-engage with more activity `score_consistency` Long-term regularity of daily engagement patterns `score_maturity` Length of the user's history, relative to your most mature users `score_volatility` Degree of variation in session depth over time > **Practical use:** `score_momentum` is one of the most actionable signals for timely intervention. A user with sharply rising momentum is in an active engagement cycle — an ideal moment for a conversion offer. A user with falling momentum is disengaging — an ideal trigger for a re-engagement campaign. #### Interests Field Description Example `lytics_content` Topic-level interest scores derived from engagement with classified content `{"Cloud Infrastructure": 0.82, "DevOps": 0.65}` `hashedurls` Map of hashed URLs the user has visited — feeds Lytics' interest engine `{"4058474390481920149": 5}` `lytics_content` is the primary surface for content affinity in audiences and personalization. The values represent affinity strength, not raw visit counts. For more on how content is classified and how affinity is computed, see [Content](/academy/courses/lytics-course/content). #### Intelligence Field Description Example `_segments` Current audience memberships `["all", "anonymous_profiles", "power_users"]` `_split` Randomly assigned 0–99 value for A/B testing and experiments `44` `_split2` Second random split — enables targeting down to 0.01% of profiles `77` `segment_prediction` Scores from active Lookalike Models (0–1 range) `{"likely_to_churn": 0.47}` `segment_prediction_percentile` Percentile ranking from Lookalike Models `{"likely_to_churn": 91}` `_split` enables true randomized audiences without any behavioral conditions. An audience where `_split < 50` gives you a stable, random 50% of profiles — essential for holdout groups and controlled experiments. `_split` and `_split2` together enable targeting down to 0.01% of your profile population. ### Common Schema Fields Common schema fields cover standard profile attributes — personal details and contact information — normalized from whatever field names your source systems use. #### Details Field Description Example `first_name` First name `"Jane"` `last_name` Last name `"Doe"` `name` Full name — included on every account by default `"Jane Doe"` `phone` Phone number, auto-formatted to E.164 `"+15555555555"` `phone_mobile` Mobile number, auto-formatted to E.164 `"+15555555555"` `address1` First line of address `"30 Rockefeller Plaza"` `address2` Second line of address `"Suite 1000"` `city` City `"New York"` `region` State or province `"NY"` `country` Country `"USA"` `postal_code` Postal code `"10112"` `birthday` Birthday or date of birth `"July 22"` or `"2000-07-22"` `status` Generic customer status `"active"` #### Pre-Defined Mappings from Integrations When you add a managed integration via **Data Pipeline > Jobs**, Lytics automatically creates common schema field mappings for that source. You don't define these manually — they are part of the integration's default configuration. For example: \- Adding a **Shopify** import job creates `purchase_total` and related commerce fields, mapping Shopify's order data to them automatically. \- Adding a **Salesforce** import job creates CRM fields mapped from Salesforce's contact schema. This means you can connect a source and immediately use standard profile attributes in audiences and personalization rules, without writing LQL mapping queries. For data outside the common schema, see [Customization](#customization). ### Summary Every profile has two schema layers that require no manual configuration. The universal schema provides computed intelligence — identifiers, metafields, nine behavioral scores, content interest scores, and audience/model membership — on every profile regardless of data source. The common schema normalizes standard attributes like name, email, phone, and address from whatever field names your source systems use. When you add a managed integration, Lytics automatically creates common schema mappings for that source, so standard fields populate immediately. ### Documentation Links * [User Schema](https://docs.lytics.com/docs/schema) * [Behavioral Scoring](https://docs.lytics.com/docs/behavioral-scoring) * [Common Schema Fields](https://docs.lytics.com/docs/common-schema) ## Identity Rules ### Learning Objectives By the end of this section, you will be able to: * Navigate to the Identity Rules view and interpret its visualizations * Explain the role identity rules play in connecting events to profiles * Identify signs of a healthy vs. problematic identity resolution configuration ### What Identity Rules Do Every event that arrives in Lytics carries one or more identifiers: a cookie ID, an email address, a customer ID. Identity rules define which of those identifiers Lytics should use to stitch events together into profiles — and how to resolve conflicts when identifiers from different sources appear to disagree. Without identity rules, Lytics would have no way to know that the anonymous web visitor with cookie `50b772f5` is the same person as the email subscriber `jane@example.com`. Identity rules are what enable that connection. The mechanics of identity graphs — traversals, neighbors, fragment stitching, graph compaction — are covered in depth in [Identity Resolution](/academy/courses/lytics-course/id-resolution). This section focuses on the operational view: how to see your identity rules and evaluate their health in the UI. ### Navigating to Identity Rules 1. In the left navigation, expand **Building Profiles**. 2. Select **Identity**. 3. Select **Rules** from the submenu. The Identity Rules view renders a visualization of how your configured identity keys relate to your data streams. Each node in the graph represents a data stream; the connections show which identity keys are shared across streams and therefore which streams can stitch profiles together. > This visualization answers a critical implementation question: "Which of my data sources can actually connect a user's web behavior to their CRM record?" If two streams share no identity keys, events from those streams can never stitch into the same profile. ![Identity Rules visualization showing multiple streams connected through shared identity keys, with at least one isolated stream node for contrast.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am93d805b00d6ea64d/5483a94e95031405194b97ef/identity_rules_visualization_multiple_streams.png) ### Reading the Visualization A healthy identity configuration shows: * **Multiple streams connected through shared identity keys** — for example, your web stream (cookie-based) connected to your email stream (email-based) through a stitching event that captures both identifiers. * **No isolated stream nodes** — an isolated stream means data from that source can never be associated with a profile from any other source. When you see a stream with no connections, that means either: the stream intentionally produces anonymous or isolated events (acceptable for some data sources), or the stream is missing the identity key needed to stitch with other streams (a gap to fix). ### Identity Rule Configuration Identity rules are configured across two areas: * **Which fields are identity keys** — set per field in **Building Profiles > Schema > Fields**. The `Identity Key: true` flag marks a field as a key for profile stitching. * **Identity key rankings** — in the event of a stitching conflict, higher-ranked keys win. View and adjust rankings in **Building Profiles > Schema > Ranks**. Email is typically ranked higher than cookie identifiers, because a single email represents a more reliable and stable person-identifier than a browser cookie. > Before adjusting identity key rankings or adding new identity keys to a live stream, consult with your implementation team. Changing identity rules on a live account can trigger profile merges or splits that affect every downstream audience and export. ### Summary Identity rules define which event fields Lytics uses to stitch data from different streams into a single profile. The Identity Rules visualization in **Building Profiles > Identity > Rules** shows how your streams are connected through shared identity keys — an isolated stream node means data from that source can never merge with profiles from other sources. Identity keys are configured per field in **Building Profiles > Schema > Fields**, and key rankings (which control conflict resolution during merges) are managed in **Building Profiles > Schema > Ranks**. ### Documentation Links * [Identity Resolution](https://docs.lytics.com/docs/identity-resolution) * [Identity Rules](https://docs.lytics.com/docs/identity-rules) ## Customization ### Learning Objectives By the end of this section, you will be able to: * Create a custom user field with the correct data type and merge operator for a given use case * Explain how `keep_days` and `capacity` settings affect how field values are stored * Select the appropriate merge operator for a given field's semantics ### When You Need Custom Fields The universal and common schema cover a wide range of standard profile attributes. But every account has data that doesn't fit into those categories: subscription tier, loyalty points balance, last product category purchased, consent flags, custom model scores from your data warehouse. For these, you define custom fields. Custom fields live alongside universal and common fields on the profile and can be used in audience conditions, personalization rules, and exports exactly like any built-in field. > Custom field creation is available on Growth and Enterprise Lytics accounts. ### Creating a Custom Field Navigate to **Building Profiles > Schema > Fields**. Click **\+ Create New** to open the field creation wizard. Configure the following parameters: Parameter Description **ID** The field key as it appears on the profile (e.g., `subscription_tier`). Alphanumeric, no spaces. **Short Description** Human-readable label displayed in the UI (e.g., "Subscription Tier") **Data Type** The type of data this field holds — see Data Types below **Long Description** Optional additional context shown in field summaries **Categories** Optional categorization: Identity, Governance, Interests, Behavior, First Party, Intelligence, Activation **Merge Operator** How to resolve conflicts when two sources provide different values — see Merge Operators below **Identity Key** Set to true if this field should be used to stitch profiles together **Keep Days** Days to retain values before expiration. Set to 0 to disable. **Capacity** Maximum values to store for set and map types. Set to 0 for unlimited. **PII** Flag as Personally Identifiable Information for governance and access control ![Building Profiles > Schema > Fields showing the field creation wizard with data type, merge operator, and capacity settings visible.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am157b2895912a318e/6dfb0f95e8451c81eb4f347e/building_profiles_schema_fields_field.png) ### Data Types **Standard types:** Type Use When `string` Single text value — e.g., `subscription_tier: "premium"` `integer` Whole number — e.g., `loyalty_points: 240` `number` Decimal number — e.g., `ltv: 842.50` `boolean` True/false flag — e.g., `email_opt_in: true` `date` Timestamp — e.g., `first_purchase_date: "2024-01-15T10:00:00Z"` **Advanced types:** Type Use When `[]string` Array of unique strings — e.g., all product categories purchased `[]time` Array of unique timestamps — e.g., session timestamps `ts[]string` Time-ordered array of strings — preserves insertion sequence; useful for tracking the order of visited content sections `map[string]string` Key-value pairs with string values — e.g., `{"last_campaign": "spring_promo"}` `map[string]int` Key-value pairs with integer values `map[string]time` Key-value pairs with timestamps — used for `last_channel_activities` `map[string]intsum` Key-value pairs where values accumulate via addition ### Merge Operators The merge operator determines what happens when Lytics receives a new value for a field that already has data. Choose based on the semantics of your field: Operator Behavior Example Use Case **Latest** Keep the most recently timestamped value `subscription_tier` — always reflect the current tier **Oldest** Keep the earliest-timestamped value `first_purchase_date` — never overwrite the original **Minimum** Keep the numerically smallest value `first_order_value` — preserve the smallest purchase amount **Maximum** Keep the numerically largest value `max_order_value` — preserve the single highest purchase **Sum** Accumulate new values into a running total `lifetime_order_count` — add each purchase event **Merge** Take the union of two sets `purchased_product_ids` — accumulate all distinct products > Merge operator selection is high-stakes. A `first_purchase_date` field configured with **Latest** instead of **Oldest** overwrites the original date on every subsequent purchase — permanently destroying the data. Verify your operator matches your intent before ingesting production data. ### Capacity and Keep Days For set and map fields, two additional settings control data retention: * **`capacity`** — Maximum number of values to store. When capacity is reached, values are evicted in FIFO order (oldest first). For example, a `purchased_product_ids` field with `capacity: 100` retains only the 100 most recently seen product IDs. * **`keep_days`** — Values older than this threshold are discarded when the profile is next evaluated. A field configured with `keep_days: 30` automatically expires values from more than 30 days ago. Setting either to 0 (or omitting it) disables that constraint. For high-frequency data like URLs or session timestamps, always set a capacity limit — unbounded set fields can grow large on active profiles and degrade profile evaluation performance. ### Connecting Custom Fields to Data: Mappings A field definition alone produces no data. To populate it, you also need a **mapping** — an LQL expression in a stream query that routes incoming event data to the field. For example, if your e-commerce events include a field called `subscription_level` and you want to map it to your custom `subscription_tier` field: ```sql subscription_level AS subscription_tier SHORTDESC "Subscription Tier" ``` Mappings are defined in **Building Profiles > Schema > Queries**. Full LQL syntax and mapping configuration is covered in [Schema](/academy/courses/lytics-course/schema). ### Summary Custom fields extend profiles beyond the universal and common schema to capture account-specific data like subscription tier, loyalty points, or consent flags. Creating a field requires selecting the correct data type and merge operator — the merge operator is especially critical because it controls how conflicting values are reconciled (e.g., Latest for current state, Oldest for first-touch data, Sum for running totals). For set and map types, `capacity` limits how many values are stored and `keep_days` expires old values automatically. A field definition alone produces no data; you also need an LQL mapping in a stream query to populate it. ### Documentation Links * [Schema Fields](https://docs.lytics.com/docs/schema) * [Merge Operators](https://docs.lytics.com/docs/merge-operators) * [LQL Mappings](https://docs.lytics.com/docs/lql) ## Anatomy of a Profile ### Learning Objectives By the end of this section, you will be able to: * Navigate the Identity Explorer and describe the purpose of each of its six sections * Use the Profile Fields filter to locate a specific field or field category * Use the Raw Data tab to verify profile values during debugging * Delete a profile for GDPR compliance using the Identity Explorer ### The Identity Explorer The **Identity Explorer** is the primary tool for examining an individual profile in depth. Where the three-tab profile view surfaces a summarized view, the Identity Explorer exposes every layer of the profile directly: identifiers, raw attributes, behavioral models, content interests, and historical activity. Access the Identity Explorer by navigating to **Building Profiles > Search**, searching for a profile by identifier, and selecting it from the results. ![Walk through the Identity Explorer for a sample profile: show Identity graph, Profile Fields with filtering, Raw Data JSON, Behavior scores, Content Affinity topics, and Activity heatmap.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am10a4da547461bc2b/72d6e001ffe636b182a9f722/walk_identity_explorer_sample_profile.gif) ### Identity Section The **Identity** section shows the relationships between all unique identifiers associated with this profile. Two views are available: * **Identifier List** — A table of every key-value pair used to link this profile: identifier type (email, cookie, external ID) alongside its value. * **Identity Graph** — A visual representation of connections between identifiers. Each node is an identifier; each edge is a stitching event that connected them. Use this section when troubleshooting merges. If a profile is missing data you expect it to have, check whether the identifier that should link the missing data is present here. A missing or disconnected identifier is the most common cause of incomplete profiles. ### Profile Fields Section The **Profile Fields** section is an exhaustive catalog of every attribute on the profile — universal schema fields, common schema fields, and any custom fields you've defined. Each entry shows the field name, its current value, and the source stream. #### Searching and Filtering The Profile Fields view supports both free-text search and category filters: * **Free-text search** — Type any field name or value fragment to narrow the list. * **Category filters** — Filter by pre-defined field categories (Identity, Behavior, Intelligence, First Party, etc.) to reduce the view to a relevant subset. > Filtering by the **Identity** category is the fastest way to audit which identifiers are active on a profile. Filtering by **Behavior** surfaces only behavioral scores and related fields. This section is the most comprehensive representation of what Lytics knows about a user. Use it to verify that mappings are working, that custom fields are populating correctly, and that expected values are present before building audiences or personalization rules that depend on them. ### Raw Data Section The **Raw Data** section presents the complete profile as a JSON object. Example: ```json { "_id": "4fafb5b3-b199-58f2-a68b-4b266b363dd1", "email": "jane@example.com", "score_momentum": 78, "score_propensity": 91, "lytics_content": { "Cloud Infrastructure": 0.82, "DevOps": 0.65 }, "_segments": ["all", "high_momentum", "content_devops"], "subscription_tier": "premium", "_num_events": 127, "_num_streams": 3 } ``` This view is primarily for developers and data engineers who need to inspect the exact profile payload — for integration testing, debugging API queries, or verifying that an LQL mapping expression produces the expected output. The Raw Data section is the ground truth: everything else in the UI derives from this JSON. ### Behavior Section The **Behavior** section renders a graphical representation of the profile's nine behavioral scores. The scores are displayed relative to your account's population, showing at a glance whether this user's engagement ranks high, mid, or low compared to the rest of your profiles. This is the same data as the `score_*` fields in the universal schema, presented as a visual summary. Use this section when reviewing a test profile to validate that behavioral scoring is working as expected — particularly after a new stream starts sending events or after a schema change that affects the fields feeding into behavioral models. ### Content Affinity Section The **Content Affinity** section visualizes the profile's `lytics_content` map — the topic-level interest scores derived from the user's engagement with your classified web content. Topics are displayed with their affinity values, ordered by strength. Use this section to verify that Lytics' content classification and interest modeling correctly reflect a user's actual browsing behavior before building content-based audiences or personalization rules that target by topic affinity. ### Activity Section The **Activity** section shows a user's activity broken down by day of week and hour of day. Use it to identify when a user is most active and optimize the timing of campaigns accordingly. This data is the same as the event heatmap in the profile's **Intelligence** tab. Use it to confirm that activity from all streams is being captured and attributed to the correct profile. ### Deleting a Profile Profile Administrators can delete an individual profile from within the Identity Explorer. This supports GDPR right-to-erasure requests. To delete a profile: 1. Open the profile in the Identity Explorer. 2. Locate the **Delete Profile** option (available to users with Administrator permissions). 3. Confirm the deletion. > Deletion is permanent. The profile and all associated data are removed from Lytics. If the same identifiers appear in future events, a new profile will be created with no memory of the deleted record. Download the profile data before deletion if you need to fulfill a data portability request. ### Summary The Identity Explorer is the primary deep-inspection tool for individual profiles, exposing six sections: Identity (identifier relationships and graph), Profile Fields (all attributes with search and category filters), Raw Data (the complete profile JSON), Behavior (visual behavioral score summary), Content Affinity (topic interest scores), and Activity (engagement by day and hour). When troubleshooting, start with the Identity section to verify identifier connections, then use Profile Fields or Raw Data to confirm specific values. Profile Administrators can permanently delete a profile from the Identity Explorer to fulfill GDPR right-to-erasure requests. ### Documentation Links * [Identity Explorer](https://docs.lytics.com/docs/identity-explorer) * [Profile Deletion](https://docs.lytics.com/docs/profile-deletion) * [GDPR Compliance](https://docs.lytics.com/docs/gdpr) ## What You've Learned You now understand the profile as the central object in Lytics — a continuously updated, unified record built from events across every connected data source. You've seen how to find and inspect profiles in the UI through both the three-tab profile view and the more detailed Identity Explorer. You know the two schema layers that exist on every profile (universal and common), the nine behavioral scores that Lytics computes automatically, and how identity rules connect events from different streams into a single record. You've also learned how to extend profiles with custom fields — selecting the right data type, merge operator, and retention settings — and how to populate those fields through LQL mappings. ### Key Terms > 📘 **Profile (Entity)** — The unified representation of a single individual in Lytics, constructed from all known events and attributes across every connected data source. Also referred to as an entity. > > 📘 **Universal Schema** — A set of computed, intelligent attributes applied to every profile in Lytics, regardless of data source, age, or whether the profile is anonymous or known. Includes identifiers, metafields, behavioral scores, interests, and intelligence fields. > > 📘 **Common Schema** — A set of standard profile attributes that provide consistency across integrations. Common fields normalize source-specific field names (like contact name or email) into a single canonical representation. > > 📘 **Behavioral Score** — A platform-computed 0–100 metric that quantifies engagement patterns across dimensions like recency, frequency, momentum, and intensity. Scores are relative to other profiles in your account. > > 📘 **Content Affinity** — A platform-computed score measuring each profile's interest in your content topics, based on engagement with classified web content. > > 📘 **Identity Rule** — A configuration that defines which event fields Lytics uses as identity keys to stitch events from different data streams into a single profile. > > 📘 **Merge Operator** — The rule that determines how conflicting values for a profile field are reconciled when data arrives from multiple sources (e.g., Latest keeps the most recent value, Sum accumulates a running total). > > 📘 **Identity Explorer** — The primary deep-inspection interface for individual profiles, exposing six sections: Identity, Profile Fields, Raw Data, Behavior, Content Affinity, and Activity. #### Key takeaways - Connect **Profile** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 05 — ID Resolution #### Lesson text Identity resolution is the process by which Lytics connects data about the same real person across devices, channels, and sessions into a single unified profile. Without a deliberate identity strategy, you end up with fragmented data, over-merged profiles, and audiences you cannot trust. This section covers how the identity graph works, what causes profiles to become unhealthy, which tools you use to investigate and debug identity behavior, and how to maintain identity integrity as an ongoing operational discipline. ## Identity Graph ### Learning Objectives By the end of this section, you will be able to: * Explain how Lytics models identity as a graph of linked identifiers and fragments * Configure identity keys and ranks to control merge behavior * Validate graph behavior using UI and API tools before moving to activation ### How the Identity Graph Works Lytics stores identity as a graph. An identity key is a field used to recognize a user across events — for example `email`, `_uids`, or a customer ID. Each identity key value is represented as a node called an identity fragment — the stored data associated with one identity key/value pair, plus its links to other fragments. Links between fragments are represented as edges, and a profile is the traversed set of connected fragments. At ingestion time, Lytics evaluates the incoming event and: 1. Reads identity keys present on the event. 2. Creates or updates fragments for those keys. 3. Stitches fragments together when the event provides evidence that identifiers belong to the same real person. 4. Traverses neighboring fragments to materialize the current profile. This means profile resolution is not a simple one-row lookup. It is a graph traversal problem with merge constraints and guardrails. ### Deterministic Identity Resolution For implementation work in Lytics, identity stitching follows deterministic rules — but the resolved graph is shaped by both your configuration (identity keys, ranks, schema) and the identifier co-occurrences present in incoming events. That means stitch outcomes can change as new evidence arrives (for example, a previously unseen email appearing alongside a known cookie). Build and validate your identity strategy using deterministic rules and controlled event samples before activation, and plan to re-verify behavior after any schema or rank change. ### Identity Key Strength and Rank Not all identifiers should have equal weight. In practice: * Strong, stable IDs (for example: authenticated customer ID, normalized email) should be ranked higher. * Volatile IDs (for example: browser cookies) should be ranked lower. In merge conflicts, higher-ranked identity keys win. This is a core protection against over-merging. ### Graph Guardrails and Compaction The platform applies traversal guardrails and profile-breaking thresholds to prevent pathological graphs: * Traversal controls include max-lookups and max-neighbors settings, with max-traversal pressure surfaced in profile metadata. * Lytics tracks traversal and neighbor pressure in profile metadata (for example `_max_traversals`, `_num_max_neighbors`). To keep graphs maintainable over time, Lytics also runs graph compaction workflows. Backend compactor registration includes `composite_compactor`, `stale_id_compactor`, `rank_overlink_compactor`, and `rank_compactor`. ### Implementation Steps 1. In **Conductor**, open **Identity > Rules** and review current identifier fields and rank order. 2. Confirm identity-key field types and capacities in schema (for example, set limits on multi-value keys where appropriate). 3. Verify route-level graph output via **Identity Explorer** and via API (`/v2/identity/:table/:field/:value`). 4. Validate network topology with `/v2/schema/:table/network` to confirm expected node/edge relationships. 5. Use **Profile Simulator** (`/conductor/schema/simulate`) when testing major identity-rule changes before production rollout. ### Example: Conflict Resolution If profile A is anchored by `email=A` and profile B by `email=B`, and a new event links a shared cookie to both, the rank model determines which side keeps the merge path. This is why rank governance is operationally critical and should not be changed casually. #### Diagrams & Screenshots ![Identity graph showing email and cookie fragments with ranked conflict resolution.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am539fd699a2e67d38/c0d330146d4a4d3350b65e7e/identity_graph_email_cookie_fragments.png) ![Identity Rules page showing identifier rank ordering.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am78ddd270b9c625e9/8810061a9d56f2327f59ea34/identity_rules_page_identifier_rank.png) ### Summary The identity graph models each identifier value as a fragment node and links fragments together when events provide evidence they belong to the same person. Profile materialization is a graph traversal over those linked fragments, not a simple lookup. Strong identifiers should be ranked higher than volatile ones so that merge conflicts resolve in favor of the most reliable data. Rank configuration is operationally critical — changes to it can materially alter how profiles are unified across your entire dataset. ### Documentation Links * [Identity Resolution Overview](https://docs.lytics.com/docs/identity-resolution) * [Identity Rules Configuration](https://docs.lytics.com/docs/identity-rules) * [Identity Graph and Fragments](https://docs.lytics.com/docs/identity-graph) ## Unhealthy Profiles ### Learning Objectives By the end of this section, you will be able to: * Identify what makes a profile unhealthy in Lytics and why it matters for activation * Diagnose which limit or data pattern is causing profile failure * Apply remediation steps that reduce unhealthy profile volume over time ### What "Unhealthy" Means Lytics defines unhealthy profiles as profiles where traversal/materialization fails, commonly due to one or more of: * Max neighbors limits * Max traversals/lookups limits * Oversized profile or fragment payloads When a profile is unhealthy, Lytics excludes it from audience evaluations, exports/triggers, and enrichment processing (including behavioral scoring and content affinity calculations). ### What Data Remains on an Unhealthy Profile Unhealthy profiles retain identity-critical and diagnostic fields, including by-fields and key metafields such as: * `_profile_processing_failure` * `_num_max_neighbors` * `_max_traversals` * `_broken_profile_broke_max_size` * `_broken_profile_broke_max_fragment_size` * `_broken_profile_max_neighbors` * `_broken_profile_nested_count` This is consistent with backend behavior that marks broken profiles and reduces them to a minimal keep-set of identity and diagnostic fields. ### How to Detect Unhealthy Profiles Use all three layers: 1. **Default audience**: `default_unhealthy_profiles` (filter: `_profile_processing_failure = true`). 2. **Profile-level inspection** in Identity Explorer for traversal and size indicators. 3. **Trend monitoring** of unhealthy audience size versus total active profiles. ### Remediation Workflow 1. Identify the failure type (`neighbor`, `traversal`, `size`, or nested-field explosion). 2. Trace offending identifiers and streams on affected profiles. 3. Correct schema and mapping hygiene: \- Add/adjust caps for high-cardinality set fields. \- Reduce accidental many-to-many linking keys. \- Re-rank identifiers to prioritize stable keys. 4. Reprocess appropriately: \- Some issues require replay. \- Others resolve through normal re-evaluation after corrected events. 5. Track post-fix unhealthy trend for at least one scoring cycle. ### Example Failure Pattern A shared device or kiosk can cause one cookie to accumulate many unrelated emails, driving max-neighbor pressure. If cookie rank is too high or email constraints are weak, you can over-link the graph and eventually produce unhealthy profiles. #### Diagrams & Screenshots ![Unhealthy Profiles audience trend line compared to total profiles.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am0fe8ee37c111791b/bbfa34357a2f89474c7af353/unhealthy_profiles_audience_trend_line.png) ![Identity Explorer profile showing processing failure metadata fields.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am3fc1259ad95e544d/55e4b2f7c33ccff8c5f660fd/identity_explorer_profile_processing_failure.png) ### Summary Unhealthy profiles are those where Lytics cannot complete graph traversal or materialization — typically because max-neighbor, max-traversal, or payload-size limits are exceeded. When a profile is unhealthy, it is excluded from all audience evaluations, enrichment, and activation exports. Remediation follows a consistent workflow: identify the failure type using `_profile_processing_failure` and related meta fields, trace the offending identifiers, correct schema and rank configuration, reprocess as needed, and monitor the unhealthy trend through at least one scoring cycle before declaring the issue resolved. ### Documentation Links * [Unhealthy Profiles](https://docs.lytics.com/docs/unhealthy-profiles) * [Identity Graph Limits](https://docs.lytics.com/docs/identity-graph-limits) * [Profile Processing Failure Fields](https://docs.lytics.com/docs/profile-metadata-fields) ## Identity Tools ### Learning Objectives By the end of this section, you will be able to: * Navigate identity investigation tools in the Lytics UI with confidence * Use the core identity API endpoints for lookup, network inspection, and GDPR deletion workflows * Trace browser-side identity behavior from JS Tag and Pathfora integrations ### UI Tools (Conductor) The UI exposes identity investigation through three primary surfaces: * **Identity > Rules** for key/rank strategy configuration. * **Identity > Stats** for aggregate identity-health insights. * **Search** (`/conductor/identity/explorer`) for profile-level investigation. In **Identity Explorer**, you can: * Visualize fragments and conflicts (graph + table). * Inspect profile fields, raw data, behavior, audiences, and activity. * Download a profile snapshot. * Trigger profile deletion (GDPR path), with asynchronous completion. ### API Tools Primary identity endpoints in current backend routes: * `POST /v2/identity/lookup` * `GET /v2/identity/:table/:field/:value` * `DELETE /v2/identity/:table/:field/:value` * `GET /v2/identity/deletestatus/overview` * `GET /v2/identity/deletestatus/:reqid` * `GET /v2/identity/deletestatus/list` * `GET /v2/schema/:table/network` The identity response model centers on: * `entity` (materialized profile payload) * `fragments` (fragment-level keys, neighbors, streams, conflict state, and neighbor-limit signals) ### Profile Simulator for Pre-Production Testing The UI **Profile Simulator** uses `/v2/simulate-entity-analysis` and returns step-wise identity analyses. Use it when you want to test field/mapping/rank changes against representative events before committing schema updates. ### Browser-Side Identity Tooling (JS Tag + Pathfora) `jstag3` and Pathfora are part of the operational identity toolchain for web experiences: * `jstag.getid(callback)` retrieves the current ID asynchronously. * `jstag.setid(id)` sets the current ID cookie value. * `jstag.identify(...)` is an alias of `send(...)`. * `jstag.loadEntity`, `entityReady`, `getEntity`, and `getSegments` drive client-side personalization and segment-aware behavior. * Default JS Tag cookie name is `seerid`, storing `_uid` by default. * Pathfora targeting requires JS Tag segment data; if not available, targeted modules will not initialize as expected. * Pathfora entity templates read identity/profile data from `window.jstag.getEntity()` (or legacy `window.lio.data`) and support fallback/default handling. ### Investigation Playbook 1. Start with a known identifier in **Identity Explorer**. 2. Confirm profile-level fields and segment memberships. 3. Call identity API for fragment-level details and conflict/neighbor-limit signals. 4. Check identity rules/ranks and schema mappings for merge misconfiguration. 5. Validate web identifier flow (`getid`, cookie name, entity load timing) if issue originates in browser personalization. 6. Confirm impact scope using unhealthy-profile and affected-audience trends. #### Diagrams & Screenshots ![Identity Explorer with graph and fragment conflict indicators.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amcd2abdd66b7fb226/56577621a8650db4fc900e5e/identity_explorer_graph_fragment_conflict.png) ![Profile Simulator showing step analyses and graph output.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am34a08ae867c6619d/a2f7bc088228e3ded7082a2f/profile_simulator_step_analyses_graph.png) ### Summary Identity investigation in Lytics spans three layers: the UI (Identity Explorer for fragment-level inspection, Identity Stats for aggregate health), the API (`/v2/identity` endpoints for lookup, deletion, and network topology), and the browser (JS Tag methods for reading and setting identifiers, and Pathfora for segment-driven experiences). The investigation playbook starts with a known identifier in the Explorer, confirms profile fields and audiences, then drops into the API for fragment-level detail before checking rules and schema for misconfiguration. ### Documentation Links * [Identity Explorer](https://docs.lytics.com/docs/identity-explorer) * [Identity API Reference](https://docs.lytics.com/reference/identity-api) * [Profile Simulator](https://docs.lytics.com/docs/profile-simulator) * [JS Tag Identity Methods](https://docs.lytics.com/docs/jstag-identity) ## Data Integrity ### Learning Objectives By the end of this section, you will be able to: * Define practical identity integrity standards for implementation teams * Build a monitoring and response workflow for identity degradation * Introduce safe change controls for schema and identifier-rank updates ### Integrity Principles Treat identity quality as an operating discipline, not a one-time setup: 1. **Use stable primary identifiers first.** Keep weak identifiers lower-ranked. 2. **Bound cardinality.** Avoid unbounded set fields for IDs and nested structures. 3. **Separate collection from trust.** You can collect many identifiers, but do not rank all of them equally. 4. **Assume drift.** Browser IDs rotate, integrations change shape, and mappings regress unless monitored. 5. **Control change blast radius.** Rank and identity-rule changes can materially alter profile unification. ### Operational Metrics to Monitor Track at least: * Volume and rate of `default_unhealthy_profiles` * Distribution of `_profile_processing_failure` causes * Profiles with `_num_max_neighbors` and `_max_traversals` pressure * Oversize indicators (`_total_sz`, `_num_nested_values`, broken-size flags) * Segment count anomalies after schema/rank changes ### Runbook: Identity Health Incident 1. Detect: unhealthy profile spike or audience drift. 2. Contain: freeze non-essential schema/rank changes. 3. Diagnose: isolate stream(s), identifier(s), and merge path causing the break. 4. Correct: update mappings/ranks/caps and deploy with explicit rollback criteria. 5. Recover: replay or re-evaluate profiles as required. 6. Verify: compare pre/post metrics and confirm activation counts normalize. 7. Document: capture root cause and prevention controls. ### Governance Controls * Require review for identifier-rank modifications. * Test identity-rule changes in simulator before production rollout. * Gate releases on unhealthy-profile trend checks. * Keep a versioned checklist of accepted identity keys, rank rationale, and capacity limits. ### Source-Verified Implementation Notes Backend/account settings include explicit controls for: * `traversal_max_lookups` * `traversal_max_neighbors` * `traversal_max_neighbors_by_table` * `graphcompact` Use these controls deliberately and only with a clear rollback plan. #### Diagrams & Screenshots ![Identity health dashboard with unhealthy profile and traversal-limit indicators.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am6b259f015c7163e3/76cec8a69da52e3290e43f53/identity_health_dashboard_unhealthy_profile.png) ![Change control checklist for identifier rank updates.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am571092fe295d8a0e/8118f8cf8fd8ee152dea6600/change_control_checklist_identifier_rank.png) ### Summary Identity integrity is an ongoing operational discipline, not a one-time configuration task. The five core principles — stable identifiers first, bounded cardinality, separated collection from trust, assumed drift, and controlled change blast radius — form the foundation of a maintainable identity strategy. Monitor unhealthy profile volume, failure cause distribution, and traversal pressure on a regular cadence. When an identity health incident occurs, follow the seven-step runbook: detect, contain, diagnose, correct, recover, verify, and document. All schema and rank changes should go through the Profile Simulator and be gated on post-change metric validation before being considered complete. ### Documentation Links * [Identity Health Monitoring](https://docs.lytics.com/docs/identity-health) * [Account-Level Identity Settings](https://docs.lytics.com/docs/account-identity-settings) * [Identity Governance Best Practices](https://docs.lytics.com/docs/identity-governance) ## What You've Learned Identity resolution in Lytics is the process of connecting all data about the same real person into a single unified profile through a graph of linked identity fragments. You've learned how the graph is built and traversed, how identifier rank determines merge behavior when conflicts arise, what causes profiles to become unhealthy and how to remediate them, which UI and API tools support identity investigation, and how to maintain identity integrity as a production operating discipline. With a well-governed identity strategy, your audiences are reliable, your activations reach the right people, and your enrichment data reflects reality. ### Key Terms > 📘 **Identity Key** — A field used to recognize a user across events (for example: `email`, `_uids`, customer ID). Identity keys are configured with a rank that determines their priority in merge conflict resolution. > > 📘 **Identity Fragment** — A unit of profile evidence associated with one identity key/value pair. Fragments are connected (stitched) when events carry multiple identifiers together, and a profile is materialized by traversing the connected graph of fragments. > > 📘 **Identity Graph** — The graph structure Lytics uses to represent relationships between identity fragments. Each identifier value is a node; links between identifiers (established by co-occurrence on events) are edges. > > 📘 **Unhealthy Profile** — A profile where graph traversal or materialization has failed due to exceeding max-neighbor, max-traversal, or payload-size limits. Unhealthy profiles are excluded from audience evaluation, enrichment, and activation exports. > > 📘 **Profile Simulator** — A UI tool that runs step-wise identity analysis against test events using `/v2/simulate-entity-analysis`. Use it to validate identity-rule and schema changes before production rollout. > > 📘 **Graph Compaction** — A set of backend workflows (`composite_compactor`, `stale_id_compactor`, `rank_overlink_compactor`, `rank_compactor`) that keep the identity graph maintainable by cleaning up stale and over-linked fragments over time. #### Key takeaways - Connect **ID Resolution** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 06 — Tag #### Lesson text The Lytics JavaScript tag is the primary mechanism for collecting behavioral data from your website and surfacing profile data back to the browser for personalization. Getting the tag right — from initial installation through consent handling, cookie configuration, and identity stitching — determines the quality of the data that flows into every downstream process. This section covers what the tag does, how to customize it for your event taxonomy, how to work with the SDK programmatically, and how to configure consent and identity behavior correctly. ## What is the Tag ### Learning Objectives By the end of this section, you will be able to: * Explain what the Lytics tag does and how it differs from the broader SDK * Understand how the tag collects behavioral data from web pages * Verify that the tag is correctly installed and firing on your site ### What Is the Tag The Lytics JavaScript tag (`jstag`) is your web collection runtime. It runs in the browser, creates or reads the visitor `_uid`, sends behavioral events to Lytics, and can load profile data back into the page for audience-aware personalization. The profile payload returned to the browser for the current visitor — called the entity — includes audience membership (`segments`) by default and can include additional surfaced profile fields. The distinction that matters in implementation: \- The **tag snippet** loads and initializes `jstag` on your site. \- The **SDK runtime** is the executable `jstag` API surface (`send`, `pageView`, `loadEntity`, `entityReady`, `getid`, and related methods). By default, the tag sends page-level and browser-level context, including fields like `_e` (event type), `url`, `_ref`, `_uid`, `_ts`, `_device`, `_nmob`, and `_v` (tag version). You then add your own event payloads on top of this baseline. #### Key Concepts * **Automatic collection baseline**: Initial pageview and page metadata are captured once the tag is initialized. * **Event stream output**: `jstag.send()` pushes custom behavioral payloads into your configured stream. * **Asynchronous profile loading**: Entity/profile access happens asynchronously and should use callbacks or listeners. * **Verification modes**: Use both UI verification and browser checks. #### Step-by-Step 1. Install the Lytics tag snippet from the Lytics app for your account CID. 2. Load a tagged page and confirm no JavaScript initialization errors in console. 3. In console, run `jstag.config.version` to verify the runtime is present. 4. Trigger a test event: ```javascript jstag.send({ event: "academy_tag_install_test" }); ``` 5. In Network tools, confirm outbound collection requests to the Lytics endpoint. 6. In Lytics, validate that stream/event data arrives for the test payload. #### Examples ```javascript // Basic event collection jstag.send({ event: "cta_click", cta_name: "request_demo", page_type: "pricing" }); ``` ```javascript // Manual pageview when needed (for route-based tracking patterns) jstag.pageView(); ``` #### Diagrams & Screenshots ![Browser page with Lytics tag installed and a successful network collect call.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am18cce815c774d9d1/b5988fdb035592704a04d127/browser_page_lytics_tag_installed.png) ### Summary The Lytics tag (`jstag`) is a browser-side runtime that collects behavioral events and returns profile data for personalization. The tag snippet loads the SDK, which exposes the full `jstag` API for sending events, managing identity, and loading the entity payload. Verification requires both browser developer tools (console and network inspection) and confirmation that data arrives in the Lytics event stream. ### Documentation Links * [JavaScript Tag Overview](https://docs.lytics.com/docs/jstag-overview) * [Tag Installation](https://docs.lytics.com/docs/tag-installation) * [Tag Verification](https://docs.lytics.com/docs/tag-verification) ## Customizations ### Learning Objectives By the end of this section, you will be able to: * Configure custom events to capture business-specific user interactions * Integrate the Lytics tag with data layers (e.g., Google Tag Manager data layer) * Customize tag behavior including event filtering, field mapping, and conditional loading ### Customizations A production tag implementation should not stop at default pageview collection. You should explicitly capture high-value behaviors (product views, form starts, submits, purchases, trials, churn signals) and normalize naming so downstream schema mapping is predictable. The runtime and account settings support several customization points: \- Runtime config such as `stream`, `loadid`, `qsargs`, `cookie`, `sessecs`, and `entity` lookup options. \- Account-level options for custom data layer variables and custom cookie keys to auto-collect. \- Entity callbacks to push Lytics audience data into external tools (for example, GTM `dataLayer` pushes). #### Key Concepts * **Stream strategy**: Use explicit stream names when separating domains or source systems. * **Query parameter forwarding**: `qsargs` allows deterministic pass-through of selected URL params. * **Data layer ingestion**: You can merge site/app data layer values into Lytics payloads for richer events. * **Downstream sync hooks**: Audience membership can be pushed into tools through `entityReady` callbacks. #### Step-by-Step 1. Define an event taxonomy (event names and required fields) before coding. 2. Configure default stream behavior in `jstag.init` when needed. 3. Add explicit `jstag.send()` calls at important interaction points. 4. Add selected query params to `qsargs` if campaign/attribution context is needed. 5. If using GTM, push entity audiences into `window.dataLayer` using an `entityReady` callback. 6. Validate in browser network + data layer inspection + downstream tool preview mode. #### Examples ```javascript jstag.init({ cid: "YOUR_CID", stream: "web_behavior", loadid: true, qsargs: ["utm_source", "utm_medium", "utm_campaign"] }); ``` ```javascript // Custom conversion event with business context jstag.send({ event: "subscription_started", plan: "pro", billing_cycle: "annual", value: 299.00, currency: "USD" }); ``` ```javascript // Push Lytics audiences into GTM dataLayer jstag.entityReady((_, entity) => { const segments = entity?.data?.user?.segments || []; window.dataLayer = window.dataLayer || []; window.dataLayer.push({ event: "set_lytics_audiences", lytics_audiences: segments.join(",") }); }); ``` #### Diagrams & Screenshots ![Custom event instrumentation plan mapped to page interactions.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ame290e3c4eae2952d/22e62af764489284f0bda25e/custom_event_instrumentation_plan_mapped.png) ### Summary A production tag implementation goes beyond default pageview collection by instrumenting high-value user interactions with explicit `jstag.send()` calls and a defined event taxonomy. Runtime configuration options control stream routing, query parameter forwarding, and entity lookup behavior. Entity callbacks bridge Lytics audience data into external tools like GTM, enabling downstream targeting without requiring separate integrations. ### Documentation Links * [Custom Event Instrumentation](https://docs.lytics.com/docs/custom-events) * [Tag Runtime Configuration](https://docs.lytics.com/docs/jstag-configuration) * [GTM Integration](https://docs.lytics.com/docs/google-tag-manager) ## Working with SDK ### Learning Objectives By the end of this section, you will be able to: * Use SDK methods programmatically to send events, identify users, and retrieve profile data * Implement advanced data collection patterns such as SPA tracking and dynamic event properties * Handle SDK lifecycle events including initialization, readiness callbacks, and error handling ### Working with SDK The JS SDK is asynchronous and event-driven. Treat entity access and identifier access as async operations, and keep page-level collection separate from profile reload behavior. Core method groups you will use most: \- **Collection**: `send`, `identify`, `page`, `pageView` \- **Identity utility**: `getid`, `setid` \- **Profile/entity**: `loadEntity`, `entityReady`, `getEntity`, `unloadEntity` \- **Execution control**: `blocked` + `unblock` workflow when you need delayed dispatch #### Key Concepts * **`identify` is a semantic alias of `send`**: use it when the payload is identity-focused. * **`entityReady` is passive**: it listens for entity loads; it does not trigger load itself. * **`loadEntity` is explicit**: call it when route changes or context changes require profile refresh. * **SPA pattern**: call `pageView()` on route changes and `loadEntity()` when personalization state must refresh. #### Step-by-Step 1. Initialize `jstag` with your account CID and required options. 2. Register `entityReady` once in app bootstrap code. 3. Instrument user interactions with `send` and identity updates with `identify`. 4. In SPAs, hook your router to call `pageView()` after each route render. 5. Call `loadEntity()` when route context changes affect targeting or experiences. 6. Avoid `getEntity()` unless you are sure entity has already loaded (inside `entityReady` is safe). #### Examples ```javascript jstag.entityReady((_, entity) => { const segments = entity.data?.user?.segments || []; console.log("Current Lytics segments", segments); }); ``` ```javascript // SPA route handler example function onRouteChange(route) { jstag.pageView({ route }); jstag.loadEntity({ route }); } ``` ```javascript // Identity-focused send jstag.identify({ email: "person@example.com", customer_id: "cust_12345", event: "user_identified" }); ``` #### Diagrams & Screenshots ![Chrome DevTools Console on redpandaresorts.com showing jstag.getEntity() returning a real live profile: behavioral scores (consistency, frequency, intensity, momentum, propensity, quantity, recency, volatility), segment\_prediction values, segment\_prediction\_percentile, and segments membership (anonymous\_profiles, all, adventurous\_web\_visitors) — proving the tag is installed, loadEntity is working, and profile enrichment is live.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am63b4eb5a18b5ec65/4a42c4a40ad1d568fd1859b0/spa_route_change_flow_calling.png) ### Summary The JS SDK is asynchronous throughout — entity access, identifier retrieval, and profile loading all operate via callbacks and listeners rather than synchronous returns. The four core method groups (collection, identity utility, profile/entity, and execution control) cover the full range of implementation needs from basic event sending to SPA route tracking. Register `entityReady` once at bootstrap, use `loadEntity` explicitly when personalization context changes, and avoid `getEntity` outside of confirmed entity-ready contexts. ### Documentation Links * [JS Tag SDK Reference](https://docs.lytics.com/reference/jstag-sdk) * [Entity and Profile Loading](https://docs.lytics.com/docs/entity-loading) * [SPA Tracking Patterns](https://docs.lytics.com/docs/spa-tracking) ## Consent Management ### Learning Objectives By the end of this section, you will be able to: * Integrate consent state collection into tag and SDK events * Apply opt-in and opt-out behavior so data collection honors user preferences * Design consent data structures that support enforceable segmentation rules ### Consent Management Consent in Lytics is both a collection concern and an activation concern. You need to capture consent events with enough context to enforce policy in segmentation and downstream export filters. Recommended consent payload components: \- `consented` status (true/false) \- `purpose` or consent type \- optional context (`location`, `documents`, source form, timestamp context) From the SDK side, jstag includes consent controls (`optIn`, `optOut`) and an internal consent-blocking model. The source also includes OneTrust consent integration (`onetrust.consent`) that can block/allow sends based on accepted categories. #### Key Concepts * **Granular consent model**: design per-purpose consent, not one global boolean for all activation. * **Profile materialization**: map consent fields into schema with merge behavior that preserves the latest state. * **Enforcement path**: use consent audiences + global job segment filters to prevent restricted exports. * **Runtime controls**: opt-out should stop sends and clear tag cookies. #### Step-by-Step 1. Define your consent taxonomy (purpose names, accepted/denied states, and context fields). 2. Instrument explicit consent events from forms/CMP callbacks using `jstag.send`. 3. Map consent events into profile fields in Schema (usually map fields with merge rules). 4. Build building-block audiences (for example, `has_marketing_consent`, `no_marketing_consent`). 5. Apply consent exclusion filters to destination jobs so restricted profiles are not activated. 6. If using OneTrust, configure accepted categories and test both accept/deny paths. #### Examples ```javascript jstag.send({ event: "consent_update", consent: { purpose: "email_marketing", consented: true, documents: ["terms_v2026_01"], location: "US" } }); ``` ```javascript // OneTrust-aware pseudocode pattern // on accept: jstag.optIn() // on deny: jstag.optOut() ``` ### Summary Consent management in Lytics spans collection, schema, segmentation, and activation. Capture consent events with purpose, status, and context fields, map them into profile schema with appropriate merge behavior, build consent-state audiences to reflect current opt-in status, and apply those audiences as exclusion filters on destination export jobs. The `optIn` and `optOut` SDK controls handle runtime enforcement, and OneTrust integration provides a CMP-native path for accepting or blocking collection based on consent categories. ### Documentation Links * [Consent Management Overview](https://docs.lytics.com/docs/consent-management) * [OneTrust Integration](https://docs.lytics.com/docs/onetrust-integration) * [Consent Enforcement in Exports](https://docs.lytics.com/docs/consent-export-filtering) ## Custom Cookie Settings ### Learning Objectives By the end of this section, you will be able to: * Configure cookie-related SDK settings for identity and session handling * Understand session TTL and cookie key behavior in jstag v3 * Validate cookie behavior across domains and browsers ### Custom Cookie Settings Cookie behavior directly affects profile continuity and session logic. In `jstag` configuration, the key cookie settings are: \- `cookie` (default `seerid`): stores `_uid` \- `sesname` (default `seerses`): session cookie name \- `sessecs` (default `1800`): session cookie TTL in seconds Account settings also provide: \- **Custom Cookie Keys**: additional cookie names that the SDK should automatically collect. \- Related client-side integration toggles that rely on runtime IDs and audience sync behavior. #### Key Concepts * **`_uid` persistence**: stable cookie behavior is foundational to anonymous profile continuity. * **Session boundary**: `sessecs` controls when a new session starts after inactivity. * **Collection vs control**: collecting custom cookies is separate from changing the core `_uid` cookie. * **Troubleshooting primitive**: `getCookie`, `setCookie`, `deleteCookie`, `clearCookies` are available for debugging. #### Step-by-Step 1. Start with default cookie settings unless you have a clear domain or governance requirement. 2. If needed, set custom names for `cookie` and `sesname` in `jstag.init`. 3. Set `sessecs` to match your measurement/session strategy. 4. Configure any additional auto-collected cookie keys in account settings. 5. Validate in browser storage tools across navigation, inactivity windows, and subdomains. 6. Confirm downstream identity continuity after deployment. #### Examples ```javascript jstag.init({ cid: "YOUR_CID", cookie: "my_uid_cookie", sesname: "my_session_cookie", sessecs: 1800 }); ``` ```javascript // Debugging utilities console.log(jstag.getCookie("my_uid_cookie")); jstag.setCookie("academy_test", "true", 300); jstag.deleteCookie("academy_test"); ``` #### Diagrams & Screenshots ![Cookie and session values in browser storage after jstag initialization.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ameecb12fcee31802b/44760ddf194e3a90ebbd18b8/cookie_session_values_browser_storage.png) ### Summary Cookie configuration in `jstag` controls the names and TTLs of the `_uid` and session cookies that underpin anonymous profile continuity and session boundary detection. Default settings work for most implementations, but custom domain requirements or governance policies may require renaming cookies or adjusting session TTL. Validate cookie behavior in browser storage tools across navigation patterns and subdomain boundaries, and confirm that identity continuity holds in the downstream profile data before considering the deployment complete. ### Documentation Links * [Cookie Configuration](https://docs.lytics.com/docs/jstag-cookie-settings) * [Session Management](https://docs.lytics.com/docs/session-management) * [Cross-Domain Tracking](https://docs.lytics.com/docs/cross-domain-tracking) ## ID Resolution Considerations ### Learning Objectives By the end of this section, you will be able to: * Explain how tag-collected identifiers feed the Lytics identity graph * Use `loadid`, `_uid`, and custom identity fields appropriately for profile stitching * Avoid common over-merge and identity-conflict pitfalls in tag-based implementations ### ID Resolution Considerations The tag contributes identity evidence on every send. At minimum, it contributes browser identity (`_uid`). As more identifiers are sent (email, login ID, CRM ID), Lytics can stitch fragments into richer unified profiles. An identity fragment — a unit of profile evidence associated with one identity key/value pair — is created or updated each time the tag sends an event carrying a recognized identifier. Fragments are connected when events carry multiple identifiers together. The most important implementation decisions are: \- Whether to enable `loadid` for broader cross-domain/cross-context linking. \- Which custom identifier fields you send during known-user moments. \- Whether to configure entity lookup with `entity.byFieldKey` / `entity.byFieldValue` when authenticated identity should drive profile retrieval. #### Key Concepts * **Identifier strength and ranking**: strong identifiers (for example, stable customer IDs or verified email keys) should anchor strategy; weak identifiers (cookies) should not dominate merge decisions. * **Known-user transitions**: login/signup events should include stable IDs to link anonymous and known behavior. * **Override caution**: `setid` and custom entity lookup are advanced tools; misuse can fragment or over-merge profiles. * **Schema alignment**: identifier fields must be mapped and governed in schema and identity rules. #### Step-by-Step 1. Define your identity key hierarchy before deployment (cookie, email, customer ID, device IDs). 2. Ensure anonymous traffic consistently carries `_uid` from tag sends. 3. On authentication events, send stable first-party identifiers with the same event. 4. If needed, configure entity lookup by known ID for authenticated experiences. 5. Review identity behavior in Identity tooling and merge statistics. 6. Adjust identity ranks/rules in schema strategy before scaling campaigns. #### Examples ```javascript // Known-user bridge event after login jstag.send({ event: "login_success", customer_id: "cust_12345", email: "person@example.com" }); ``` ```javascript // Entity lookup by custom profile field (advanced usage) jstag.init({ cid: "YOUR_CID", entity: { byFieldKey: "customer_id", byFieldValue: "cust_12345" } }); ``` For broader identity strategy details, see [ID Resolution](/academy/courses/lytics-course/id-resolution) and align tag behavior with your identity rule design. #### Diagrams & Screenshots ![Identity stitching flow from anonymous \_uid to known customer\_id and email.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am0f1ff55227c42fa8/521b64c05886a4b503d4b83e/identity_stitching_flow_anonymous_uid.png) ### Summary Every tag send contributes identity evidence to the Lytics identity graph. Anonymous sessions carry `_uid` as a cookie-based fragment; login and signup events bridge anonymous and known behavior by sending stable identifiers alongside the `_uid`. The key implementation decisions — whether to enable `loadid`, which identifier fields to send at known-user moments, and how to configure entity lookup for authenticated experiences — should be made before deployment and aligned with your identity rule and rank configuration in the platform. ### Documentation Links * [Tag Identity Configuration](https://docs.lytics.com/docs/tag-identity) * [Identity Stitching from Web Events](https://docs.lytics.com/docs/web-identity-stitching) * [loadid Configuration](https://docs.lytics.com/docs/loadid) ## What You've Learned The Lytics tag is the browser-side foundation of your data collection and personalization strategy. You've seen how the tag snippet initializes the `jstag` SDK runtime, how that runtime sends behavioral events and loads the entity payload for audience-aware personalization, and how to verify correct installation. You've configured custom events for business-specific interactions, integrated with data layers, and used SDK methods to handle the full lifecycle from initialization through SPA route tracking. You've also covered consent enforcement at the collection layer, cookie configuration for session and identity continuity, and how tag-collected identifiers feed the identity graph to stitch anonymous and known behavior into unified profiles. ### Key Terms > 📘 **jstag** — The Lytics JavaScript SDK runtime. The tag snippet loads and initializes `jstag` in the browser; the SDK exposes the full API surface for event collection, identity management, and entity loading. > > 📘 **Entity** — The profile payload returned to the browser for the current visitor. By default, it includes audience membership (`segments`) and can include additional surfaced profile fields. Access it asynchronously via `entityReady` or `loadEntity`. > > 📘 **`_uid`** — The anonymous visitor identifier stored in the browser cookie (default cookie name: `seerid`). It is the foundation of anonymous profile continuity and is present on every tag send. > > 📘 **`loadEntity`** — An explicit SDK call that triggers retrieval of the current visitor's entity payload from Lytics. Use it when route context changes require a profile refresh; it is distinct from `entityReady`, which passively listens for entity loads. > > 📘 **Identity Fragment** — A unit of profile evidence associated with one identity key/value pair. Fragments are created or updated each time the tag sends an event carrying a recognized identifier, and are stitched together when events carry multiple identifiers. > > 📘 **Consent Blocking** — The SDK mechanism (`optIn` / `optOut`) that starts or stops event collection based on the visitor's consent state. When `optOut` is called, sends are halted and tag cookies are cleared. > > 📘 **`sessecs`** — The session cookie TTL setting in `jstag` configuration (default: 1800 seconds). It controls when a new session is recorded after a period of inactivity. #### Key takeaways - Connect **Tag** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 07 — Schema #### Lesson text Schema is the translation layer between raw event data and usable profile attributes. Without schema configuration, data arrives in Lytics but has no structure — identifiers go unrecognized, fields go unpopulated, and profiles remain empty shells. This module covers the full schema lifecycle: navigating the Schema Manager, defining profile fields, writing mapping expressions, maintaining a data dictionary, using advanced LQL functions, organizing fields with categories, understanding the universal and common schema layers, and validating changes safely before they reach production. ## Overview and Navigation ### Learning Objectives By the end of this section, you will be able to: \- Explain what the Schema Manager does and why it is central to data processing in Lytics \- Navigate the Schema Manager UI confidently, including search, filtering, and field detail views \- Understand the relationship between streams and schema, and how incoming data maps to profile fields ### Schema Manager Overview Schema is the translation layer between raw event data and usable profile attributes. In Lytics, your **Fields**, **Mappings**, and **Ranks** define how profiles are materialized and stitched over time. Schema work is organized under **Building Profiles > Schema**, which exposes these areas: \- **Versions** \- **Fields** \- **Mappings** \- **Ranks** \- **Visualization** \- **Simulate** \- **Schema Audit** A schema version — a staged draft of field, mapping, and ranking changes that can be validated and published atomically — is how Lytics controls schema changes before they affect live processing. You accumulate edits in a single draft, validate the full set, and publish them together. Changes published in one version only affect events processed after that publish; historical data is not retroactively reprocessed. #### Key Concepts * **Schema-first operations**: fields and mappings should be defined before new stream payloads scale up. * **Draft vs published state**: changes are staged in draft and only affect processing after publish. * **Mapping-time behavior**: mappings apply at ingestion time; they do not retroactively backfill old events. * **Operational visibility**: Schema Audit and Visualization help detect gaps, unused fields, and source mismatch. #### Step-by-Step 1. Open **Building Profiles** > **Schema** and review current **Versions**. 2. Confirm whether you have unpublished changes. 3. Open **Fields** and verify key identifiers and business attributes exist. 4. Open **Mappings** and inspect active stream-to-field expressions. 5. Use **Schema Audit** to identify fields with no coverage or no audience usage. 6. Document priorities before editing (new fields, mapping fixes, rank updates). #### Examples * You ingest web events in `default` and CRM events in `salesforce`; schema maps both to one canonical `email` field. * You maintain one profile field `purchase_total` while multiple streams contribute values with appropriate merge operators. ![Schema Manager showing the Versions, Fields, Mappings, and Ranks navigation tabs with an active draft version visible.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am92d279cefd0612c2/1977d461a33b652a1044674c/schema_manager_versions_fields_mappings.png) ### Summary Schema is the mechanism by which Lytics transforms raw event payloads into structured profile attributes. The Schema Manager organizes this work into versioned drafts that you validate before publishing. The key areas — Fields, Mappings, Ranks, Visualization, and Schema Audit — cover the full lifecycle of schema design, monitoring, and maintenance. Changes only affect events processed after publish; historical data is not retroactively reprocessed. ### Documentation Links * [Schema Overview](https://docs.lytics.com/docs/schema-overview) * [Schema Manager](https://docs.lytics.com/docs/schema-manager) ## Profile Fields ### Learning Objectives By the end of this section, you will be able to: \- Identify the field types available in Lytics (string, number, boolean, date, list, map, etc.) \- Create and manage profile fields, including setting display names, descriptions, and visibility \- Understand field naming conventions and their impact on downstream usage in audiences and exports ### Working with Profile Fields Fields are the profile attributes you segment on, export, and personalize against. Field design decisions — type, merge operator, capacity, retention, identity key status, PII flag — directly affect quality and performance across every downstream system. Core data types include: \- Standard: `string`, `integer`, `number`, `boolean`, `date` \- Collection/advanced: `[]string`, `[]time`, `ts[]string`, `map[string]...` Field properties you should set intentionally: \- **Merge operator** (`latest`, `oldest`, `min`, `max`, `merge`, `sum`) \- **Identity key** (true only for identifiers used in stitching) \- **Keep days** and **capacity** (for retention and set/map growth control) \- **PII flag** for governance workflows #### Key Concepts * **Field IDs are contract keys**: keep IDs stable and implementation-safe (`snake_case`, no ambiguity). * **Type must match expression output**: mapping errors often come from type/output mismatch. * **Merge operator is business logic**: choose based on meaning, not convenience. * **Capacity and retention are controls**: avoid unbounded growth in set/map fields. #### Step-by-Step 1. In **Schema > Fields**, click **Create New**. 2. Define `ID`, short description, type, and long description. 3. Set category, merge operator, and identity key status. 4. Configure keep-days/capacity where applicable. 5. Mark PII fields correctly. 6. Save field and add it to your data dictionary. #### Examples ```text Field ID: first_purchase_at Type: date Merge operator: minimum Reason: always preserve earliest purchase timestamp ``` ```text Field ID: consent_flags Type: map[string]bool Merge operator: merge Reason: maintain current purpose-level consent key/value states ``` ![Field creation dialog showing the data type dropdown, merge operator selection, and identity key/PII flag settings.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am168fc4da61fd23af/65653f6f57f4e8908a5303dc/field_creation_dialog_data_type.png) ### Summary Profile fields are the schema's data model — each definition specifies its ID, type, merge operator, and governance properties. Field IDs must be stable because downstream audiences and exports depend on them. Choosing the right merge operator at creation time is critical: changing it later on a live field can corrupt accumulated data. For set and map types, always configure `keep_days` and `capacity` to prevent unbounded growth on active profiles. ### Documentation Links * [Schema Fields](https://docs.lytics.com/docs/schema-fields) * [Merge Operators](https://docs.lytics.com/docs/merge-operators) ## Mapping ### Learning Objectives By the end of this section, you will be able to: \- Map raw event fields from incoming streams to profile fields in the schema \- Configure mapping rules including merge strategies (set, append, sum, etc.) \- Validate that mappings are working correctly by inspecting profile data after ingestion ### Configuring Schema Mappings Mappings connect stream payload keys to profile fields and can transform, filter, and conditionally write values. They are defined per stream. Mapping model: \- **Stream**: where source event arrives \- **Expression**: what value to produce \- **Condition**: when to apply expression \- **Target field**: where value is stored Important operational rule: mapping changes affect events processed after publish; they do not reprocess historical data automatically. #### Key Concepts * **Expression vs condition**: compute value in expression, gate writes in condition. * **Identity mappings are foundational**: ensure `_uid`, `email`, and other chosen keys map consistently. * **Multiple mappings can feed one field**: merge operator resolves write conflicts. * **Draft validation before publish**: prevent bad mapping deploys. #### Step-by-Step 1. Open **Schema > Mappings** and create a new mapping. 2. Choose source stream (for example `default`, `crm_import`, `orders_api`). 3. Define expression using raw keys (wrapped in backticks in advanced syntax). 4. Add condition if mapping should only fire on specific event patterns. 5. Save mapping and run schema validation. 6. Publish draft version and test with live events. #### Examples ```text Expression: oneof(`email_address`, `email`) Condition: exists(`email_address`) OR exists(`email`) Target field: email ``` ```text Expression: count(`event_type`) Condition: eq(`event_type`, "page-view") Target field: pageview_count ``` ![Mapping editor showing the stream selector, expression input, condition field, and target field dropdown for an active mapping.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am190ccabb324a3877/e5db52ac7bbe06b8a765793e/mapping_editor_stream_selector_expression.png) ### Summary Mappings are the bridge between raw stream events and profile fields. Each mapping specifies a source stream, an LQL expression that computes the value, an optional condition that gates when the mapping fires, and a target profile field. Because mappings are forward-looking — they do not reprocess historical events — defining them before data volumes scale up is the correct implementation order. Draft validation before publish catches expression errors and type mismatches before they affect live profiles. ### Documentation Links * [Schema Mappings](https://docs.lytics.com/docs/schema-mappings) * [LQL Reference](https://docs.lytics.com/docs/lql) ## Data Dictionary ### Learning Objectives By the end of this section, you will be able to: \- Build and maintain a schema data dictionary that documents field purpose, source, and ownership \- Track dependencies between fields, mappings, audiences, and downstream destinations \- Establish governance rules for introducing, deprecating, and removing fields safely ### Building and Maintaining a Data Dictionary A schema dictionary is your implementation control plane. It reduces rework, prevents duplicate fields, and makes impact analysis possible before changes. Minimum dictionary columns: \- Field ID \- Business meaning \- Data type and merge operator \- Source streams and mapping IDs \- Identity key / PII flags \- Owning team \- Downstream dependencies (audiences, reports, exports) \- Lifecycle status (`active`, `deprecated`, `to_delete`) #### Key Concepts * **Schema and dictionary must stay in sync**: drift causes false assumptions in campaign logic. * **Dependency tracking prevents regressions**: never delete fields blindly. * **Lifecycle labeling enables safe cleanup**: deprecate first, delete later. * **Audience usage checks are mandatory**: use Schema Audit before field retirement. #### Step-by-Step 1. Export or manually inventory current schema fields and mappings. 2. Add business definitions and owners for each field. 3. Record source streams and mapping expressions. 4. Add all known audience/report/export dependencies. 5. Review monthly with data + activation owners. 6. Gate schema changes behind dictionary updates. #### Examples ```text Field: purchase_total Owner: Lifecycle Marketing Type/Merge: number/sum Sources: shopify_orders, warehouse_orders Used by: high_value_buyers audience, paid_social export filter Status: active ``` ![Data dictionary spreadsheet template showing field ID, business meaning, merge operator, source streams, downstream dependencies, and lifecycle status columns.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amb4a177dbd8cc813c/0c28dcb6482c8b4dce4e7330/data_dictionary_spreadsheet_template_field.png) ### Summary A data dictionary is the implementation control plane for schema. It records every field's purpose, type, merge operator, source streams, owning team, and downstream dependencies. Without it, schema changes become high-risk guesses — you cannot determine what audiences or exports depend on a field before modifying or removing it. Maintaining it requires discipline: gate all schema changes behind dictionary updates and review it monthly with the teams who own data and activation. ### Documentation Links * [Schema Management](https://docs.lytics.com/docs/schema-management) * [Schema Audit](https://docs.lytics.com/docs/schema-audit) ## Advanced Mapping Functions ### Learning Objectives By the end of this section, you will be able to: \- Use built-in mapping functions to normalize, transform, and enrich incoming values \- Combine expressions and conditions to create context-aware mappings \- Evaluate expression outputs before publishing schema changes ### Advanced Mapping Techniques Lytics supports many built-in LQL functions so you can transform data at ingestion without external preprocessing for simple cases. Common high-value functions: \- `oneof(...)` for fallback key resolution \- `join(...)` for composite strings \- `replace(...)` for normalization \- `split(...)` + `set(...)` for string-to-set conversion \- `len(...)` for size/length metrics \- conditional writes with `eq`, `exists`, and logical combinators #### Key Concepts * **Use transformation where it belongs**: simple cleansing in mapping, heavy ETL in pipeline/warehouse. * **Conditions prevent noisy writes**: avoid polluting fields with irrelevant events. * **Function composition is expected**: nested functions are common in production mappings. * **Test expressions directly**: use expression evaluation endpoints before publish. #### Step-by-Step 1. Start from the target field definition (type + merge semantics). 2. Write the simplest expression that satisfies output requirements. 3. Add conditions to scope writes to valid events. 4. Test using example payloads in schema evaluation. 5. Validate full schema draft. 6. Publish and monitor output fields in audit/profile views. #### Examples ```text Expression: join(`street`, `city`, `state`, ", ") Output: "698 Candlewood Lane, Cabot Cove, ME" ``` ```text Expression: set(split(`favorite-genres`, "|")) Condition: exists(`favorite-genres`) Output type: []string ``` ```text Expression: replace(replace(path(`url`), "/"), "-", " ") Output: normalized page topic text ``` ![Mapping editor showing a nested LQL function expression with a condition filter, illustrating function composition in a production mapping.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am69c958a6732e0334/aac5d874f86c7facf97deb01/mapping_editor_nested_lql_function.png) ### Summary Lytics' built-in LQL functions let you transform, normalize, and conditionally write values at ingestion time without upstream preprocessing. `oneof` handles multi-key fallback, `split` and `set` convert delimited strings into arrays, `join` builds composite fields, and condition expressions like `eq` and `exists` gate writes to relevant events. For complex transformations, test expressions against sample payloads before publishing — catch type mismatches early rather than discovering them in live profile data. ### Documentation Links * [LQL Functions](https://docs.lytics.com/docs/lql-functions) * [Mapping Expressions](https://docs.lytics.com/docs/mapping-expressions) ## Categories ### Learning Objectives By the end of this section, you will be able to: \- Use field categories to organize schema for discoverability and governance \- Apply category standards consistently across implementation teams \- Leverage categories to prioritize profile completeness and maintenance work ### Organizing Fields with Categories Categories provide semantic organization for large schemas and help teams reason about coverage and gaps. Lytics field creation supports category assignment directly. Common categories used in Lytics schema workflows include: \- **Identity** \- **Governance** \- **Interests** \- **Behavior** \- **First Party** \- **Intelligence** \- **Activation** #### Key Concepts * **Categories are operational metadata**: they improve search, onboarding, and ownership clarity. * **Governance fields should be explicit**: consent/privacy fields should not be mixed into generic categories. * **Identity category must stay tight**: only actual stitch keys belong there. * **Category consistency enables audits**: easier to review profile readiness by domain. #### Step-by-Step 1. Define a category policy shared across implementation, data, and marketing teams. 2. Review existing fields and backfill missing categories. 3. Enforce category assignment in every new field request. 4. Use category views during quarterly schema audits. 5. Track coverage per category in your data dictionary. 6. Escalate uncategorized critical fields as hygiene issues. #### Examples * `email`, `_uids`, `external_id` → **Identity** * `consent_flags`, `gdpr_opt_in_status` → **Governance** * `score_momentum`, `segment_prediction` → **Intelligence** * `purchase_total`, `last_order_date` → **First Party** ![Schema Fields view filtered by category, showing a list of Identity-category fields with their field IDs, types, and merge operators.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amc9770f2cd222d6f9/51314dff968fa4871eb073d2/schema_fields_filtered_category_identity.png) ### Summary Field categories are semantic labels that organize schema for discoverability and governance. Without them, large schemas become difficult to audit and maintain — teams cannot quickly identify which fields are identity keys, which require consent governance, or which are unused. Assign categories at field creation time, enforce them consistently, and use category filters during quarterly schema audits to assess coverage and surface uncategorized fields. ### Documentation Links * [Schema Fields](https://docs.lytics.com/docs/schema-fields) * [Profile Field Categories](https://docs.lytics.com/docs/field-categories) ## Common Schema Expanded ### Learning Objectives By the end of this section, you will be able to: \- Distinguish universal schema attributes from common schema attributes \- Identify key default identifiers and intelligence fields available in Lytics \- Apply common schema conventions to speed implementation and activation ### Deep Dive into Common Schema Lytics profile modeling includes two schema layers covered in detail in [Profile](/academy/courses/lytics-course/profile#common-schema): \- **Universal schema**: system-level profile metadata and model-driven attributes present across all profiles. \- **Common schema**: standardized business-facing fields and mappings intended to normalize cross-source data. Important universal/common fields you should know: \- Core IDs and metadata: `_id`, `_created`, `_modified`, `_num_events`, `_streamnames` \- Identity and stitch keys: `_uids`, `email`, `email_sha256`, `external_id` \- Audience/intelligence: `_segments`, `_split`, `_split2`, `segment_prediction`, `segment_prediction_percentile` \- Interest modeling: `lytics_content`, `hashedurls` #### Key Concepts * **Universal schema is always-available context**: useful for diagnostics, audience health, and experimentation. * **Common schema reduces integration entropy**: map source-specific keys into canonical field names. * **Identifier hygiene is non-negotiable**: ID fields are the backbone of profile unification. * **Predictions should be consumed intentionally**: use score and percentile fields for explicit modeled audiences. #### Step-by-Step 1. Inventory your currently surfaced universal/common fields. 2. Confirm identifier fields and ranks match your identity strategy. 3. Map source-specific keys into canonical common-schema fields. 4. Validate audience logic against canonical fields, not raw source keys. 5. Review model score fields and percentile usage for lookalike/predictive cases. 6. Standardize downstream exports on canonical field names. #### Examples ```text Raw source variants: - crm_email - emailAddress - customer.email Canonical common schema target: - email ``` ```text Experiment audience using universal random split: - _split < 10 => random 10% holdout group ``` ![Schema Fields view showing universal schema fields (identifiers, behavioral scores, intelligence fields) alongside common schema fields, with their categories labeled.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amd7c50bf7b0dba348/9e4274c2637e47c811649f6e/schema_fields_universal_common.png) ### Summary The universal and common schema layers eliminate the need to define from scratch the fields that every account needs. The universal schema provides system-computed attributes — identifiers, behavioral scores, audience memberships, and experiment splits — automatically on every profile. The common schema normalizes business-facing contact fields across integrations. During implementation, the priority is mapping source-specific field names into canonical common schema fields so that audience logic and exports operate on stable, predictable names rather than source-dependent variants. ### Documentation Links * [Common Schema Fields](https://docs.lytics.com/docs/common-schema) * [User Schema](https://docs.lytics.com/docs/schema) ## Testing Schema ### Learning Objectives By the end of this section, you will be able to: \- Validate schema drafts before publish using both UI and API workflows \- Diagnose mapping and type errors quickly using controlled test payloads \- Execute safe publish/revert practices for schema changes in production ### Validating and Debugging Schema Production schema operations should follow a strict test pipeline: 1\. expression testing, 2\. draft validation, 3\. controlled publish, 4\. post-publish verification. Lytics supports draft workflows (including **Publish Changes** and **Discard Changes**) and schema version history. API endpoints also support validation and expression evaluation (`validate schema`, `evaluate expression`) for automation. #### Key Concepts * **Validate before publish**: catch broken mappings, missing fields, and type mismatches. * **Version discipline**: every publish should have a clear description and rollback path. * **No implicit backfill**: published mapping changes only impact new ingestion. * **Audit immediately after publish**: confirm expected profile field coverage and audience behavior. #### Step-by-Step 1. Prepare test events that cover happy path and edge cases. 2. Evaluate risky expressions with schema expression evaluation tools. 3. Run schema draft validation. 4. Review version diff and publish with a descriptive change note. 5. Verify new events populate expected fields. 6. If regression appears, revert to prior schema version and investigate. #### Examples ```bash # Conceptual validation flow (v2 API) GET /v2/schema/{table}/validate POST /v2/schema/expression/evaluate ``` ```text Publish checklist: - field changes reviewed - mapping changes reviewed - rank changes reviewed - downstream impact confirmed ``` ![Schema version history view showing a published version with change description, alongside the Publish Changes and Discard Changes controls.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ama99a1960d7d2e17f/818f40e627ff9f98eef67919/schema_version_history_published_version.png) ### Summary Schema changes carry production risk because mappings are forward-only — there is no automatic backfill when you fix a broken mapping. The safest workflow is: test individual expressions against sample payloads, run draft validation to catch structural errors, publish with a descriptive version note, and immediately audit profile coverage post-publish. Lytics' version history gives you a rollback path if a change introduces regressions. Treat every schema publish as a production deployment: validate, document, and monitor. ### Documentation Links * [Schema Validation](https://docs.lytics.com/docs/schema-validation) * [Schema API Reference](https://docs.lytics.com/reference/schema) ## What You've Learned Schema is the foundational configuration layer between raw event data and the profile attributes that power every Lytics feature. You've worked through the full schema lifecycle: navigating the Schema Manager and understanding how versioned drafts stage changes before publish; designing profile fields with the correct data types, merge operators, and retention settings; writing LQL mapping expressions that connect stream payloads to profile fields; maintaining a data dictionary that tracks ownership and downstream dependencies; using built-in LQL functions for data transformation at ingestion; organizing fields with categories for discoverability and governance; understanding how the universal and common schema layers provide out-of-the-box intelligence and canonical field names; and validating schema changes safely before they affect live data. ### Key Terms > 📘 **Schema** — The configuration layer in Lytics that defines how raw event data from streams is translated into structured profile fields. Consists of field definitions, mapping expressions, and identity key rankings. > > 📘 **Schema Version** — A staged draft of field, mapping, and ranking changes that can be validated and published atomically. Changes only affect events processed after the version is published. > > 📘 **Field (Profile Field)** — A named attribute on a Lytics profile with a defined data type, merge operator, and optional retention settings. Fields are the units that audiences, exports, and personalization rules operate on. > > 📘 **Merge Operator** — The rule that determines how conflicting values for a field are resolved when data arrives from multiple sources. Common operators: `latest` (keep newest), `oldest` (keep first), `sum` (accumulate), `merge` (union of sets). > > 📘 **Mapping** — An LQL expression assigned to a source stream that computes a value and writes it to a target profile field. Mappings can include conditions to gate writes to specific event patterns. > > 📘 **LQL (Lytics Query Language)** — The expression language used to write schema mapping expressions, audience conditions, and computed field logic. Supports field references, transformation functions, and boolean conditions. > > 📘 **Schema Audit** — A Lytics UI tool that surfaces schema health signals: fields with no event coverage, fields unused by any audience, and streams with no active mappings. > > 📘 **Data Dictionary** — An external documentation artifact that records the business definition, data type, merge operator, source streams, owning team, and downstream dependencies for every schema field. The primary tool for safe schema governance. > > 📘 **Identity Key** — A field designated as a profile stitching identifier. When a new event carries an identity key value that matches an existing profile, the event is merged into that profile. Changing identity keys on a live account affects profile merges globally. #### Key takeaways - Connect **Schema** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 08 — Integrations & Connections #### Lesson text Lytics connects to the rest of your marketing and data stack through a combination of prebuilt provider integrations, warehouse connections, and API-based exchange patterns. This section covers the full integration surface: how to authorize external systems, control what data flows out of Lytics and to whom, query warehouse data directly via Cloud Connect, and interact with profiles programmatically through the Attributes, Collect, and Personalize APIs. By the end, you will be able to configure, monitor, and troubleshoot every major integration pattern in the platform. ## Overview ### Learning Objectives By the end of this section, you will be able to: \- Explain what integrations do in Lytics and why they are essential for data collection and activation \- Distinguish between import integrations (data in) and export integrations (data out) \- Navigate the integrations page, including viewing active connections, statuses, and configuration details ### Integrations in Lytics Integrations are how Lytics exchanges data with external systems. A connection — a configured link between Lytics and an external system or warehouse, with provider-specific settings and authorization — is the foundational unit of this exchange. Practically, this includes: \- importing data into Lytics, \- enriching profiles, \- exporting audiences/profile attributes/events to downstream tools. You will work across these product surfaces: \- **Data Pipeline > Jobs** for most import/export integrations \- **Cloud Connect** for warehouse-backed connections and SQL-driven data models \- **Account > Security > Authorizations** for credential management #### Key Concepts * **Import vs export**: import builds profile context; export activates decisions. * **Job lifecycle**: integrations run as jobs with statuses like running, sleeping, failed, paused, completed. * **Schema dependency**: downstream activation quality depends on upstream field mapping quality. * **Operational observability**: summaries and logs are required for troubleshooting and change control. #### Step-by-Step 1. Inventory required systems by use case (analytics, ESP, ads, CRM, warehouse). 2. Decide per system whether you need import, export, enrichment, or bidirectional flows. 3. Create required authorizations first. 4. Configure connection/job with explicit naming conventions and descriptions. 5. Validate logs and output payloads before campaign go-live. 6. Set ownership and monitoring cadence for each active integration. #### Examples * Import events from server systems into Lytics to enrich profiles. * Export audience membership changes in real-time to a webhook endpoint. * Query warehouse data with Cloud Connect and map output into profile attributes. #### Diagrams & Screenshots ![Integrations landscape across Jobs, Cloud Connect, and Authorizations.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am4d037ec328ffaa7a/17496303b1cd4009ce3f3548/integrations_landscape_jobs_cloud_connect.png) ### Summary Integrations are the mechanism through which Lytics exchanges data with the rest of your stack. Import integrations build profile context; export integrations activate that context in downstream tools. Before configuring any job, you inventory the systems involved, create the necessary authorizations, and then set up and validate each connection. Logs and summaries are your primary operational tools for ongoing health monitoring. ### Documentation Links * [Integrations Overview](https://docs.lytics.com/docs/integrations) * [Data Pipeline Jobs](https://docs.lytics.com/docs/data-pipeline) ## Authorizations ### Learning Objectives By the end of this section, you will be able to: \- Configure OAuth authorizations to connect Lytics with third-party platforms securely \- Manage API key credentials, including creation, scoping, and storage best practices \- Understand authorization security best practices such as least-privilege access and credential rotation ### Managing Integration Authorizations Authorizations are reusable credential objects used by jobs and connections. In Lytics, authorizations are managed centrally in **Account > Security > Authorizations** and then selected during job/connection setup. Supported auth styles vary by provider: \- API keys \- OAuth variants \- user/password or token-based methods \- webhook-specific auth modes (no auth, header/parameter auth, OAuth client credentials) #### Key Concepts * **Authorization health**: Lytics tracks auth health (healthy/unhealthy/unknown) to surface risk early. * **Reuse with care**: one authorization can back multiple jobs; changes have broad impact. * **Immutable config pattern**: when core credentials must change, create a new authorization and migrate jobs. * **Least privilege**: grant only required scopes/tables/actions. #### Step-by-Step 1. In **Account > Security > Authorizations**, create a new authorization. 2. Select provider and method required by the target integration. 3. Add clear label/description identifying owner and purpose. 4. Enter credentials and save. 5. During job/connection setup, select this authorization. 6. Monitor health and rotate credentials on schedule. #### Examples ```text Provider: Webhooks Method: OAuth 2.0 Client Credentials Grant Outcome: Lytics requests access token and sends webhook calls with Bearer token ``` ```text Provider: Cloud Connect warehouse Method: provider-specific API/JWT credentials Outcome: Data models can query only authorized datasets/tables ``` #### Diagrams & Screenshots ![Authorization creation wizard showing provider and method selection.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am5adcb9e988f635e9/d7a1b5c95067ec410516f3ce/authorization_creation_wizard_provider_method.png) ### Summary Authorizations are the credential layer that jobs and connections draw from. Managing them centrally in **Account > Security > Authorizations** means credential updates propagate to every dependent job at once — a powerful pattern that also means changes have broad impact. Apply least-privilege scoping at creation time, monitor authorization health proactively, and establish a rotation schedule for all API keys and OAuth tokens. ### Documentation Links * [Managing Authorizations](https://docs.lytics.com/docs/authorizations) * [Security Settings](https://docs.lytics.com/docs/security) ## Destination Filters ### Learning Objectives By the end of this section, you will be able to: \- Configure destination filters to control which fields and records are sent to export destinations \- Control which profile data is exported to ensure only relevant information reaches each platform \- Use destination filters to meet compliance requirements such as GDPR, CCPA, and consent management ### Controlling Data Export with Destination Filters Destination filtering is how you constrain outbound payloads and recipients. In practice, this can include: \- selecting specific profile fields for export, \- excluding users in disallowed audiences, \- restricting trigger windows and event types, \- applying template-level output shaping. Lytics also supports segment exclusion operations for export workflows, allowing you to add/remove a segment from an export exclusion list. #### Key Concepts * **Scope minimization**: export only fields required by the destination contract. * **Policy enforcement**: combine consent audiences with exclusion filters. * **Job-specific controls**: each destination has different filtering knobs; standardize patterns internally. * **Field-level governance**: avoid sending PII unless explicitly required and approved. #### Step-by-Step 1. Define outbound contract per destination (required IDs + allowed fields). 2. Configure job-level field selection and filters. 3. Add exclusion audiences for non-eligible users. 4. Validate payload shape in test or logs. 5. Reconcile destination acceptance/match metrics. 6. Review filters quarterly for compliance drift. #### Examples ```text Segment exclusion API pattern: POST /v2/segment/exclude/{operation}?workflow={workflow_slug}&segment_id={segment_id} operation: add | remove ``` ```text Webhook export: send only first_name, email, and segment_events instead of full profile payload. ``` #### Diagrams & Screenshots ![Destination filtering pattern with allowlist fields and exclusion audiences.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am96484b7acac52307/2dee2ce740beb04c632c2340/destination_filtering_pattern_allowlist_fields.png) ### Summary Destination filters give you precise control over what leaves Lytics and who receives it. Field selection limits exposure to only what each destination requires; audience exclusions enforce consent and suppression policies. Validate payload shape in logs before go-live and revisit filters quarterly to catch compliance drift as your data model and regulatory obligations evolve. ### Documentation Links * [Destination Filters](https://docs.lytics.com/docs/destination-filters) * [Audience Exclusions](https://docs.lytics.com/docs/audience-exclusions) ## Cloud Connect ### Learning Objectives By the end of this section, you will be able to: \- Explain how Cloud Connect uses warehouse queries to enrich profiles and audiences \- Create and manage warehouse connections securely \- Understand Cloud Connect architecture and common operational use cases ### File-Based Data Exchange with Cloud Connect Cloud Connect lets you run SQL directly against supported warehouses and map resulting records into Lytics profiles/audiences without replicating your full warehouse into Lytics. Supported providers include common enterprise warehouses such as BigQuery, Snowflake, Redshift, Databricks, and Azure SQL variants (availability may vary by account setup). In-product structure: \- **Connections** define warehouse access \- **Data Models** define SQL logic and materialization behavior #### Key Concepts * **Warehouse remains source of truth**: query only what you need for activation. * **Authorization governs table visibility**: connection access is bounded by auth permissions. * **Cost awareness matters**: query volume and row scans can impact warehouse cost. * **Model-driven enrichment**: Cloud Connect enables complex joins/time-window logic before activation. #### Step-by-Step 1. Open **Data Pipeline > Cloud Connect > Connections**. 2. Create connection (provider, type, authorization, config). 3. Validate table visibility in the **Explore** tab. 4. Create data model with SQL query. 5. Map model output into schema fields/audiences. 6. Monitor connection/model logs and query volume. #### Examples * Build `inactive_30_days` by querying last\_login timestamps in warehouse. * Join account + user tables for B2B audience criteria. * Compute LTV rollups and map to `lifetime_value` field for downstream activation. #### Diagrams & Screenshots ![Cloud Connect flow from warehouse query to profile enrichment.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am35a98e09daf4e6a8/5779b5a64bd97c42f59a0544/cloud_connect_flow_warehouse_query.png) ### Summary Cloud Connect bridges your warehouse and Lytics without full data replication. You define a connection with the appropriate authorization, write a SQL data model that extracts exactly the rows and columns you need, and map the output into profile attributes or audience membership. Keep query scope narrow to manage warehouse costs, and monitor model logs and query volume as data scales. ### Documentation Links * [Cloud Connect Overview](https://docs.lytics.com/docs/cloud-connect) * [Cloud Connect Data Models](https://docs.lytics.com/docs/cloud-connect-data-models) ## Attributes API ### Learning Objectives By the end of this section, you will be able to: \- Use the Attributes API to retrieve and update profile attributes programmatically \- Choose between full replacement and partial update semantics \- Apply identity-key-based profile addressing safely in API workflows ### Profile Enrichment via the Attributes API The Attributes API supports CRUD-style operations on profile attributes addressed by table + identity key + identity value. Endpoint pattern: \- `/v2/attributes/{table}/{field}/{value}` Common methods: \- `GET` profile attributes \- `PUT` replace/update all supplied attributes \- `PATCH` partial update \- `DELETE` remove profile attributes #### Key Concepts * **Identity addressing**: correctness depends on stable identity keys (`email`, `_uid`, etc.). * **PATCH vs PUT semantics**: PATCH for targeted updates; PUT when replacing a broader attribute set. * **Merge behavior**: use `mergeExisting` when needed to avoid destructive overwrites. * **Operational safeguards**: validate payloads and rate-limit upstream callers. #### Step-by-Step 1. Select the table (`user` in most implementations). 2. Select identity key/value pair to target profile. 3. Use `GET` first to inspect current state. 4. Apply `PATCH` for incremental enrichment updates. 5. Verify response and downstream schema/audience effects. 6. Monitor error responses for key/value mismatches. #### Examples ```http GET /v2/attributes/user/email/person@example.com ``` ```http PATCH /v2/attributes/user/email/person@example.com?mergeExisting=true Content-Type: application/json { "loyalty_tier": "gold", "external_audiences": ["spring_campaign"] } ``` #### Diagrams & Screenshots The diagram below traces a realistic enrichment scenario: an external system (a CRM, a backend service, or a batch job) needs to push a single new attribute — a loyalty tier — onto an existing Lytics profile without touching any of the other data on that profile. Follow it left to right: 1. **The calling system** addresses the profile by table + identity key + value (`user` + `email` + `person@ex.com`). This is how Lytics finds "the right profile" regardless of what platform is calling. 2. **GET** returns the profile's current attributes — first name, order count, whatever the tag and other integrations have already written. This step is optional but strongly recommended: it prevents you from overwriting something you didn't know was there. 3. **PATCH with `?mergeExisting=true`** sends the one field you want to add or update (`{"loyalty_tier": "gold"}`). Lytics merges it into the existing profile — every other field the profile already had is preserved. 4. **The profile** now carries `loyalty_tier: "gold"` alongside everything it had before. Downstream audiences, schema mappings, and exports re-evaluate automatically against the new state. The key mental model: **PATCH with `mergeExisting=true` is additive, not destructive.** Use it when your caller only knows about the fields it owns and shouldn't touch anything else. Use PUT (without mergeExisting) only when you deliberately want to replace a broader attribute set. ![Attributes API request flow: an external system GETs a profile's current attributes, then PATCHes a single new field (loyalty\_tier=gold) with mergeExisting=true; the profile ends up carrying both its original fields and the new one.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am6cf3ac6d37b3289c/1d07c14a2fea8486839a16ec/attributes_api_request_flow_get.png) ### Summary The Attributes API lets you read and write profile attributes by addressing profiles through a table, identity key, and identity value. Use `GET` to inspect current state before writing. Prefer `PATCH` with `mergeExisting=true` for incremental enrichment to avoid destructive overwrites. Validate that your identity keys are stable across systems, and monitor error responses for key/value mismatches as upstream data evolves. ### Documentation Links * [Attributes API](https://docs.lytics.com/docs/attributes-api) * [Profile API Reference](https://docs.lytics.com/docs/profile-api) ## Prebuilt Integrations ### Learning Objectives By the end of this section, you will be able to: \- Evaluate when to use a prebuilt integration versus custom integration options \- Configure common job types with the appropriate provider authorization and settings \- Monitor and troubleshoot prebuilt integration jobs using logs and status views ### Working with Prebuilt Integrations Lytics ships many prebuilt provider integrations across ad platforms, marketing automation, messaging, analytics, and data infrastructure. These reduce implementation time versus fully custom pipelines. A typical setup sequence: 1\. create authorization, 2\. create job, 3\. configure provider-specific options, 4\. validate logs, 5\. monitor health. #### Key Concepts * **Provider-specific behavior**: each connector has unique required fields, schedule behavior, and limits. * **Template and field mapping support**: many exports allow selectable fields or templating. * **Backfill vs real-time**: understand initial sync behavior and ongoing cadence. * **Operational ownership**: each live job needs owner, SLA, and alerting expectations. #### Step-by-Step 1. Identify target provider and intended use case. 2. Read provider integration doc for required auth method and job type. 3. Create authorization and job in Data Pipeline. 4. Configure source audience/fields/template as required. 5. Run test sync and validate provider-side receipt. 6. Promote to production and monitor logs. #### Examples * Export modeled audience to ad platform with hashed identifiers. * Sync segment events to messaging platform using webhook connector. * Import source-system events into Lytics for enrichment and segmentation. #### Diagrams & Screenshots ![Prebuilt integration workflow from auth to production monitoring.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am3ef85362f96624b1/c41f33931779d863480f950f/prebuilt_integration_workflow_auth_production.gif) ### Summary Prebuilt integrations cover the most common provider connections and significantly reduce setup time versus building custom pipelines. Each integration follows the same sequence: create the authorization, create and configure the job, validate via logs, and promote to production. Pay attention to provider-specific behavior around schedule cadence, required fields, and backfill behavior — these vary by connector and affect both initial sync quality and ongoing operational expectations. ### Documentation Links * [Prebuilt Integrations](https://docs.lytics.com/docs/integrations) * [Integration Job Configuration](https://docs.lytics.com/docs/integration-jobs) ## Webhook and Profile Templates ### Learning Objectives By the end of this section, you will be able to: \- Configure webhooks for audience-triggered payload delivery \- Use templates to reshape outbound payloads for destination-specific contracts \- Test and validate template output before enabling production jobs ### Custom Data Delivery with Webhooks and Templates Webhooks are a flexible server-side integration pattern for sending audience enter/exit/change events to external endpoints. Template support allows payload transformation before send: \- template types include `jsonnet` and `handlebars` \- templates can be created/listed via `/template` \- webhook jobs can reference template IDs for structured payload delivery #### Key Concepts * **Event-driven activation**: webhooks notify systems when user state changes. * **Payload contracts**: templates enforce destination-specific JSON shape. * **Auth options**: no auth, header/param auth, OAuth client credentials. * **Audience update caution**: if audience logic changes significantly, validate webhook behavior and replay strategy. #### Step-by-Step 1. Create webhook authorization with required method. 2. Create or select source audience. 3. Build template definition (jsonnet/handlebars) for destination contract. 4. Create webhook job and attach template. 5. Test with controlled audience events. 6. Validate endpoint responses and retry/error behavior. #### Examples ```text Template API: POST /template?name=insider_temp&type=jsonnet GET /template ``` ```json { "users": [ { "identifiers": { "email": "person@example.com" }, "attributes": { "lytics_segments": ["high_value"] } } ] } ``` #### Diagrams & Screenshots ![Webhook trigger with template transformation before destination POST.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am8c5be2a8c38e5031/1aec72ba2d7b3f9fe641ff1a/webhook_trigger_template_transformation_before.png) ### Summary Webhooks enable event-driven activation by notifying external endpoints when audience membership changes. Templates (in `jsonnet` or `handlebars`) reshape the outbound payload to match the destination's contract before the call is made. Always test with controlled audience events and validate endpoint responses, including retry and error handling behavior, before enabling a webhook job in production. ### Documentation Links * [Webhook Integrations](https://docs.lytics.com/docs/webhooks) * [Profile Templates](https://docs.lytics.com/docs/profile-templates) ## Collect API ### Learning Objectives By the end of this section, you will be able to: \- Send server-side events to Lytics using the Collect API \- Use stream strategy and identity fields correctly for profile stitching \- Implement resilient server-side event ingestion patterns ### Server-Side Ingestion with the Collect API The Collect API is the server-side ingestion endpoint for JSON events. It is the standard option when data should be sent from backend services instead of client-side tags. Endpoint: \- `POST /collect/json/{stream}` with required data API token Common required event fields for identity-oriented events include: \- `_e` event type/name \- `_uid` (if available) \- stable identifiers like `email` or customer ID #### Key Concepts * **Server-side reliability**: avoids browser blockers and client runtime failure modes. * **Identity bridging**: including `_uid` + known identifiers improves stitching. * **Stream discipline**: different streams may require dedicated mappings. * **Ingestion contracts**: validate payload shape and timestamp behavior. #### Step-by-Step 1. Select stream name and ensure schema mappings exist for that stream. 2. Capture required identity/event fields in backend flow. 3. Send JSON payload to collect endpoint with access token. 4. Handle non-200 responses with retries/backoff. 5. Verify ingestion in Lytics stream data and profile outcomes. 6. Monitor ingestion volume and error rates. #### Examples ```bash curl -X POST \ 'https://api.lytics.io/collect/json/default?access_token=YOUR_DATA_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "_e": "login", "email": "user@example.com", "_uid": "12345-67890-abcdef", "timestamp": "2026-02-16T10:30:00Z" }' ``` #### Diagrams & Screenshots ![Server authentication flow emitting login event to Collect API.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am95fb7dad9e71261b/48a278b419fc3b22434567f0/server_authentication_flow_emitting_login.png) ### Summary The Collect API is the primary server-side ingestion path for JSON events. POST to `/collect/json/{stream}` with a data API token, including `_e`, `_uid`, and any stable identity fields to support profile stitching. Implement retry/backoff logic for non-200 responses, and monitor ingestion volume and error rates in production to catch payload or mapping issues early. ### Documentation Links * [Collect API](https://docs.lytics.com/docs/collect-api) * [Server-Side Event Ingestion](https://docs.lytics.com/docs/server-side-events) ## Personalize API ### Learning Objectives By the end of this section, you will be able to: \- Retrieve user entity/profile data for personalization use cases \- Request only required fields and segment context for low-latency decisions \- Integrate Personalize API calls safely into server-side or edge decision flows ### Real-Time Personalization with the Personalize API The Personalize API exposes user entity data by identity key/value and is used by web personalization patterns and server-side decisioning. Core endpoint family — all paths perform the same entity retrieval: \- `/api/entity/{table}/{fieldname}/{fieldval}` — authenticated lookup (requires `Authorization` header) \- `/api/personalize/{accountid}/{table}/{fieldname}/{fieldval}` — public variant used by client-side personalization (no auth; account ID scopes the request) Common query options: \- `fields` include-list \- `segments` toggle \- `meta` toggle \- `fieldBlocklist` exclusion list The JS tag uses the `/api/personalize/{accountid}/...` public form under the hood when loading entity data client-side. #### Key Concepts * **Identity lookup correctness**: wrong key/value pair yields empty or wrong profile retrieval. * **Latency optimization**: request only required fields for runtime decisions. * **Audience-aware decisions**: segment membership can drive channel/content selection. * **Data minimization**: keep PII exposure bounded to true runtime need. #### Step-by-Step 1. Choose lookup key/value strategy (`_uid`, `email`, or stable first-party key). 2. Define minimal field list required for decisioning. 3. Call personalization endpoint and parse entity response. 4. Handle no-profile cases with fallback logic. 5. Apply decision and log attribution context. 6. Monitor response quality and lookup miss rates. #### Examples ```bash # Lookup by user_id curl -H "Authorization: $LIOKEY" \ "https://api.lytics.io/api/entity/user/user_id/user123?fields=first_name,segment_prediction_percentile&segments=true" ``` ```bash # Lookup by email curl -H "Authorization: $LIOKEY" \ "https://api.lytics.io/api/entity/user/email/person@example.com?fields=lytics_content,score_momentum" ``` #### Diagrams & Screenshots ![Personalize API lookup and decisioning flow with segment-aware response.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am792812e20e53de88/b141d13a7a4f3807b39d2e7b/personalize_api_lookup_decisioning_flow.png) ### Summary The Personalize API retrieves unified profile data at runtime for server-side and edge decisioning. Address profiles by table, field name, and field value; request only the fields you need to keep latency low and PII exposure minimal. Always implement fallback logic for no-profile cases, and monitor lookup miss rates to detect identity key mismatches before they degrade personalization quality in production. ### Documentation Links * [Personalize API](https://docs.lytics.com/docs/personalize-api) * [Entity API Reference](https://docs.lytics.com/docs/entity-api) ## What You've Learned You now have a complete picture of how Lytics connects to external systems — from the credential layer that underlies every connection, through the filtering controls that govern what leaves the platform, to the warehouse-native enrichment patterns of Cloud Connect and the API surface for programmatic profile interaction. You've seen how prebuilt integrations and webhooks handle the most common activation patterns, and how the Collect and Personalize APIs extend those patterns to server-side ingestion and real-time decisioning. Together, these capabilities form the integration foundation that makes your unified profile data actionable across every channel in your stack. ### Key Terms > 📘 **Connection** — A configured link between Lytics and an external system or warehouse, with provider-specific settings and authorization. > > 📘 **Authorization** — A reusable credential object (API key, OAuth token, etc.) managed centrally in Account > Security and referenced by jobs and connections. > > 📘 **Destination Filter** — A job-level control that limits which profile fields and which users are included in an export payload. > > 📘 **Cloud Connect** — A Lytics feature that lets you run SQL queries directly against supported data warehouses and map results into profile attributes or audiences without full data replication. > > 📘 **Attributes API** — A REST API for reading and writing profile attributes, addressed by table, identity key, and identity value. > > 📘 **Collect API** — The server-side JSON event ingestion endpoint (`POST /collect/json/{stream}`), used when data should be sent from backend services rather than client-side tags. > > 📘 **Personalize API** — A REST API that retrieves unified profile data by identity key/value for runtime personalization and server-side decisioning. > > 📘 **Webhook** — An event-driven integration pattern that sends audience enter/exit/change notifications to an external HTTP endpoint when user state changes. > > 📘 **Profile Template** — A `jsonnet` or `handlebars` template that reshapes the outbound payload of a webhook or export job to match a destination's required JSON contract. #### Key takeaways - Connect **Integrations & Connections** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 09 — Audience Building #### Video details #### At a glance - **Title:** Audience Building - **Duration:** 8m 19s - **Media link:** https://cdn.jwplayer.com/previews/xf4x1xiI - **Publish date (unix):** 1751454050 #### Streaming renditions - application/vnd.apple.mpegurl - audio/mp4 · AAC Audio · 113452 kbps - video/mp4 · 180p · 178p · 135487 kbps - video/mp4 · 270p · 268p · 146544 kbps - video/mp4 · 360p · 358p · 160778 kbps - video/mp4 · 406p · 402p · 167149 kbps - video/mp4 · 540p · 536p · 189812 kbps #### Timed text tracks (delivery) - **thumbnails:** `https://cdn.jwplayer.com/strips/xf4x1xiI-120.vtt` #### Video transcript will cover audience building, how to build audiences using the data in your Lytx account. What you will learn in this training, what types of data is available for audience segmentation, including the following data types. Existing audiences, content affinity using data science, campaigns or modals that are hosted within Lytx, and custom role, which is the custom data that has been configured into your account. You will also learn how to create and save an audience using the above attributes. The audience builder enables you to create segments of profiles based on a variety of attributes. For example, you can create an audience of recent site visitors, visitors with specific characteristics, or unknown profiles. With these targeting capabilities, you can create personalized user experiences and better performing campaigns. Clicking on the audiences tab opens the audiences main page. Here you'll see all existing audiences. The main audiences page shows the most recently modified audience at the top. It will also show you how many audiences are available and is searchable. You can view the properties of an existing audience by clicking on it. After you open the audience and it loads, you can click the gray pencil button in the upper right to edit or view an audience. If you don't want to make changes, just hit cancel. To create a new audience, go back to the audiences main page and click the green button in the upper right. You need to name your audience to be able to save it. This is a good time to check with your organization's naming conventions. The description field is optional but very useful. It is searchable from the audience main page. The slug field is how the audience will get passed to API enabled third party tools like Facebook. The slug or audience ID will automatically populate from the audience name using underscores for spaces. You can edit it if you do not want to pull from your name of your audience. The slug is how the audience will be labeled in other tools. So you can name it something specific if you want to control how it appears in downstream tools. We also recommend shorter slugs are better. If you want the audience to be available in API enabled third party tools, check the box for whitelist API. If you leave it unchecked but change your mind, you can edit the audience later. Under definition, you will select the criteria for this audience. There are four types of rule sets to select from. First, we'll look at custom rule. Custom rule allows you to segment on all the custom data that has been configured in your account. Examples are email address, total visits, geotargeting like state, last email click date, online purchase, and many more attributes. For example, here's how to add a rule for profiles whose email address you know. Email address exists. You can also look for state. If we want to look at the other attributes, you can add a new rule set. The campaign tab enables you to add rules based on whether a web visitor has been served a Lytx hosted experience or personalized campaign. For example, you can add a rule for all users who have been reached by a campaign. Those campaigns are controlled in the personalize and experiences tab. The content affinity tab allows you to create audiences based on what types of content your visitors are likely to be interested in. The content affinity tab pulls from the top 500 most prominent topics that have been scraped from your website, enabling you to create rules based on what types of content your visitors read about on your site. For example, you can create a rule based on profiles who have a high affinity for electronics. High affinity. You can also make custom. Let's go to high. Add condition. Let's go ahead and add another rule set. The existing audience tab is how you would add a pre-existing audience to a new audience. This tab contains all of the audiences that your team has built and saved in the account. You can add these audiences by selecting them and adding them as a rule. For example, add an existing audience titled computer enthusiast. Audience building logic is straightforward. You can add rules by clicking add new rule for as many rules as you want to use for this audience. This is a rule set of a combined set of attributes. Remember that if you have and selected as the operator, the audience will get smaller each time you add a new rule because the audience consists of users who have multiple qualities. If you flip the operator to or, the audience will contain all profiles with those attributes and keep adding to that audience, therefore making the audience larger. Keep in mind that if you want to separate the audience rule sets to contain a mix of and and or operators, you should add a new rule set like we've been doing here. To delete a rule, scroll over the row that the rule appears and click the red delete this rule text. This delete this rule button is hidden until you scroll over it. When you're ready to save your audience, go ahead and hit create. This will now open the audience main page which will show you total profiles and in the audience, the percentage of your total audience, and the changes over time. Thanks for listening. Future modules will show you how to activate on the audiences that you've created. #### Lesson text Gain a baseline understanding of Lytics audiences and how to use the audience builder. ## Introduction ### Introduction to Audiences **Note:** On January 10, 2023, we upgraded our UI with a new, refreshed interface. All of the underlying functionality is the same, but you will notice that things look a little different from this Academy guide. The most notable change is that the navigation menu has moved from the top of the app to the left side. We appreciate your patience as we work on updating our Academy. #### What will I learn? * What are audiences? How are they used in Lytics? * What types of data are available for audience segmentation? * How can I create and save an audience in the Lytics UI? * What out-of-the-box audiences are available in Lytics? * Helpful hints to keep in mind while building audiences Audiences are critical to unlocking the full potential of Lytics. The Lytics audience builder is a powerful tool. All of your custom fields, data science scores, content affinities and other segments are available to create extremely targeted audiences. **What is the difference between an audience & a segment?** Nothing! We use the term "audience" & "segment" interchangeably Audiences are: * Groups of users defined based on specific criteria, or filters. * Central to using Lytics when creating personalized marketing initiatives. * Used to target and define how cross-channel user data is used in campaigns. * A tool that operates on user fields as well as other audiences. * Capable of targeting just one user, every user, or any number in between. In the next section, we will go over the basic UI navigation to prepare you to start building audiences. ### Navigating the UI In the Lytics app, you will find all existing audiences and create new ones in the **Audiences** tab. To start building your own audiences, click the **Create New Audience** button in the upper right corner of the UI. By default, audiences will show in order of "Last Modified Date". You can use the search bar to look up any specific audience name.  You can also organize your list of audiences alphabetically and by whether or not they are API enabled. By default, Lytics audiences are **not API enabled**. **When do I need to API enable my audience?** Enabling API access allows audience membership to be sent to your website. It is also necessary when integrating with other client-side tags/ pixels, or the Lytics personalization API endpoints. Next, we will walk you through some examples of audience building in a tutorial video. ## Building Audiences in Lytics ### Video Tutorial Watch the tutorial video below (~8 mins) to learn the basics of building audiences in the Lytics UI. **Which of the following can you use to build audiences? Select all that apply.** A. Existing Audiences B. Content Affinities C. Raw Data D. Custom Rules Answer: A, B, D **By default, Lytics audiences are NOT enabled for API access.** A. True B. False Answer: A ### Audience Builder Tabs Now, we'll go over the different tabs of the Lytics Audience Builder and the variables available for segmentation. ![audience-builder-scores.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt3f9f9274ec8303b0/68655529b734d046be943a36/audience-builder-scores.png) #### Existing Audience This tab includes existing audiences and their size categorized by audience type such as characteristics. * Characteristics: pre-built audiences pertaining to single user attributes such as location or behavior. #### Content Affinity This tab is used to add Affinity-based rules to your audience. Since Affinities are a group of related Topics, you can effectively target users interested in several subjects or products. If you are looking to update existing audiences based on Topics, or build new ones with a single Topic, you can do so under the **Custom Rule** tab. #### Campaign This tab is used to add rules regarding users' interactions with Lytics [Personalize Campaigns](https://learn.lytics.com/documentation/product/features/web-personalization/web-personalization-introduction) to your audience. For example, users who were reached or converted with a Lytics campaign. It's important to note that you can only create audiences for Personalize Campaigns (Legacy) in this tab, NOT Experiences. If you'd like to create an audience based on user interaction with an Experience you can do so in the Custom Rules tab. See [here](https://learn.lytics.com/documentation/product/features/audiences/building-audiences/experiences#building-audiences:-experiences) for more info. #### Custom Rule This tab is used to add any rule based on a [user field](https://learn.lytics.com/documentation/product/features/data-onboarding-and-management/user-fields) to the audience being built or edited. All user fields in the account will be under the Custom Rules Tab. Types of user fields can include: * Numeric - The number of times a user visited your site or opened an email * Text - First name (commonly used for miscellaneous information) * Date - When was the last time a user visited? * Set - All URLs visited by a user (commonly used for collecting related data over time) * Map/Nested - Events per device (i.e. Desktop, Mobile, Laptop) \*Add hierarchy to a dynamic domain of data If you'd like more info, check out our [Audience Building documentation](https://learn.lytics.com/documentation/product/features/audiences/building-audiences/overview). **Tip:** Are audiences updated in real time? Yes! When creating or editing an audience, you will always see real-time numbers so that you can make precise decisions based on accurate data (see screenshot below). ![audience-builder-real-time-count.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt8e78d5d82ef1d51a/6865552a4431706cfdfdb457/audience-builder-real-time-count.png) However, a caveat to note: audience sizes you see throughout the Lytics app (outside the Audience Builder) are updated every few hours for performance reasons.  Next we will go over the out-of-the-box audiences that are provided by Lytics. ### Out-of-the-Box Audiences Lytics will automatically create a handful audiences that are helpful for many marketing use cases. * **All** - All users in the account. * **Anonymous Profiles** - Those users who only have the Lytics Cookie ID and have not yet been stitched with other data sources. * **Behavioral Scores** - These scores each represent a distinct behavioral quality and can be composed to build rich audiences.  * Please note, users must have behavioral data to make confident measurements before they have scores. If a user was added to Lytics via email upload, for instance, they would have no scores.\*  * Since using Lytics [behavioral scores](https://learn.lytics.com/documentation/product/features/descriptive-and-predictive-modeling/lytics-scores) directly requires a level of understanding of the data science at play, Lytics also offers out-of-the-box "Behavioral Audiences." * **Behavioral Audiences** \-blends of scores that can be used alone or as a rule in a custom audience**.** * Examples: Frequent Users, Likely to Re-engage, At Risk Users, etc. * Read more about [behavioral audiences](https://learn.lytics.com/documentation/product/features/descriptive-and-predictive-modeling/behavioral-audiences#the-full-set-of-out-of-the-box-behavioral-audiences) *  **Custom Rules** such as "Last Active", "Devices Used", "Total Pageview Count" * See the full list of [out-of-the-box custom rules](https://learn.lytics.com/documentation/product/features/audiences/building-audiences/out-of-the-box-custom-rules#out-of-the-box-custom-rules) We'll cover Out-of-the-Box Audiences in more detail in other courses. Next, let's look at a few examples of audiences you may want to build in your account. ## Tips and Tricks ### Useful Audience Examples Here are some some examples of useful audiences you may want to build: * Anonymous to Known Users  * Anonymous users are those with a Web Cookie ID. * Known users are those with an email or other identifier. * Build an audience of users that have both a Web Cookie ID and an email. Here is an [example](https://learn.lytics.com/documentation/product/features/user-profiles/stitching-user-profiles#tracking-growth). * Mobile Users * The Lytics JS Tag will automatically record if a user has ever used a mobile device to view your webpages. * Creating a list of those who use mobile devices can be helpful when marketing a new mobile app. See our [Drive mobile app downloads use case](https://learn.lytics.com/use-cases/drive-mobile-app-downloads). * Free Trial Users who are highly engaged * You often need to incentivize users to become paid subscribers. By identifying users who are highly engaged that are not yet subscribers, you can target them with relevant offers to drive conversions. * See our use case: [Convert highly engaged users to subscribers](https://learn.lytics.com/use-cases/lookalike-models-convert-highly-engaged-users-to-subscribers) * Known Users who have made a single purchase * Once you’ve acquired customers, a good way to increase sales and revenue without increasing advertising cost significantly is to target customers that are most likely to return for a second or third purchase. * See our use case: [Convert single purchasers to multi-purchasers](https://learn.lytics.com/use-cases/lookalike-models-convert-single-purchasers-to-multi-purchasers) ### Helpful Hints #### Use existing audiences as building blocks Beginning with an existing audience filter will allow you to create a new sub-set audience much easier. Be careful to keep from having cross-references in multiple audiences! #### Audience Counts Keep in mind that audiences are **real-time**. Audiences are filters applied to the total audience and will change whenever a user's behavior changes in a way that will add or remove them from the audience definition. In this way, tracking audience size over time is a powerful reporting tool. #### Adjust rule logic to target more or less users Lytics audiences are incredibly flexible. You can include multiple user attributes within a rule, and even include multiple rule sets within a given audience.  Use the **AND** operator to target a **smaller** audience of users who have multiple attributes.  * Example: people who are frequent users AND have a high affinity for Lytics. ![audience-builder-and-example.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt9ad8ec0292ff6a92/686604caf4c619a376fcf0cf/audience-builder-and-example.png) Use the **OR** operator to target a **larger** audience of users who have one or more attributes. * Example: users who have made a purchase OR users who are loyalty members. ![audience-builder-or-example.png](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blta8aed82bb6a21eaa/686604ca8628602d45348b9a/audience-builder-or-example.png) Learn more about building audiences with [Multiple Rules & Rule Sets](https://learn.lytics.com/documentation/product/features/audiences/building-audiences/multiple-rules-and-rulesets). #### Test your audience configuration  You can export any audience as CSV file to an email, which can be very useful for testing to make sure your audience is configured properly. To export an audience to an email: 1. Click the "Export" button on the Audience page. 2. Choose "Custom Integrations". 3. Choose "Email CSV" and the "Email" Authorization option. 4. Enter the email address, description, and fields to export. Be careful when exporting Personally Identifiable Information (PII)! You may want to just send the Web Cookie ID for testing, and look up the profiles in the UI to confirm they are the correct ones. 5. In the "Advanced Options", make sure the "**Continuous Export**" setting is unchecked to make this a one-time email. ## Next Steps We recommend you check out the following resources next. ### Academy Courses * How to Export Audiences  * Behavioral Audiences * Connecting Integrations ### Documentation * [Audiences Overview](https://learn.lytics.com/documentation/product/features/audiences/audiences-introduction) * [Experiences Overview](https://learn.lytics.com/documentation/product/features/experiences/overview) * [Goals Overview](https://learn.lytics.com/documentation/product/features/goals/canvas-overview) #### Key takeaways - Connect **Audience Building** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 10 — Content #### Lesson text Lytics includes a built-in content intelligence engine that classifies your web content into topics and uses those classifications to compute content affinity scores on every profile. This section covers how to configure content ingestion, review and correct classification results, enrich the content corpus with custom metadata via context layers, curate content into collections for recommendations, and read content affinity signals from profiles for segmentation and personalization. By the end, you will be able to stand up and operate the full content pipeline — from raw page view events through to recommendation delivery. ## Content Configuration ### Learning Objectives By the end of this section, you will be able to: \- Set up content ingestion in Lytics so that web pages, articles, and other content are automatically collected \- Configure content ingestion inputs including event-driven URL discovery, manual classification, and corpus API ingestion \- Verify that content is being collected by checking the content library for expected entries ### Setting Up Content Ingestion Lytics treats each content item as a **document** and the full set of documents as a **corpus** — the `content` table that stores classified content records used by affinities, collections, and recommendations. For web implementations, new content is usually discovered from incoming events that contain a `url` field. When Lytics receives an event containing a new URL, it writes a content-enrichment event to `lytics_content_enrich` and maps output into the `content` table via the `lytics_content` query. To configure content ingestion reliably, focus on four controls first: \- **Account content allowlists**: include every production domain/subdomain where content should be crawled. \- **Crawler access**: ensure `lyticsbot` can fetch your pages via `robots.txt` and network policy. \- **Tag/event coverage**: ensure page and content interaction events include URLs. \- **Manual ingest options**: use Content Classification or Content Corpus API for controlled onboarding and backfills. #### Key Concepts * **Domain allowlist controls collection scope**: if a domain is missing, content from that domain will not classify correctly. * **Crawlability is required**: `robots.txt` and server allowlists can block enrichment. * **Discovery is event-driven**: Lytics observes URLs in stream events; it is not a generic web crawler that continuously indexes your entire site by default. * **Non-web content is supported**: add documents by sending URL/text directly to the corpus API. #### Step-by-Step 1. Go to **Account > Settings > Content** and populate **Content domains allowlist** with all production domains/subdomains. 2. Confirm your site permits `lyticsbot` and exposes valid metadata for title, image, and topic extraction. 3. Validate that your tag/event pipeline is sending URL-bearing events (for example, page views). 4. Open **Content > Classification** and run a manual classification on representative URLs. 5. Open **Content > Documents** and verify new documents appear with expected metadata. 6. If you need to ingest controlled records (non-web, staged, or backfill), send documents with the Content Corpus API. #### Examples ```bash curl -s -XPOST "https://api.lytics.io/api/content/corpus" \ -H "Authorization: $LIOKEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://www.example.com/blog/launch-post", "topics": "Product Launch,CDP" }' ``` ```text Quick validation pattern: - Add domain to content allowlist - Manually classify 3-5 representative URLs - Confirm each has title + primary image + topics ``` #### Diagrams & Screenshots ![Content ingestion flow from URL events through enrichment into the content table.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amf8c7aa00b681aecf/b1c1cdaa0468c6fa0bd3fe9e/content_ingestion_flow_url_events.png) ### Summary Content ingestion in Lytics is event-driven: the platform discovers new URLs from incoming stream events and enriches them into the document corpus automatically. To get this working, you need the domain allowlist configured, crawler access confirmed, and URL-bearing events flowing from the tag. For backfills or non-web content, use the Content Corpus API to push documents directly. Validate by checking the Content Documents view for expected entries with title, image, and topic metadata. ### Documentation Links * [Content Configuration](https://docs.lytics.com/docs/content-configuration) * [Content Corpus API](https://docs.lytics.com/docs/content-corpus-api) ## Classification ### Learning Objectives By the end of this section, you will be able to: \- Understand how Lytics uses AI-powered content classification to automatically categorize and tag content \- Review and adjust classification results to correct misclassifications and improve accuracy \- Manage the content taxonomy including topics, categories, and custom labels ### AI-Powered Content Classification The **Classification** page provides operational visibility into content processing and a manual classifier for testing and correction. From the product documentation and UI behavior, the page is split into: \- **Classification Dashboard**: activity and flow-state visibility. \- **Manual Content Classification**: URL-level preview and topic override before corpus commit. By default, classification runs continuously in background workflows and reprocesses content over time (subject to account limits). #### Key Concepts * **Classification activity quota**: default docs guidance references up to 20,000 documents per month (new + reclassifications) unless contract settings differ. * **Flow-state diagnostics**: distinguish allowlist issues, robots blocking, non-200 fetches, and enrichment failures. * **Manual classify supports curation**: review topics, adjust as needed, then complete classification. * **URL normalization**: Lytics applies URL sanitation logic (`urlmain`) to reduce duplicate URL variants. #### Step-by-Step 1. Open **Content > Classification**. 2. Review activity and flow states to detect blocked domains, path restrictions, or HTTP failures. 3. In **Manual Content Classification**, classify a target URL. 4. Validate extracted `title`, `primary_image`, and `topics`. 5. Add/remove topics when needed, then click **Complete Classification** to write the document into corpus. 6. Re-run classification checks after metadata/template updates on your site. #### Examples ```html ``` ```bash # Preview classification only (debug) curl -s -XGET "https://api.lytics.io/api/content/doc/classify?url=https://www.example.com/blog/post" \ -H "Authorization: $LIOKEY" ``` ```bash # Classify and add to corpus curl -s -XPOST "https://api.lytics.io/api/content/doc/classify?url=https://www.example.com/blog/post" \ -H "Authorization: $LIOKEY" ``` #### Diagrams & Screenshots ![Classification dashboard showing activity, content flow states, and manual classify panel.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am73bc3e943df8481f/d27a146ceac1ae66ed53d938/classification_dashboard_activity_content_flow.png) ### Summary Classification runs automatically in the background, but the Classification page gives you the operational controls to diagnose failures and correct results manually. Use the dashboard flow states to identify blocked domains or crawl failures, and use the manual classifier to preview and override topic assignments before committing documents to the corpus. After any significant site metadata changes, re-run classification checks to ensure the corpus stays accurate. ### Documentation Links * [Content Classification](https://docs.lytics.com/docs/content-classification) * [Content Taxonomy Management](https://docs.lytics.com/docs/content-taxonomy) ## Context Layers ### Learning Objectives By the end of this section, you will be able to: \- Add context layers to content to enrich classification with custom metadata dimensions \- Use metadata from context layers for enhanced audience targeting and personalization \- Configure context layer sources, including CMS metadata, manual tags, and external data feeds ### Enriching Content with Context Layers Lytics supports three context-layer patterns: \- **Standard Context Layer**: default NLP-based topic extraction on web content. \- **Custom Context Layers**: map custom content fields to user-level affinity fields. \- **Collaborative Filters**: model user-item similarity for "users also viewed/bought" recommendations. In current navigation, these are managed at **Content > Context Layers**. #### Key Concepts * **Standard field mappings**: * `content.hashedurl` identifies documents. * `content.global` stores topic/features. * `user.hashedurls` captures viewed item IDs. * `user.lytics_content` stores inferred topic-level interests. * **Custom layers are schema-driven**: you select inventory ID + feature field on `content`, then map user inventory field. * **Collaborative filters require behavior links**: a set/map on user profiles that references content IDs. * **Output fields become audience-usable**: context-layer outputs can be used directly in Audience Builder rules. #### Step-by-Step 1. Open **Content > Context Layers**. 2. Choose **New Context Layer** and select one type: \- Custom Context Layer \- Collaborative Filter \- Shopify-specific guided option (if applicable) 3. For custom layers: 4. Select content identifier field (inventory ID). 5. Select one or more feature/topic fields to project. 6. Map the related user field that contains inventory interactions. 7. Set output field name and save. 8. For collaborative filters: 9. Define name and description. 10. Select inventory ID on content. 11. Select user inventory-history field (set/map). 12. Save and wait for model training. 13. Validate outputs on sample user profiles and in audience rule selectors. #### Examples ```text Custom context layer (commerce): - content id field: shopify_product_id - content feature field: shopify_product_tags - user inventory field: shopify_product_ids - output user field: shopify_affinities_tag_ ``` ```bash # Explore topic graph used by context-layer workflows curl -s -XGET "https://api.lytics.io/api/content/taxonomy?limit=150" \ -H "Authorization: $LIOKEY" ``` #### Diagrams & Screenshots ![Context layer creation wizard showing inventory mapping and output field configuration.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amdc6605baf3a80c4a/228e9fb477051fb2996a01ce/context_layer_creation_wizard_inventory.png) ### Summary Context layers extend the platform's default NLP classification with custom metadata dimensions. Custom context layers map content-side feature fields (like product tags or CMS categories) to user-level affinity fields, creating audience-usable signals beyond standard topic scores. Collaborative filters take this further by modeling user-item similarity from interaction history. In both cases, validate the output fields on real profiles and confirm they appear as selectable criteria in the Audience Builder before activating downstream. ### Documentation Links * [Context Layers](https://docs.lytics.com/docs/context-layers) * [Collaborative Filtering](https://docs.lytics.com/docs/collaborative-filtering) ## Content Collections ### Learning Objectives By the end of this section, you will be able to: \- Create content collections to group related content items for specific use cases or campaigns \- Organize content into curated groups using manual selection, filters, or dynamic rules \- Use content collections as the basis for recommendation widgets and personalized content delivery ### Curating Content with Collections Content Collections are content-side segmentation objects. Where audiences segment users, collections segment documents. Lytics supports both: \- **Dynamic collections**: rule-driven and continuously updating. \- **Locked collections**: static, hand-selected documents. Lytics also auto-creates foundational collections (for example, all documents and recommendation-ready defaults) to accelerate setup. #### Key Concepts * **Collections are recommendation boundaries**: they constrain what can be returned by recommendation APIs and experiences. * **Builder filters are composable**: title/description/URL, content type, publish date, features, author, affinities, topics. * **Advanced editor unlocks full expression power**: combine collection inclusion and content-field logic beyond basic filters. * **Lifecycle operations matter**: duplicate, edit, delete, and re-enrich with dependency checks. #### Step-by-Step 1. Go to **Content > Collections** and click **New Collection**. 2. Decide **Dynamic** or **Locked**. 3. Add filters that match campaign intent (for example, path + topics + recency). 4. Save collection and open its summary page. 5. Validate: \- **Documents tab** for content quality. \- **Recommendations tab** for user-level recommendation testing. 6. If needed, open **Advanced Editor** to add custom rule logic. 7. Use **Re-Enrich** after major metadata/template updates. #### Examples ```text Collection pattern: recent_blog_growth_marketing - dynamic collection - URL contains /blog/ - topic includes "Growth Marketing" - published in last 30 days - has primary image + description ``` ```text Locked collection pattern: q4_hero_assets - static curated set of high-priority launch pages - manually selected to avoid churn during campaign period ``` #### Diagrams & Screenshots ![Content collection builder showing dynamic filters and advanced editor options.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amb5f59cec271f9d2c/4ce3515fe60a0ea62b737cbe/content_collection_builder_dynamic_filters.png) ### Summary Collections are the scoping layer for content recommendations — they define what the recommendation engine is allowed to return. Dynamic collections update continuously as new content is classified and filtered; locked collections are static and useful for campaigns where content stability matters. Validate every collection using the Documents and Recommendations tabs before attaching it to a delivery channel, and use Re-Enrich after any significant site metadata updates to keep collection membership accurate. ### Documentation Links * [Content Collections](https://docs.lytics.com/docs/content-collections) * [Content Recommendations](https://docs.lytics.com/docs/content-recommendations) ## Content on Profile ### Learning Objectives By the end of this section, you will be able to: \- Understand how content affinity appears on user profiles as topic scores and content engagement data \- Use content affinity fields for segmentation to build audiences based on what users read and engage with \- Interpret content engagement scores to distinguish between casual browsers and deeply engaged readers ### Understanding Content Affinity on Profiles Content processing produces user-level fields that power segmentation and recommendations. Topic and affinity scores are relative ranking signals across users and topics — treat them as comparative indicators, not absolute truth. The most important profile fields are: \- `lytics_content` (map\[string\]number): topic-level interests. \- `lytics_rollup` (map\[string\]number): affinity rollups/groups. \- `lytics_content_inferred` (map\[string\]number): inferred-only interests. \- `hashedurls` (map): hashed content IDs the user engaged with. #### Key Concepts * **Behavior drives affinity**: topic signals rise/fall based on observed interactions and model updates. * **Rollups simplify activation**: use affinity rollups when you need broad categories instead of atomic topics. * **Inferred-only field caution**: docs recommend avoiding `lytics_content_inferred` as a sole targeting field. * **Profile verification is mandatory**: always inspect real profiles before activating content-based audiences. #### Step-by-Step 1. Open a known profile in **Profile Explorer**. 2. Inspect `lytics_content`, `lytics_rollup`, and supporting behavioral fields. 3. Confirm that recent content behavior matches expected topic signals. 4. Build a test audience using one topic/affinity rule. 5. Validate audience sample users for false positives/negatives. 6. Iterate thresholds/conditions before production activation. #### Examples ```bash # Fetch a user profile and inspect content-affinity fields curl -s -XGET "https://api.lytics.io/api/entity/user/email/jane@example.com" \ -H "Authorization: $LIOKEY" ``` ```text Audience logic pattern: - Include users where lytics_rollup["B2B Marketing"] >= medium - Exclude users where lifecycle_stage = customer ``` ### Summary Content affinity data lives on the profile as a set of map fields — `lytics_content` for atomic topic scores, `lytics_rollup` for grouped categories, and `hashedurls` for the specific content items a user engaged with. Scores are relative signals, not absolute values, so validate them against real profiles before building production audiences. Prefer rollup fields when you want broad category targeting; use atomic topic fields when you need precise interest matching. ### Documentation Links * [Content Affinity on Profiles](https://docs.lytics.com/docs/content-affinity) * [Profile Explorer](https://docs.lytics.com/docs/profile-explorer) ## Recommendations ### Learning Objectives By the end of this section, you will be able to: \- Configure the Lytics content recommendation engine, including selecting collections and setting recommendation strategies \- Tune recommendation parameters such as ranking mode, visited filtering, and collection constraints \- Deliver recommendations to end users via Pathfora widgets, the Personalize API, or custom integrations ### Configuring and Delivering Content Recommendations Lytics recommendations can be implemented through: \- **Lytics UI** (Interest Engine and Collection recommendation tabs) \- **Pathfora** recommendation modules \- **Recommendation APIs** for custom web/email/app delivery The API path most teams start with is: \- `GET /api/content/recommend/user/{fieldname}/{fieldval}` For campaign-wide defaults, use segment-scoped recommendations: \- `GET /api/content/recommend/segment/{segId}` #### Key Concepts * **Collection-first recommendation strategy**: use `contentsegment` to constrain recommendation scope and avoid irrelevant pages. * **Ranking modes**: `affinity`, `popular`, `recent`. * **Visit filtering**: `visited=false` suppresses already-viewed content. * **Fallback handling**: Pathfora supports default content blocks when recommendation calls return no result. #### Step-by-Step 1. Build or select a recommendation-ready content collection. 2. Validate collection quality: \- documents return HTTP 200, \- documents are enriched, \- documents have topics. 3. Test recommendations from the collection summary **Recommendations** tab using a known identity. 4. Implement API call in your delivery channel (site/email/service). 5. Tune parameters (`rank`, `limit`, `visited`, `shuffle`, topic constraints). 6. Add fallback behavior for sparse profiles. 7. Monitor engagement and iterate collection filters plus rank strategy. #### Examples ```bash curl -s -XGET "https://api.lytics.io/api/content/recommend/user/email/alex@example.com?contentsegment=recent_blog_growth_marketing&limit=5&rank=affinity&visited=false" \ -H "Authorization: $LIOKEY" ``` ```javascript // Pathfora recommendation module excerpt const widget = { type: "message", layout: "modal", recommend: { collection: "recent_blog_growth_marketing", rank: "affinity", visited: false, shuffle: true }, content: [ { default: true, title: "Explore our latest resources", url: "https://www.example.com/resources" } ] }; ``` #### Diagrams & Screenshots ![Recommendation workflow from collection definition to API delivery and performance optimization.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amb9ea60d6f11ac644/85d48ee6e5b356ea1abb70b0/recommendation_workflow_collection_definition_api.gif) ### Summary Recommendations tie together the content corpus, affinity scores, and collections into a delivery mechanism. Start by validating your collection's document quality, then test recommendations against known user identities before wiring up your delivery channel. Constrain scope with a `contentsegment` parameter, tune ranking mode and visit filtering to match your intent, and always implement fallback content for profiles with sparse affinity data. Monitor engagement after launch and iterate on collection filters and rank strategy based on performance. ### Documentation Links * [Content Recommendations](https://docs.lytics.com/docs/content-recommendations) * [Recommendation API](https://docs.lytics.com/docs/recommendation-api) * [Pathfora Recommendations](https://docs.lytics.com/docs/pathfora-recommendations) ## What You've Learned You now understand how Lytics builds and maintains a classified content corpus from your web pages and other content assets — from the domain allowlist and crawler configuration that govern ingestion, through the AI-powered classification pipeline, to the context layers that extend the corpus with custom metadata. You've seen how that corpus feeds into user profiles as content affinity scores, how those scores become audience criteria in the builder, and how collections scope the recommendation engine to return only the right content to the right person. Together, these capabilities make content a first-class signal in your segmentation and personalization strategy, not just a reporting artifact. ### Key Terms > 📘 **Document** — A single classified content record in Lytics, representing a web page, article, or other content asset stored in the corpus. > > 📘 **Corpus** — The `content` table in Lytics that stores all classified document records, used by affinity computation, collections, and recommendations. > > 📘 **Content Affinity** — A platform-computed score measuring how strongly a user profile is associated with a content topic, based on observed content interactions. Stored as a map of topic-to-score values in `lytics_content`. > > 📘 **Context Layer** — A configuration that maps custom content-side metadata (such as product tags or CMS categories) to user-level affinity fields, extending classification beyond standard NLP topics. > > 📘 **Collaborative Filter** — A context-layer type that models user-item similarity from interaction history, enabling "users also viewed" recommendation patterns. > > 📘 **Content Collection** — A content-side segmentation object that groups documents for use in recommendations. Collections can be dynamic (rule-driven) or locked (static/hand-curated). > > 📘 **Affinity Rollup** — A grouped aggregation of atomic topic scores stored in `lytics_rollup`, used when broad-category targeting is preferable to individual topic precision. > > 📘 **lyticsbot** — The Lytics crawler that fetches and enriches web pages after URL discovery. Must be permitted in `robots.txt` and server network policies for content ingestion to work correctly. #### Key takeaways - Connect **Content** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 11 — Audience Insights App #### Lesson text The Audience Insights App gives implementation teams a structured way to move from raw audience data to activation decisions. Rather than inspecting audiences in isolation, you use two interconnected surfaces — per-audience summary views and multi-audience Reports — to compare size trends, membership overlap, field composition, and dataflow. This section walks you through both surfaces and shows you how to build reusable comparison reports that turn analysis into concrete actions. ## Overview ### Learning Objectives By the end of this section, you will be able to: \- Explain what the Audience Insights App provides and the questions it helps answer \- Navigate the Insights App UI and locate key views \- Identify key audience composition metrics such as demographics, behaviors, and affinities ### Overview In current Lytics implementations, audience insights are delivered through two surfaces: \- **Audience Summary views** (per-audience metrics and characteristics) \- **Reports** (multi-audience visual analysis using reusable components) You may also see references to a legacy **Insights Drawer** experience in older docs. That model focused on generated insight cards; current implementation analysis work is typically done in Reports and audience summary pages. The audience insights workflow covers comparing audience size, composition, overlap, and dataflow so you can convert findings into activation actions. From the reporting system and UI source, the core component types are: \- **Size**: trends and point-in-time audience size \- **Composition**: field distribution by audience (for example `lytics_content`, behavioral scores, UTM fields) \- **Overlap**: Venn-based shared membership analysis \- **Dataflow**: provider/stream/audience/destination linkage #### Key Concepts * **Single-audience vs cross-audience analysis**: * Audience Summary tabs are best for health and lifecycle of one audience. * Reports are best for comparison between audiences. * **Insights are activation-oriented**: overlap intersections can be turned into pre-populated audience definitions. * **Limits to design around**: * Up to 25 reports per account in current UI. * Up to 20 components per report. * Overlap components support up to 3 audiences. * **Sharing model**: reports can be public to reporting-role users or restricted as private with collaborators. #### Step-by-Step 1. Start with business questions, not charts (for example: "Which audience is growing fastest?", "Where is overlap causing suppression leakage?"). 2. Validate audiences are production-ready (definitions, naming, ownership, and enough population). 3. Open each audience summary page and review: \- **Metrics** tab for trend and share, \- **Details** for dependencies/exports, \- **Characteristics** for profile composition, \- **Logs** for recent definition/config changes. 4. Move to **Reports** for side-by-side analysis across audiences. 5. Build a reusable report that combines size + overlap + composition. 6. Convert findings into concrete actions (new audience, exclusion rule, destination export change, or experience targeting update). #### Examples ```text Questions and matching components: - "Is this audience accelerating?" -> Size component - "Which topics distinguish audience A vs B?" -> Composition on lytics_content - "Where are we double-targeting?" -> Overlap component - "Which pipeline path feeds this audience?" -> Dataflow component ``` ```bash # List reports curl -s -XGET "https://api.lytics.io/v2/report" \ -H "Authorization: $LIOKEY" ``` #### Diagrams & Screenshots ![Audience insights workflow from audience summary pages to comparative reports and activation actions.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am1b04ae013ea8e208/8d407e9c32f207b411b201c2/audience_insights_workflow_audience_summary.png) ### Summary Audience insights in Lytics are surfaced through per-audience summary views and the multi-audience Reports workspace. Summary views are best for inspecting the health and lifecycle of a single audience, while Reports provide the cross-audience comparison — size trends, overlap, field composition, and dataflow — needed to make activation decisions. The analysis workflow always starts with a business question and ends with a concrete action: a new audience definition, an exclusion rule update, or a destination export change. ### Documentation Links * [Audience Overview](https://docs.lytics.com/docs/audiences) * [Reports](https://docs.lytics.com/docs/reports) * [Audience Overlap](https://docs.lytics.com/docs/audience-overlap) ## Implementation Walkthrough ### Learning Objectives By the end of this section, you will be able to: \- Set up the Insights App for a specific audience and configure its parameters \- Interpret insights data to inform marketing and personalization strategy \- Export insights for stakeholder reporting and presentations ### Implementation Walkthrough This walkthrough builds a reusable **Audience Comparison Report** for up to three strategic audiences. #### Key Concepts * **Use 2-3 audiences for clean comparisons**: this keeps overlap interpretation and stakeholder communication simple. * **Standard comparison stack**: * Size comparison (trend + current value) * Membership overlap (intersection and exclusivity) * Interest/behavior composition (why these audiences differ) * **Start with stable fields**: use trusted fields (`lytics_content`, behavioral score fields, lifecycle attributes) before experimenting with niche fields. * **Save interpretation context**: meaningful component names and descriptions reduce rework in recurring reviews. #### Step-by-Step 1. Pick 2-3 audiences with one shared business objective (for example acquisition vs nurture vs retention). 2. Confirm each audience has sufficient size and recent activity. 3. Go to **Reports** and click **Create New**. 4. Name the report (for example `Q2_key_audience_comparison`) and add a scope description. 5. Add a **Size** component for trend and snapshot comparison. 6. Add an **Overlap** component with the same 2-3 audiences (overlap supports max 3). 7. Add **Composition** components for `lytics_content` and selected behavioral score fields. 8. Add **Dataflow** if you need stream/provider/destination traceability. 9. Rename components to reflect business meaning, then set report access mode (shared or private with collaborators). 10. Export component CSVs for stakeholder communication and runbook documentation. 11. Convert findings into actions: * create suppression or opportunity audiences from overlap insights, * update exports/experiences/flows using composition findings, * schedule recurring reviews. #### Examples ```text Reference report layout: 1) Audience Membership Comparison (Size) 2) Membership Overlap (Overlap) 3) Interest Comparison (Composition: lytics_content) 4) Frequency Comparison (Composition: score_frequency) 5) Intensity Comparison (Composition: score_intensity) 6) Momentum Comparison (Composition: score_momentum) ``` ```bash # Add a size component to an existing report curl -s -XPOST "https://api.lytics.io/v2/report/$REPORT_ID/component" \ -H "Authorization: $LIOKEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Audience Membership Comparison", "type": "size", "config": { "segment_ids": ["aud_1", "aud_2", "aud_3"], "type": "sizes", "table": "user" } }' ``` ```text Interpretation pattern: - High overlap + similar composition -> consolidate messaging and suppress duplication - Low overlap + distinct composition -> maintain differentiated channel/creative strategy - Rising size but falling momentum -> review acquisition quality and nurture timing ``` #### Diagrams & Screenshots ![Audience comparison report with size, overlap, and composition components configured for three audiences.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am4df9c086acf3388c/e984edd3cef9de184aa04375/audience_comparison_report_size_overlap.png) ### Summary Building a reusable audience comparison report follows a repeatable pattern: select 2-3 strategically related audiences, layer in size, overlap, and composition components, and name everything for business meaning before sharing. The findings from a well-structured report translate directly into activation changes — new suppression rules, updated destination exports, or refined personalization targeting. Recurring reviews against the same report structure let you track whether your interventions are working over time. ### Documentation Links * [Creating Reports](https://docs.lytics.com/docs/reports) * [Report Components](https://docs.lytics.com/docs/report-components) * [Exporting Report Data](https://docs.lytics.com/docs/report-export) ## What You've Learned In this section you worked through both surfaces of Lytics audience analysis: the per-audience summary view for inspecting individual audience health and the Reports workspace for multi-audience comparison. You learned how to frame business questions as component choices, validate audiences before analysis, and build a structured comparison report that covers size, overlap, composition, and dataflow. The walkthrough showed you how to name and share reports effectively and how to convert every insight into a downstream activation action. ### Key Terms > 📘 **Audience Insights workflow** — The implementation workflow for comparing audience size, composition, overlap, and dataflow so you can convert findings into activation actions. > > 📘 **Audience Summary view** — A per-audience page in the Lytics UI that surfaces metrics, characteristics, dependencies, exports, and change logs for a single audience. > > 📘 **Report** — A saved dashboard object containing one or more configurable components (`size`, `composition`, `overlap`, `dataflow`) used for cross-audience analysis. > > 📘 **Composition component** — A report component that shows the distribution of a selected profile field across one or more audiences, useful for understanding behavioral and interest differences between segments. > > 📘 **Overlap component** — A report component that renders Venn-style intersection and exclusion analysis for up to three audiences, used to identify double-targeting or suppression opportunities. > > 📘 **Dataflow component** — A report component that maps provider/stream/audience/destination relationships, used for integration path traceability and pipeline troubleshooting. #### Key takeaways - Connect **Audience Insights App** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 12 — Lookalike Model #### Lesson text Lookalike modeling in Lytics extends your rule-based audience strategy by scoring profiles on their similarity to a target audience. When manual segment logic is too coarse and you need the platform to learn high-signal combinations of behavior and profile attributes, a lookalike model gives you a precision tool that writes directly back to profile fields — making its output available everywhere audiences are used. This section covers the full model lifecycle: framing goals, configuring and training a model, interpreting its diagnostics, and activating predictive audiences downstream. ## Overview ### Learning Objectives By the end of this section, you will be able to: \- Explain what lookalike models are and how they identify similar users \- Describe when to use lookalike modeling versus other audience strategies \- Understand the business value of lookalikes for expanding reach and improving targeting ### Overview Lytics **Lookalike Models** are propensity models that score users in a **Source Audience** — the audience you want to score and take action on — based on how similar they are to a **Target Audience** — the audience that represents the outcome you want more users to resemble. You use them when rule-based audience logic is too coarse and you want the platform to learn higher-signal combinations of behavior and profile attributes. In current UI navigation, model management is under **Laboratory > Lookalike Models** (`/laboratory/lookalike-models`). #### Key Concepts * **Lookalike models are profile-native**: scores are written back to profile meta fields, so they are usable anywhere audiences are usable. * **Model outputs are explicit fields**: * `segment_prediction` (map of model score values, typically 0-1) * `segment_prediction_percentile` (map of percentile ranks, integer scale) * **ML augments, not replaces, audience strategy**: you still define clear business intent through source/target selection. * **Activation controls scoring lifecycle**: building a model and activating scoring are separate operational steps. #### Step-by-Step 1. Define the business question in source-to-target form: \- `unknown_users -> known_users_with_email` \- `single_purchasers -> repeat_purchasers` 2. Confirm both audiences are valid and stable in **Audience Builder**. 3. Go to **Laboratory > Lookalike Models** and click **Create New**. 4. Configure source/target and initial model options. 5. Review model status (`building`, `complete`, `active`, etc.) and summary diagnostics once complete. 6. Activate the model and build predictive audiences from model score/percentile fields. #### Examples ```text Appropriate lookalike scenarios: - You need better precision than broad lifecycle audiences - Feature interactions are too complex for manual segment rules - You want dynamic audience membership as behavior changes ``` ```text Lookalike anti-patterns: - Source/target definitions are unclear or unstable - Audience populations are too small to train reliably - You have no clear activation destination or downstream action ``` #### Diagrams & Screenshots ![Lookalike model workflow from source/target selection to scoring and predictive audience activation.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amcab82ebd9a8794e1/984a3252933be7c0494877cf/lookalike_model_workflow_source_target.png) ### Summary Lookalike models score every profile in your source audience on its similarity to a target audience, writing those scores back as profile fields that are immediately usable in audience rules. They are most valuable when manual rule logic is too coarse or when feature interactions are complex enough that a machine learning approach outperforms manual segmentation. The key governance discipline is keeping source and target definitions clear and stable before you build — model quality is mostly determined at goal-definition time, not at configuration time. ### Documentation Links * [Lookalike Models Overview](https://docs.lytics.com/docs/lookalike-models) * [Predictive Audiences](https://docs.lytics.com/docs/predictive-audiences) ## How Models Work ### Learning Objectives By the end of this section, you will be able to: \- Understand the machine learning approach used by lookalike models at a high level \- Identify what data feeds the model, including behavioral and profile attributes \- Explain model confidence scores and how they rank lookalike candidates ### How Models Work Lytics trains supervised models to distinguish target-like behavior from non-target behavior using profile features. You control inputs at configuration time; Lytics handles feature processing, training, evaluation, and score persistence. #### Key Concepts * **Feature inputs** can include: * Behavioral scores (`use_scores`) * Content affinity (`use_content`) * Additional schema fields (`additional`) * Field exclusions (`blocked`) * **Model workflow separation**: * `Model Training Only` builds model artifacts. * Active scoring evaluates profiles and updates prediction fields. * **Size guardrails matter**: * Minimum source/target threshold is enforced (25 users). * Large audiences can trigger alternate modeling behavior and performance tradeoffs. * **Health and diagnostics are first-class outputs**: * Summary view surfaces model health, accuracy, reach, and feature composition. * Diagnostics tab includes `R Squared`, `MSE`, `AUC`, error rates, and decision threshold. #### Step-by-Step 1. Open a completed model and review the **Summary** tab first. 2. Confirm the model is healthy enough for activation: \- confidence/health state acceptable, \- non-trivial accuracy and reach balance, \- no major warning messages. 3. Open **Configuration** to confirm included/excluded features match your intent. 4. Open **Diagnostics** to inspect: \- `R Squared` \- `Mean Squared Error` \- `False Positive/Negative Rate` \- `Area Under Curve` \- `Decision Threshold` 5. Use **Feature Importance and Correlation** charts to identify which fields are driving predictions. #### Examples ```text Example interpretation: - High accuracy + low reach: best for narrow, high-intent targeting - Lower accuracy + high reach: best for upper-funnel expansion - Unhealthy model messages: revisit source/target adjacency or feature set ``` ```lql FILTER AND ( INCLUDE unknown_users, segment_prediction.`unknown_to_known_model` >= 0.50 ) FROM user ``` #### Diagrams & Screenshots ![Lookalike model summary view with audience cards, threshold explorer, and feature importance charts.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amde3193a79426d72a/bbba365fe3b7975fb7a0aa4e/lookalike_model_summary_view_audience.png) ### Summary Lytics lookalike models are supervised classifiers trained on the profile features you specify. Behavioral scores, content affinity, and selected schema fields are the primary inputs; feature processing, training, and score persistence happen automatically. After build, the Summary and Diagnostics tabs give you accuracy, reach, R Squared, AUC, and error rate signals you use to decide whether the model is ready for activation. Feature importance charts let you verify that the predictors driving the model are meaningful and acceptable from a governance perspective. ### Documentation Links * [Model Diagnostics](https://docs.lytics.com/docs/lookalike-model-diagnostics) * [Feature Importance](https://docs.lytics.com/docs/lookalike-feature-importance) * [Behavioral Scoring](https://docs.lytics.com/docs/behavioral-scoring) ## Define Goals ### Learning Objectives By the end of this section, you will be able to: \- Define clear model objectives tied to business outcomes \- Choose the right seed audience based on size, quality, and relevance \- Set success criteria for model performance including target reach and precision ### Define Goals Lookalike performance is mostly determined before you click build. Clear goal definition and correct source/target design are the most important controls you have. #### Key Concepts * **Frame goals as movement between audience states**: from current state (source) to desired state (target). * **Choose adjacent lifecycle stages**: adjacency improves learnability and actionable overlap. * **Define success before build**: * expected audience size at initial threshold, * expected lift/conversion proxy, * activation channel and cadence. * **Keep targets behaviorally meaningful**: avoid purely administrative fields that do not represent real outcomes. #### Step-by-Step 1. Write a one-line objective: \- "Increase users likely to become newsletter subscribers." 2. Choose source and target audiences that reflect this objective. 3. Validate each audience: \- clear definition, \- enough users, \- current and regularly refreshed. 4. Define threshold strategy in advance: \- start near default decision threshold for balanced performance, \- lower threshold for reach, \- higher threshold for precision. 5. Define activation plan: \- destinations/flows/Pathfora experiences that will use the resulting audiences. 6. Document model ownership and review cadence. #### Examples ```text Goal template: - Business outcome: - Source audience: - Target audience: - Activation channel: - Success metric: ``` ```text Common objective patterns: - unknown -> known - one-time purchaser -> repeat purchaser - engaged browser -> converter - recently active customer -> retained customer ``` #### Diagrams & Screenshots ![Goal definition worksheet showing source, target, threshold strategy, and activation plan.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am27cf6e0d1f4a70e3/3a32acb07e6c181615cdc711/goal_definition_worksheet_source_target.png) ### Summary Model goal definition is the highest-leverage step in the lookalike workflow. Framing goals as movement between adjacent lifecycle states — unknown to known, browser to converter, single purchaser to repeat purchaser — gives the model a learnable signal and keeps the downstream activation plan concrete. Define your expected audience size, precision target, and activation channel before you build, so you have a clear success benchmark to evaluate against once diagnostics are available. ### Documentation Links * [Lookalike Model Configuration](https://docs.lytics.com/docs/lookalike-model-configuration) * [Audience Building](https://docs.lytics.com/docs/audiences) ## Configure Model ### Learning Objectives By the end of this section, you will be able to: \- Configure model parameters in the Lytics UI including seed audience and scope \- Select features for the model that align with your modeling goals \- Launch a model run and monitor its progress to completion ### Configure Model Configuration is driven by workflow `lytics_seg_model` in the UI wizard and is split into required basic settings and optional advanced controls. #### Key Concepts * **Required inputs**: * `source` * `target` * **Common advanced controls**: * `auto_tune` * `build_only` (training-only mode) * `use_scores` * `use_content` * `additional` * `blocked` * `re_run` (continuous retrain) * `collect` (sample size) * **Activation is explicit**: after build, click **Activate** to apply scoring updates on profiles. * **Model tabs for operations**: * **Summary**, **Audiences**, **Configuration**, **Diagnostics** #### Step-by-Step 1. Go to **Laboratory > Lookalike Models > Create New**. 2. Set **Source Audience** and **Target Audience**. 3. Optionally set **Custom Model Name** (recommended for governance). 4. Decide whether to start in **Model Training Only** mode. 5. Configure feature strategy: \- start with `use_scores` + `use_content`, \- add carefully selected `additional` fields if needed, \- use `blocked` to remove leakage/noise. 6. Enable **Auto Tune** if manual features are not producing healthy models. 7. Save and monitor build status. 8. Open the model and click **Activate** when diagnostics are acceptable. #### Examples ```bash curl -s -XPOST "https://api.lytics.io/ml" \ -H "Authorization: $LIOKEY" \ -H "Content-Type: application/json" \ -d '{ "name": "unknown_to_known_model", "source": "aud_unknown_users", "target": "aud_known_users_with_email", "config": { "auto_tune": true, "build_only": true, "use_scores": true, "use_content": true, "collect": 5000, "re_run": false } }' ``` ```bash curl -s -XGET "https://api.lytics.io/ml" -H "Authorization: $LIOKEY" curl -s -XGET "https://api.lytics.io/ml/unknown_to_known_model/summary" -H "Authorization: $LIOKEY" ``` #### Diagrams & Screenshots ![Lookalike model configuration wizard showing source/target and advanced options.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am2743f4cb06638c5c/4452c4302d63af5eba247509/lookalike_model_configuration_wizard_source.png) ### Summary Model configuration in the Lytics UI wizard requires only a source and target audience; everything else is optional but consequential. Starting with `use_scores` and `use_content` gives the model a strong behavioral signal without overfitting to niche fields. Use `blocked` to remove any fields that would introduce data leakage, and enable `auto_tune` when manual feature selection isn't producing healthy diagnostics. Activation is a separate, explicit step after build — build and activate are intentionally decoupled so you can review diagnostics before committing to production scoring. ### Documentation Links * [Lookalike Model API](https://docs.lytics.com/reference/lookalike-model-api) * [Model Configuration Options](https://docs.lytics.com/docs/lookalike-model-configuration) ## Understanding Your Model ### Learning Objectives By the end of this section, you will be able to: \- Interpret model results including score distributions and audience overlap \- Analyze feature importance to understand what drives the model's predictions \- Evaluate model quality and coverage to determine if the model meets success criteria ### Understanding Your Model After build, your job is to decide whether the model is fit for activation and how aggressively to threshold it in audience creation. #### Key Concepts * **Health summary is directional, not absolute**: use multiple signals before activating. * **Decision threshold sets precision vs reach**: * lower threshold increases audience size, * higher threshold increases selectivity. * **Predefined percentile audiences speed evaluation**: * **Unlikely**: below 25th percentile * **Somewhat Likely**: above 50th percentile * **Likely**: above 75th percentile * **Highly Likely**: above 90th percentile * **Feature importance helps governance**: verify top predictors are meaningful and acceptable from privacy/compliance perspective. #### Step-by-Step 1. In **Summary**, inspect health card values for `Accuracy`, `Reach`, and `R Squared`. 2. Use model exploration to compare source/target overlap and percentile segments. 3. Adjust the threshold slider to estimate reachable population at different cutoffs. 4. Inspect feature importance/correlation charts and confirm model logic is plausible. 5. Review **Diagnostics** for error profile and threshold values. 6. If model quality is weak: \- revisit source/target adjacency, \- expand relevant features, \- use Auto Tune, \- retrain and compare again. #### Examples ```lql FILTER AND ( INCLUDE unknown_users, segment_prediction_percentile.`unknown_to_known_model` >= 90 ) FROM user ``` ```text Interpretation rule of thumb: - Need scale: start with 50-75 percentile - Need conversion efficiency: start with 90+ percentile - Then tune using observed campaign outcomes ``` #### Diagrams & Screenshots ![Model diagnostics view with R squared, AUC, error rates, and decision threshold.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am8bb25208a6d75565/3fbaa83d3f77c3a4ff138897/model_diagnostics_view_r_squared.png) ### Summary Model evaluation is a multi-signal process: start with the health summary, then validate accuracy and reach against your pre-defined success criteria, then inspect feature importance for governance. The threshold slider is your primary precision/reach control — lower thresholds expand the reachable population while higher thresholds narrow it to the highest-confidence profiles. If the model doesn't meet your criteria, revisit source/target adjacency and feature selection before retraining rather than accepting a weak model for production activation. ### Documentation Links * [Model Diagnostics](https://docs.lytics.com/docs/lookalike-model-diagnostics) * [Threshold Explorer](https://docs.lytics.com/docs/lookalike-threshold-explorer) * [Feature Importance](https://docs.lytics.com/docs/lookalike-feature-importance) ## Activating ### Learning Objectives By the end of this section, you will be able to: \- Create audiences from lookalike scores using score thresholds \- Export lookalike audiences to advertising and marketing destinations \- Measure lookalike campaign performance and iterate on targeting ### Activating Activation operationalizes the model by writing/updating prediction fields on profiles and enabling predictive audience workflows for downstream channels. #### Key Concepts * **Activation switch behavior**: * **Activate**: starts profile scoring and audience eligibility updates. * **Deactivate**: stops future scoring; existing stored values remain until changed by future processing. * **Audience creation paths**: * quick editor in model view, * full audience builder using prediction/percentile fields. * **Model usage tracking**: **Audiences** tab lists audiences tied to a model. * **Activation should be tied to execution**: flows, exports, and on-site personalization should be prepared before turning on production targeting. #### Step-by-Step 1. Open model view and click **Activate**. 2. Wait for scoring to populate/update profile fields (`segment_prediction*` maps). 3. Create predictive audiences: \- start with one precision audience (for example percentile >= 90), \- optionally create one reach audience (for example percentile >= 60). 4. Connect these audiences to destinations in [Integrations & Connections](/academy/courses/lytics-course/integrations-connections) and personalization surfaces in [Pathfora](/academy/courses/lytics-course/pathfora). 5. Track performance against your goal and tune thresholds/features. 6. If needed, enable `re_run` retraining cadence and repeat evaluation. #### Examples ```bash curl -s -XPUT "https://api.lytics.io/ml/unknown_to_known_model" \ -H "Authorization: $LIOKEY" \ -H "Content-Type: application/json" \ -d '{"is_active": true}' ``` ```text Two-audience activation pattern: - High intent: percentile >= 90 (email/high-cost channels) - Expansion: percentile >= 60 (onsite/email nurture) ``` #### Diagrams & Screenshots ![Activation workflow from model status toggle to predictive audience exports and campaign measurement.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am0fb32c4c0bfc4477/d45f06c90163a56e686b0445/activation_workflow_model_status_toggle.png) ### Summary Activating a model starts profile scoring and makes prediction fields available for audience rules. The recommended pattern is a two-tier approach: a high-precision audience at the 90th percentile for high-cost channels and a broader reach audience at the 60th percentile for nurture and onsite experiences. Prepare your destination connections and flow configurations before activating in production, and establish a review cadence to tune thresholds as campaign performance data accumulates. ### Documentation Links * [Activating a Lookalike Model](https://docs.lytics.com/docs/lookalike-activation) * [Audience Export](https://docs.lytics.com/docs/audience-export) * [Flows](https://docs.lytics.com/docs/flows) ## What You've Learned In this section you covered the full Lytics lookalike model lifecycle. You learned how propensity models score profiles in a source audience based on their similarity to a target audience, and why clear source/target design is the highest-leverage step in the workflow. You walked through feature selection and configuration, learned to read model diagnostics — accuracy, reach, R Squared, AUC, decision threshold — and practiced the threshold strategy that balances precision against reach. Finally, you saw how activation writes scores to profile fields and enables the two-tier audience pattern that serves both high-intent and upper-funnel channels. ### Key Terms > 📘 **Source Audience** — The audience you want to score and take action on. All profiles in the source audience receive a prediction score after the model is activated. > > 📘 **Target Audience** — The audience that represents the outcome you want more users to resemble. The model learns what distinguishes target members from non-members. > > 📘 **segment\_prediction** — A profile meta field (map) that stores raw model score values, typically on a 0–1 scale, keyed by model name. > > 📘 **segment\_prediction\_percentile** — A profile meta field (map) that stores integer percentile ranks for each model, used for relative threshold-based audience creation. > > 📘 **Decision Threshold** — The score cutoff used to classify a profile as target-like or not. Lowering the threshold increases audience reach; raising it increases precision. > > 📘 **Auto Tune** — A model configuration option that allows Lytics to automatically select and weight features rather than relying on a manually specified feature set. > > 📘 **AUC (Area Under Curve)** — A model quality metric measuring the classifier's ability to distinguish target-like from non-target profiles across all possible thresholds. Higher is better. #### Key takeaways - Connect **Lookalike Model** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 13 — Reports #### Lesson text Reports is the configurable analytics workspace in Lytics for comparing audiences, field distributions, overlap, and dataflow across your account. Where per-audience summary views give you a single-audience lens, Reports gives you a multi-audience, reusable, and shareable analysis layer that translates data into activation decisions. This section covers how to navigate the Reports workspace, understand its two operating modes, configure components, manage visibility, and use all four component types effectively. ## Overview ### Learning Objectives By the end of this section, you will be able to: \- Navigate the Reports section of the Lytics platform \- Understand available report types and their intended use cases \- Identify when to use reports versus the Audience Insights App ### Overview **Reports** is the configurable analytics workspace for comparing audiences, fields, overlap, and dataflow. A report is a saved container of one or more configurable components (`size`, `composition`, `overlap`, `dataflow`); when starred, a report can also be surfaced as the app dashboard. In the current UI, Reports is a primary navigation destination (`/reports`) with list, detail, dashboard, and logs workflows. Use Reports when you need reusable, shareable analysis across teams. For one-audience exploration, start in audience summary views and then move to Reports for multi-audience comparison. #### Key Concepts * **Two report modes**: * **Dashboard Report**: starred report shown on the app dashboard. * **Custom Reports**: all other report objects you create for campaigns and operations. * **Account-level limits**: * Up to 25 reports per account in current UI. * Up to 20 components per report. * **Access control is enforced at render time**: * private reports restrict access to owner/collaborators (or sysadmin). * **Reports are operational, not static**: components can be edited, reordered, exported, and tied directly to activation decisions. #### Step-by-Step 1. Open **Reports** from main navigation. 2. Review existing reports list and note lock/star indicators: \- lock = private report, \- star = report used on dashboard. 3. Open a report and inspect: \- **Dashboard** tab for components, \- **Logs** tab for report change history. 4. Identify whether your question needs: \- point-in-time dashboarding, \- recurring campaign report, \- exploratory audience comparison. 5. Create or update report components accordingly. #### Examples ```text Question-to-report mapping: - "Which audience is growing fastest?" -> Size component - "Where are audiences overlapping?" -> Overlap component - "Which fields distinguish segments?" -> Composition component - "How do providers/streams/destinations connect?" -> Dataflow component ``` ```bash # List reports curl -s -XGET "https://api.lytics.io/v2/report" \ -H "Authorization: $LIOKEY" ``` #### Diagrams & Screenshots ![Reports index page showing report list, lock/star indicators, and create action.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ame864a03e0a87d3c4/5bca08d7f5dc917b7619f523/reports_index_page_report_list.png) ### Summary The Reports workspace is the primary tool for multi-audience analysis in Lytics. Each report is a named container of reusable components that can be shared with your team or kept private for work-in-progress analysis. Starting with the business question — growth, overlap, field composition, or pipeline traceability — determines which component types you need and how to configure them. ### Documentation Links * [Reports Overview](https://docs.lytics.com/docs/reports) * [Report Components](https://docs.lytics.com/docs/report-components) ## Dashboard Report ### Learning Objectives By the end of this section, you will be able to: \- Use pre-built dashboard reports to monitor key platform metrics \- Interpret dashboard metrics including audience growth, data volume, and engagement \- Customize dashboard views by adjusting date ranges, filters, and layout ### Dashboard Report The app dashboard renders the **starred** report. On newly provisioned accounts with baseline data coverage, Lytics creates a default **Dashboard Report** with baseline components so you can monitor audience and pipeline health immediately. From current backend setup logic, default dashboard components are: \- **Audience Performance** (`size`) on `all`, `smt_new`, and `smt_active` \- **Dataflow** (`dataflow`) on top used audiences \- **Content Affinity** (`composition`) on `lytics_content` \- **Audience Overlap** (`overlap`) on `all`, `smt_new`, and `smt_active` #### Key Concepts * **Dashboard is report-backed**: clicking **Edit Dashboard** opens the underlying report. * **Starred report behavior**: any starred report can function as dashboard report. * **No data/no starred report fallback**: dashboard can show an empty state until prerequisites are met. * **Dashboard and custom reports share component engine**: same component types, same editing model. #### Step-by-Step 1. Open the app home dashboard. 2. Click **Edit Dashboard** to open the backing report. 3. Review current components and remove anything not tied to your operating KPIs. 4. Add or tune components: \- **Size** for top lifecycle audiences, \- **Overlap** for suppression/leakage checks, \- **Composition** for key profile fields, \- **Dataflow** for integration path checks. 5. Save component configuration changes and review on dashboard. 6. Revisit weekly to keep dashboard aligned with current campaign priorities. #### Examples ```text Suggested dashboard KPI stack: 1) Size: acquisition, nurture, retention audiences 2) Overlap: acquisition vs customer suppression 3) Composition: lytics_content + behavioral score fields 4) Dataflow: audiences feeding priority destinations ``` ```bash # Get a specific report curl -s -XGET "https://api.lytics.io/v2/report/$REPORT_ID" \ -H "Authorization: $LIOKEY" ``` #### Diagrams & Screenshots ![Default dashboard report with size, dataflow, composition, and overlap components.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am26898fe5e9b33048/3fa67f2275795560afebbe0c/default_dashboard_report_size_dataflow.png) ### Summary The dashboard report is a starred report that surfaces your most important KPIs on the app home screen. It uses the same component engine as every other report, so editing it follows the same workflow. Treat the dashboard as a living document: remove components that no longer reflect current priorities, tune audience selections as campaigns evolve, and revisit the configuration weekly to keep it aligned with your team's operating focus. ### Documentation Links * [Dashboard Report](https://docs.lytics.com/docs/dashboard-report) * [Reports API](https://docs.lytics.com/reference/reports-api) ## Custom Report ### Learning Objectives By the end of this section, you will be able to: \- Create a custom report from scratch using the report builder \- Add and configure report components to visualize specific data \- Save and share custom reports with team members and stakeholders ### Custom Report Custom reports are where implementation teams operationalize analysis for campaign reviews, audience QA, and stakeholder updates. You can create reports manually or from accelerators (for example, prebuilt audience comparison actions) and then iterate on component configuration. #### Key Concepts * **Component-first model**: reports are containers; insights come from component design. * **Component scale limits**: * 20 components max per report. * **Report scale limits**: * 25 reports max per account. * **Reorder support**: drag-and-drop component order, then save order explicitly. #### Step-by-Step 1. In **Reports**, click **Create New**. 2. Enter report name and optional description. 3. Open report and click **Add New Component**. 4. Select component type and configure required inputs. 5. Add supporting components until the report answers a complete business question. 6. Reorder components for narrative flow, then click **Save Order**. 7. Review **Logs** tab to confirm changes were recorded. #### Examples ```bash # Create a report shell curl -s -XPOST "https://api.lytics.io/v2/report" \ -H "Authorization: $LIOKEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Q2_audience_health", "description": "Recurring audience health review", "private": false, "collaborators": [] }' ``` ```bash # Add a size component to an existing report curl -s -XPOST "https://api.lytics.io/v2/report/$REPORT_ID/component" \ -H "Authorization: $LIOKEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Audience Membership Comparison", "description": "Track core audience counts", "type": "size", "config": { "segment_ids": ["aud_1", "aud_2", "aud_3"], "table": "user", "type": "sizes", "duration": 7 } }' ``` #### Diagrams & Screenshots ![Custom report editor with add component modal and drag-to-reorder dashboard layout.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am633f9723379dea91/b7086aeab36d9aefcb633169/custom_report_editor_add_component.png) ### Summary Custom reports are the primary tool for campaign analysis, audience QA, and recurring stakeholder reviews. Build them around a single business question, add only the components needed to answer it completely, and name components clearly so their purpose is obvious to collaborators. The 20-component and 25-report account limits are practical guardrails — use them to encourage focused, purpose-built reports over sprawling catch-all dashboards. ### Documentation Links * [Creating Reports](https://docs.lytics.com/docs/reports) * [Report Component Configuration](https://docs.lytics.com/docs/report-components) * [Reports API](https://docs.lytics.com/reference/reports-api) ## Public vs Private ### Learning Objectives By the end of this section, you will be able to: \- Understand report visibility settings and the difference between public and private reports \- Configure public and private access on reports based on audience and sensitivity \- Share reports with stakeholders using the appropriate visibility setting ### Public vs Private Report collaboration has two layers: \- role-level access in account permissions, \- per-report visibility and collaborator configuration. By default, reports are generally visible to users with reporting access. Marking a report as private restricts visibility to the report author and selected collaborators (sysadmins can still access). #### Key Concepts * **Public report**: available to users who can access reporting. * **Private report**: only owner + named collaborators (+ sysadmin override). * **UI indicators**: * lock icon for private reports, * collaborator list shown on report summary for private reports. * **Logs for accountability**: report changes are tracked in the **Logs** tab. #### Step-by-Step 1. Open the report and click **Edit**. 2. In report configuration, toggle **Set Report as Private**. 3. If private, select collaborators explicitly. 4. Save and verify access using a non-owner test account when possible. 5. Review lock/collaborator indicators in report list and summary. 6. Use **Logs** to audit changes over time. #### Examples ```text Visibility decision pattern: - Public: recurring team dashboards and shared campaign reporting - Private: sensitive analysis, executive previews, work-in-progress reports ``` ```bash # Update report visibility curl -s -XPUT "https://api.lytics.io/v2/report/$REPORT_ID" \ -H "Authorization: $LIOKEY" \ -H "Content-Type: application/json" \ -d '{ "private": true, "collaborators": ["user_id_1", "user_id_2"] }' ``` #### Diagrams & Screenshots ![Report configuration form showing private toggle and collaborators selector.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am22f732e0bac9dc36/51e310d3572f4db79c4d2614/report_configuration_form_private_toggle.png) ### Summary Report visibility in Lytics operates at two levels: account-level role permissions control who can see the Reports workspace at all, and per-report private/public settings control which reports within that workspace are visible to which users. Use public visibility for shared team dashboards and recurring campaign reporting; use private visibility for sensitive analysis, in-progress work, or executive-facing content. The Logs tab provides an audit trail for all report changes regardless of visibility setting. ### Documentation Links * [Report Sharing and Visibility](https://docs.lytics.com/docs/report-sharing) * [Account Permissions](https://docs.lytics.com/docs/account-permissions) ## Component Types ### Learning Objectives By the end of this section, you will be able to: \- Identify all available component types and their visual representations \- Choose the right component type for the data you need to present \- Configure component settings and filters to display accurate, relevant information ### Component Types Current report UI supports four core component types: **Size**, **Composition**, **Audience Overlap**, and **Data Flow**. #### Key Concepts * **Size** (`type: "size"`): trends or numeric counts for one or more audiences. * Typical audience selection max: 5. * Chart options include `number` and `sizes` time series. * **Composition** (`type: "composition"`): distribution of a selected field/subfield across audiences. * Typical audience selection max: 5. * Chart options include `bar`, `line`, `pie`, `table`, `stats` (field-type dependent). * **Audience Overlap** (`type: "overlap"`): Venn-style intersections/exclusions. * Audience selection max: 3. * **Data Flow** (`type: "dataflow"`): provider/stream/audience/destination relationship view. * Audience selection max: 5. * Column visibility toggles for providers, streams, destinations. #### Step-by-Step 1. Start with the business question and choose the component type that best fits it. 2. Configure audience list first, then field/chart-specific settings. 3. For composition, confirm field type compatibility with desired chart type. 4. Toggle `stacked` and `show_missing` options where relevant. 5. Save, inspect output, and adjust labels/descriptions for stakeholder readability. 6. Export component CSV when needed for external analysis. #### Examples ```text Component selection guide: - Time trend / point-in-time size -> Size - Field distribution / profile traits -> Composition - Intersection and suppression analysis -> Overlap - Integration pathway troubleshooting -> Data Flow ``` ```bash # Replace a report component curl -s -XPUT "https://api.lytics.io/v2/report/$REPORT_ID/component/$COMPONENT_ID" \ -H "Authorization: $LIOKEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Membership Overlap", "type": "overlap", "config": { "segment_ids": ["aud_1", "aud_2", "aud_3"], "table": "user" } }' ``` #### Diagrams & Screenshots ![Component picker showing Composition, Size, Audience Overlap, and Data Flow options.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am2ee96b46a5632199/67b3696a1d989a219736a62a/component_picker_composition_size_audience.png) ### Summary The four component types map directly to the four most common analytical questions in Lytics: Size for growth and volume, Composition for understanding what distinguishes one audience from another, Overlap for identifying shared membership and suppression opportunities, and Data Flow for tracing integration paths from provider to destination. Matching the component type to the business question before configuration saves time and produces more interpretable outputs for stakeholders. ### Documentation Links * [Size Component](https://docs.lytics.com/docs/report-component-size) * [Composition Component](https://docs.lytics.com/docs/report-component-composition) * [Overlap Component](https://docs.lytics.com/docs/report-component-overlap) * [Data Flow Component](https://docs.lytics.com/docs/report-component-dataflow) ## What You've Learned In this section you explored the full Reports workspace in Lytics — from navigating the reports list and understanding the difference between dashboard and custom reports, to configuring visibility, building components, and selecting the right component type for each analytical question. Reports translate audience data into actionable insight by letting you compare multiple audiences simultaneously, track size trends, analyze field distributions, surface overlap, and trace integration paths — all in a reusable, shareable format. ### Key Terms > 📘 **Report** — A saved dashboard object in Lytics containing one or more configurable components (`size`, `composition`, `overlap`, `dataflow`) used for multi-audience analysis and stakeholder communication. > > 📘 **Dashboard Report** — The starred report rendered on the Lytics app home dashboard. Any report can be promoted to the dashboard by starring it. > > 📘 **Size component** — A report component that shows audience membership counts or trends over time for one or more audiences. > > 📘 **Composition component** — A report component that shows the distribution of a selected profile field across one or more audiences, used to understand behavioral and interest differences between segments. > > 📘 **Overlap component** — A report component that renders Venn-style intersection and exclusion analysis for up to three audiences, used to identify double-targeting or suppression opportunities. > > 📘 **Data Flow component** — A report component that maps the provider/stream/audience/destination relationship, used for integration path traceability and pipeline troubleshooting. > > 📘 **Private report** — A report visible only to its owner and explicitly named collaborators. Sysadmins retain access regardless of visibility setting. #### Key takeaways - Connect **Reports** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 14 — Flows #### Lesson text Flows is Lytics' visual orchestration engine for building multi-step profile journeys. Where an audience answers the question "who is this person right now?", a flow answers the question "what should happen next, and when?" This section walks you through the flow builder UI, the available components, common orchestration patterns, and the build-validate-publish process so you can confidently design and operate lifecycle automations in production. ## Overview ### Learning Objectives By the end of this section, you will be able to: \- Explain what flows are and when to use them for automated orchestration \- Navigate the flow builder UI and identify its key areas \- Understand the flow execution model including how users enter, progress, and exit flows ### Overview **Flows** is Lytics' visual orchestration system for profile journeys. A flow defines: * how a profile enters (triggered by audience membership conditions), * what should happen next (wait, split, export), * and when the profile should move through each step. Use flows when you need lifecycle automation across profile state and channel activation, especially when timing and branch logic matter. Key docs for reference: * [Flows Overview](https://docs.lytics.com/docs/flows) * [Getting Started](https://docs.lytics.com/docs/flows-getting-started) * [Creating a Flow](https://docs.lytics.com/docs/flows-creation) * [Publishing and Editing](https://docs.lytics.com/docs/flows-publishing) #### Key Concepts * **Flow state lifecycle**: * `draft`: editable and not processing users. * `running`: live and processing users. * `draining`: no new entries, existing users continue until they exit. * **Versioned model**: running versions are protected; you create a new draft version to make changes. * **Builder anatomy**: * **Flows list**: create/open/search flow definitions. * **Canvas**: visual DAG of steps and paths. * **Drawer**: step-level configuration. * **Publish modal**: validation and export activation checks. * **Entry model**: trigger step is required and cannot be removed. * **Profile visibility**: active flow step slugs can be exposed on user profiles as `flows_step_slugs` for personalization checks. #### Step-by-Step 1. Open **Flows** from the left navigation. 2. Select **Create New** and choose either: \- a template, or \- **Build Your Own**. 3. Name the flow and open the canvas. 4. Configure the trigger step first (audience, entry condition, re-entry behavior). 5. Add steps in sequence and label each step clearly. 6. Open **Publish** to run validation and resolve any configuration issues. 7. Activate exports from the publish flow, then publish. #### Examples ```text Appropriate flow scenarios: - Lifecycle onboarding with timed follow-ups. - Multi-channel re-engagement with different branches. - Triggering exports only after profile conditions are met. Scenarios better handled outside flows: - One-time static export without branching or timing. - A simple audience build problem that has no orchestration need. ``` #### Diagrams & Screenshots ![Flows dashboard and canvas overview.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am1f99367746152699/5ce163e51012aa922d3262d2/flows_dashboard_canvas_overview.png) ### Summary Flows provide a visual, versioned orchestration model for profile journeys. The three lifecycle states — draft, running, and draining — enforce a disciplined change process: you build and validate in draft, run live, and drain safely before retiring a version. The builder's canvas, drawer, and publish modal work together so you can configure, validate, and activate each step before committing to production. ### Documentation Links * [Flows Overview](https://docs.lytics.com/docs/flows) * [Getting Started with Flows](https://docs.lytics.com/docs/flows-getting-started) * [Creating a Flow](https://docs.lytics.com/docs/flows-creation) * [Publishing and Editing Flows](https://docs.lytics.com/docs/flows-publishing) ## Components ### Learning Objectives By the end of this section, you will be able to: \- Identify all flow component types available in the builder \- Understand the purpose and behavior of triggers, actions, conditions, delays, and splits \- Configure each component type with appropriate settings ### Components Flow components map directly to the available step types in the builder: **Trigger**, **Wait & Personalize**, **Conditional Split**, and **Export**. #### Key Concepts * **Trigger (required)**: * Defines who enters the flow. * Uses an audience and entry condition. * Cannot be deleted. * **Wait**: * Wait for fixed time, or wait until a condition becomes true. * Can include a personalization key slug for in-session targeting. * **Conditional Split**: * Branches users into **Yes** and **No** paths based on profile conditions. * Uses the same filtering model as audience logic. * **Export**: * Sends users to an external destination/workflow. * Must be valid and active before flow publish. Trigger options to teach exactly as shown in UI: * **Begin this Flow when a user is**: * **Added to** (`on_segment_entry`) * **Member of** (`in_segment`) * **Allow re-entry**: * No (single-pass) * Yes (with re-entry condition and delay) * **Re-enter this Flow when a user**: * **Enters the audience again** * **Enters or remains in the audience** * **Re-entry delay**: * minimum is 1 hour in the UI. Wait options to teach exactly as shown in UI: * **Wait for a set amount of time** (days/hours/minutes) * **Wait until a condition is true** (plus maximum time to wait) * Optional **Personalization key** (stored as `slug`; UI normalizes spaces to underscores) Publish validation behavior to teach: * flow needs at least one step beyond trigger, * trigger must be valid, * each wait must have a valid delay/condition, * split needs defined conditions, * export steps must be configured and activated. #### Step-by-Step 1. Configure trigger first: \- select entry audience, \- choose **Added to** or **Member of**, \- set re-entry rules if needed. 2. Add a **Wait** step: \- choose time-based or condition-based mode, \- if condition-based, define max wait time to avoid indefinite waits. 3. Add a **Conditional Split** for business logic branches. 4. Add **Export** steps on each branch as needed. 5. Give each step a descriptive label so metrics and profile troubleshooting are readable. 6. Run publish validation and resolve every warning/error before activation. #### Examples ```text Example component chain: Trigger: Added to "new_subscriber" -> Wait: 1 day + personalization key "welcome_day_1" -> Conditional Split: profile.email exists? -> Yes: Export to ESP welcome campaign -> No: Export to webhook for lead enrichment ``` ```text Example re-entry configuration: Trigger: "cart_abandoners_24h" Allow re-entry: Yes Re-entry condition: Enters the audience again Re-entry delay: 24 hours ``` #### Diagrams & Screenshots ![Flow components and drawer configuration examples.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am41475c5c5ade89f8/c12534ffb8d4056d504985f2/flow_components_drawer_configuration_examples.png) ### Summary Each flow step type has a distinct role: the Trigger controls entry (by audience membership, with optional re-entry rules), Wait steps pause progression by time or condition, Conditional Splits route profiles into Yes/No branches based on profile logic, and Export steps push profiles to external destinations. Publish validation enforces that every step is correctly configured before the flow goes live. ### Documentation Links * [Flow Step Types](https://docs.lytics.com/docs/flows-step-types) * [Flow Triggers](https://docs.lytics.com/docs/flows-triggers) * [Flow Exports](https://docs.lytics.com/docs/flows-exports) ## Use Cases ### Learning Objectives By the end of this section, you will be able to: \- Identify common flow patterns such as onboarding, re-engagement, and nurture sequences \- Match business use cases to the appropriate flow configurations \- Plan a flow design for a given business requirement before building it ### Use Cases Flows are most valuable when teams need controlled, repeatable progression logic from audience membership to downstream activation. #### Key Concepts * **Pattern over one-off**: design flows as reusable operating patterns. * **Audience quality first**: trigger audience quality determines flow quality. * **Branch intentionally**: every split should map to a business decision. * **Measure per step**: optimize by locating drop-off/wait bottlenecks. #### Step-by-Step 1. Start from the business objective (activate, recover, qualify, suppress, convert). 2. Define the trigger audience and entry model. 3. Choose time-based and condition-based waits based on user behavior expectations. 4. Add splits only where business outcomes differ. 5. Attach exports aligned to each branch outcome. 6. Define success metrics before publish. #### Examples ```text Welcome and activation flow: - Trigger: Added to "new_users" - Wait: 1 day - Export: Welcome email - Wait: until profile has first_session=true or max 7 days - Split: first_session true? - Yes: Export to product tips campaign - No: Export to activation reminder campaign ``` ```text Re-engagement and suppression flow: - Trigger: Member of "at_risk_users" - Export: Winback message - Wait: 3 days - Split: recent_purchase within 7 days? - Yes: Exit path / add to retention nurture - No: Export to higher-intent offer ``` ```text Lead qualification flow: - Trigger: Added to "new_leads" - Wait: until profile.email exists, max 48 hours - Split: lead_score >= threshold? - Yes: Export to CRM high-priority queue - No: Export to nurture sequence ``` #### Diagrams & Screenshots ![Common flow blueprints: welcome, re-engagement, and qualification flows built step-by-step in the builder.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am802f683edfbc3650/8982c40c0d11ee157a808640/common_flow_blueprints_welcome_re.gif) ### Summary The most common flow patterns — welcome and activation, re-engagement, and lead qualification — share the same structural logic: an audience-triggered entry, one or more wait steps that pause on time or condition, conditional splits that branch on profile state, and exports that deliver the right action to the right destination. Designing flows around these patterns before opening the builder ensures each branch has a clear business purpose. ### Documentation Links * [Flow Patterns and Examples](https://docs.lytics.com/docs/flows-patterns) * [Audience Building](https://docs.lytics.com/docs/audience-building) ## Tips and Tricks ### Learning Objectives By the end of this section, you will be able to: \- Debug flow execution issues using logs, status indicators, and test profiles \- Optimize flow performance by reducing unnecessary steps and managing audience sizes \- Avoid common flow pitfalls such as infinite loops, race conditions, and over-triggering ### Tips and Tricks Operational reliability comes from clear naming, careful re-entry settings, and disciplined validation before publish. #### Key Concepts * **Step names matter**: labels appear in metrics and help debugging. * **Re-entry control prevents over-messaging**: always set intentional delays. * **Condition waits need max guardrails**: avoid trapping users forever. * **Exports are dependencies**: keep credentials and destination configs current. * **Version discipline**: never assume you can hot-edit running flow logic. #### Step-by-Step 1. If users are not entering: \- verify trigger audience membership, \- confirm trigger condition (`Added to` vs `Member of`), \- confirm flow state is `running`. 2. If users stall in flow: \- inspect wait condition logic, \- check max wait values, \- review split condition logic for impossible criteria. 3. If exports fail: \- open publish panel and validate export state, \- re-activate steps if needed after new version creation, \- check destination-side credentials or schema expectations. 4. If volume spikes unexpectedly: \- audit re-entry settings, \- review audience churn rules, \- reduce broad `Member of` usage unless intentionally needed. #### Examples ```text Common misconfiguration: - Trigger set to "Member of" on a very large audience - Result: large immediate entry burst on publish - Safer alternative for most campaigns: "Added to" ``` ```text Common wait pitfall: - Wait-until condition with no realistic match and no practical max wait - Result: active count accumulates in wait step - Fix: tighten condition and set business-appropriate maximum wait ``` #### Diagrams & Screenshots ![Flow troubleshooting checklist and status indicators.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am35d2c48ce4f36562/48bab258e8f1b3cd69034778/flow_troubleshooting_checklist_status_indicators.png) ### Summary Most flow production issues fall into four categories: users not entering (check audience membership and trigger condition), users stalling (check wait logic and max-wait guardrails), export failures (validate export state and destination credentials), and unexpected volume spikes (audit re-entry settings and trigger type). Clear step labels, intentional re-entry delays, and condition-wait maximums prevent the majority of these issues before they occur. ### Documentation Links * [Troubleshooting Flows](https://docs.lytics.com/docs/flows-troubleshooting) * [Flow Versioning](https://docs.lytics.com/docs/flows-versioning) ## Define Goal and Journey ### Learning Objectives By the end of this section, you will be able to: \- Define clear flow goals before building, including desired outcomes and success metrics \- Map out the user journey from entry trigger through each decision point to exit \- Identify required audiences, actions, and integrations needed for the flow ### Define Goal and Journey Begin with a one-page journey plan before you open the UI so your flow design is deterministic and testable. #### Key Concepts * **One primary objective per flow**: acquisition, activation, conversion, retention, or recovery. * **Success criteria must be measurable**: * entries, * completion, * branch distribution, * downstream action rate. * **Journey contract**: each step should have a clear business purpose. * **Dependency mapping**: audience definitions, profile fields, exports, and consent requirements must exist before publish. #### Step-by-Step 1. Define goal statement: \- "When profiles enter audience X, drive outcome Y within Z days." 2. Define entry logic: \- source audience, \- `Added to` vs `Member of`, \- re-entry requirements. 3. Map journey states: \- each wait, \- each decision split, \- each export action, \- terminal outcomes. 4. Define safeguards: \- max waits, \- suppression conditions, \- re-entry delay constraints. 5. Define metric targets and review cadence. #### Examples ```text Journey design worksheet (example) Goal: Convert trial users to first key action in 7 days Trigger: Added to "trial_started" Wait 1: 1 day Action 1: Product onboarding email export Wait 2: until key_action_completed=true, max 5 days Split: key_action_completed? - Yes -> export to success tips stream - No -> export to assisted onboarding queue Success metric: >=30% branch to "Yes" within 7 days ``` #### Diagrams & Screenshots ![Flow planning worksheet example.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am5deaf00a9d54aa02/7c9aa7c1ad6257d6426dff51/flow_planning_worksheet_example.png) ### Summary A well-defined journey plan — one primary objective, a measurable success criterion, a step-by-step map of waits and splits, and an explicit list of audience and export dependencies — eliminates ambiguity before you touch the builder. Flows built from a documented plan are easier to validate, easier to hand off, and easier to optimize once live because every step has a stated purpose you can evaluate against. ### Documentation Links * [Flow Planning Best Practices](https://docs.lytics.com/docs/flows-best-practices) * [Audience Building](https://docs.lytics.com/docs/audience-building) ## Create and Validate Flow ### Learning Objectives By the end of this section, you will be able to: \- Build a flow step-by-step in the UI following the journey map \- Test and validate flow execution using test profiles and preview tools \- Monitor flow performance after launch and identify issues early ### Create and Validate Flow Treat build and validation as a release process: draft, validate, activate dependencies, publish, monitor, iterate by version. #### Key Concepts * **Validation is mandatory** before publish. * **Export activation is part of publish readiness**. * **New versions are the safe change path** for running flows. * **Metrics update every 24 hours**, not in real-time; evaluate with this reporting cadence in mind. #### Step-by-Step 1. Build draft flow from your journey map. 2. Configure trigger and all downstream steps. 3. Label steps and check each branch path for completeness. 4. Click **Publish** to run validation. 5. Resolve all invalid trigger, wait, split, or export states. 6. Activate every required export from publish flow. 7. Publish and confirm state moves to `running`. 8. Monitor initial entries and branch behavior. 9. For updates, create a new version, edit draft, and republish. #### Examples ```text Validation pass criteria before publish: - Trigger audience selected and entry condition intentional - At least one non-trigger step exists - All wait steps have valid time/condition values - All splits have valid conditions - All exports configured and activated ``` ```text Post-launch checks (first 24-48h): - Entry volume matches audience expectations - No branch starvation or impossible condition paths - Export destinations receiving expected payloads - Active vs completed counts moving in expected direction ``` #### Diagrams & Screenshots ![Publish validation modal with step readiness indicators.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amfaf086423bdc732e/0925eefe7324f6732e5e44bb/publish_validation_modal_step_readiness.png) ### Summary Building and publishing a flow is a structured release process: draft from your journey plan, run publish validation to surface every misconfiguration, activate required exports, publish, and monitor the first 24–48 hours to confirm entries, branch distributions, and downstream payloads are behaving as expected. When changes are needed on a running flow, create a new version rather than editing live — the versioned model is the safe path for all production modifications. ### Documentation Links * [Publishing a Flow](https://docs.lytics.com/docs/flows-publishing) * [Monitoring Flow Performance](https://docs.lytics.com/docs/flows-monitoring) * [Flow Versioning](https://docs.lytics.com/docs/flows-versioning) ## What You've Learned Flows give you a production-grade orchestration layer on top of Lytics audiences. You've learned how the versioned lifecycle — draft, running, draining — enforces a safe change process, how to configure each step type (Trigger, Wait, Conditional Split, Export), and how common patterns like onboarding, re-engagement, and lead qualification translate into concrete flow designs. You've also worked through the planning and validation discipline that separates flows that run reliably in production from ones that require constant intervention. ### Key Terms > 📘 **Flow** — A visual, versioned orchestration definition that controls how profiles enter, progress through steps, and exit based on audience membership and profile conditions. > > 📘 **Trigger** — The required entry step of a flow. Defines which audience drives entry and whether profiles enter once or can re-enter after a delay. > > 📘 **Wait Step** — A flow step that pauses a profile's progression for a fixed duration or until a profile condition becomes true, with an optional maximum wait time. > > 📘 **Conditional Split** — A flow step that evaluates a profile condition and routes the profile to a Yes or No branch, using the same filter logic as audience building. > > 📘 **Export Step** — A flow step that sends a profile to an external destination or workflow. Must be configured and activated before the flow can be published. > > 📘 **Flow State** — The operational status of a flow version: `draft` (editable, not processing), `running` (live and processing), or `draining` (no new entries, existing profiles continue to completion). > > 📘 **Personalization Key** — An optional slug on a Wait step that is written to the profile's `flows_step_slugs` field, making the current flow position available for on-site targeting decisions. #### Key takeaways - Connect **Flows** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 15 — Pathfora #### Lesson text Pathfora is the client-side presentation layer that translates Lytics audience data into visible on-site experiences. Once profiles are built and audiences are defined, Pathfora is how you act on that data in the browser — rendering modals, slideouts, bars, gates, and inline blocks targeted to the right visitors at the right moment. This section covers the architecture, the experience management workflow, the editor, the available widget types, common use cases, and how to interpret performance reporting so you can launch and optimize on-site personalization end-to-end. ## Overview ### Learning Objectives By the end of this section, you will be able to: \- Explain what Pathfora is and how it works with the Lytics JavaScript tag \- Understand the role of on-site experiences in personalization strategy \- Navigate the Pathfora management UI to view and organize experiences ### Overview **Pathfora** is the client-side presentation engine used by Lytics web experiences. It renders on-site modules such as modals, slideouts, bars, gates, and inline blocks based on profile context and targeting rules. Implementation typically uses two operating modes: * **Lytics-managed experiences**: configured in the Lytics Experiences UI and delivered by the JS Tag integration. * **Custom Pathfora SDK usage**: teams directly instantiate widgets in code for advanced customization. Primary references: * [Experiences](https://docs.lytics.com/docs/experiences) * [Pathfora SDK intro](https://docs.lytics.com/docs/personalization-pathfora) * [Lytics JavaScript Tag](https://docs.lytics.com/docs/lytics-javascript-tag) * [Pathfora developer docs](https://lytics.github.io/pathforadocs/) #### Key Concepts * **Tag dependency**: audience-aware targeting requires the Lytics JS Tag to load profile and segment data. * **Widget re-evaluation behavior**: * by default, widgets are evaluated at tag load, * and re-evaluated when `jstag.loadEntity` refreshes profile data. * **SPA optimization**: `pathfora.publish.listenForProfileChange=true` reduces unnecessary widget reloads by refreshing only dependency-based widgets. * **Experience candidate model**: experiences are selected from eligible candidates returned by Lytics and initialized in Pathfora. * **Preview support**: preview URLs use query parameters to force rendering of specific preview candidates. #### Step-by-Step 1. Ensure JS Tag is installed and profile loading is verified. 2. Open **Experiences** in Lytics to view existing experiences. 3. Create a new Lytics experience or import supported external experiences. 4. Configure targeting, display behavior, and schedule. 5. Activate and validate rendering on eligible pages. #### Examples ```javascript // SPA-friendly Pathfora behavior in JS Tag config jstag.init({ ...config, pathfora: { publish: { listenForProfileChange: true, }, }, }); ``` ```html ``` #### Diagrams & Screenshots ![Pathfora architecture: JS Tag, profile load, candidate selection, widget render.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am85312a90db368fba/d3e9155e82a358f9b0f3020c/pathfora_architecture_js_tag_profile.png) ### Summary Pathfora is the bridge between Lytics profile data and visible on-site action. It runs in the browser via the JS Tag, evaluates eligible experience candidates against the current visitor's profile, and renders the appropriate widget. Understanding the tag dependency, candidate selection model, and re-evaluation behavior is essential before configuring any targeting or display logic. ### Documentation Links * [Experiences Overview](https://docs.lytics.com/docs/experiences) * [Pathfora SDK](https://docs.lytics.com/docs/personalization-pathfora) * [Lytics JavaScript Tag](https://docs.lytics.com/docs/lytics-javascript-tag) ## Managing Experiences ### Learning Objectives By the end of this section, you will be able to: \- Create and organize experiences using folders and naming conventions \- Schedule and prioritize experiences to control when and how they appear \- Manage the experience lifecycle from draft through active to archived ### Managing Experiences Experience operations happen in the **Experiences** list and each **Experience summary** page. #### Key Concepts * **Creation modes**: * New experience (full editor flow). * Import (supported external providers). * **List operations**: * search, * filter by channel/integration/status/type, * sort by name or last modified. * **Lifecycle and health statuses** (system status): * Draft, * Active, * Paused, * Scheduled, * Externally Managed, * Ended, * Warning, * Error. * **Edit guardrail**: active experiences must be paused before editing. * **Schedule behavior**: * future start date sets Scheduled status, * automatic transition to Active at start, * optional end date auto-transitions to Ended. * **Priority handling**: * when multiple candidates qualify, tag + Pathfora initialize eligible widgets using configured priority mode (default `ordered` in tag integration). #### Step-by-Step 1. Open **Experiences** and click **Add Experience**. 2. Choose **New** or **Import**. 3. Name with consistent convention (channel, objective, audience, date). 4. Configure target audience and display rules. 5. Set date range (start/end). 6. Save, activate, and monitor status on summary page. 7. For edits to active experience: \- pause, \- edit and save, \- resume. 8. Archive or delete only after replacement/retirement plan is complete. #### Examples ```text Recommended naming pattern: [Channel]-[Objective]-[Audience]-[Quarter] Example: Web-LeadCapture-UnknownVisitors-Q2 ``` ```text Status-driven operations: - Draft -> finish configuration and activate - Active -> monitor and optimize - Paused -> edit safely - Scheduled -> verify future launch timing - Warning/Error -> investigate delivery or export health ``` #### Diagrams & Screenshots ![Experiences list view with status filters and summary actions.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am6664283772906285/3a1fc7f5227df806851fe0a2/experiences_list_view_status_filters.png) ### Summary The Experiences list is your operational control panel for all active, scheduled, and historical experiences. Consistent naming conventions, status-aware edit guardrails (pause before edit, resume after), and scheduled start/end dates keep a growing library of experiences manageable. Priority configuration controls which experience wins when multiple candidates qualify for the same visitor. ### Documentation Links * [Managing Experiences](https://docs.lytics.com/docs/managing-experiences) * [Experience Scheduling](https://docs.lytics.com/docs/experience-scheduling) * [Experience Priority](https://docs.lytics.com/docs/experience-priority) ## Experience Editor ### Learning Objectives By the end of this section, you will be able to: \- Use the visual experience editor to design on-site experiences \- Customize experience appearance and behavior including layout, copy, and actions \- Preview experiences before publishing to verify they render correctly ### Experience Editor The Experience Editor is a guided wizard. Steps vary by provider/tactic, but Lytics experiences generally include design, targeting, display, and review. #### Key Concepts * **Provider and tactic selection** controls the available workflow. * **Lytics tactics** include: * Drive Traffic, * Capture Leads, * Present a Message, * Recommend Content. * **Design step** configures layout, position, copy, image, theme, and optional custom CSS. * **Target step** binds the experience to an audience and shows potential reach. * **Display step** controls: * page matching rules (show/hide), * trigger conditions, * frequency caps, * CTA/close follow-up behavior, * date range. * **Preview** requires URL match with display rules, but audience targeting is ignored in preview mode for testing. #### Step-by-Step 1. Create or open an experience and enter editor. 2. Select provider and tactic. 3. Complete tactic-specific setup (URL, form fields, or recommendation settings). 4. In **Design**: \- choose layout, \- set copy and CTA, \- apply theme or custom CSS. 5. In **Target**: \- select audience, \- validate potential reach. 6. In **Display**: \- define appears-on rules, \- set trigger and frequency controls, \- set date range. 7. In **Review**: \- run preview on real URL, \- save and exit. 8. Activate from summary page. #### Examples ```text Display rule strategy: - Show on URL contains "/blog/" - Hide on URL contains "/blog/admin" - Trigger after 10 seconds and 50% scroll - Show max 1 time per session ``` ```text Capture Leads tactic form design: - Enable: email, name - Require: email - CTA: "Get updates" - Hide permanently after successful submit ``` #### Diagrams & Screenshots ![Experience editor flow: provider selection, design, target, display, and review steps.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am504321d9284c6ff0/d0ea4974666fd6df41f1c552/experience_editor_flow_provider_selection.gif) ### Summary The Experience Editor walks you through provider and tactic selection, design configuration (layout, copy, theme, CSS), audience targeting with reach validation, and display rules (page matching, triggers, frequency caps). Preview mode lets you verify rendering on a real URL without requiring audience membership, so you can confirm visual correctness before going live. ### Documentation Links * [Experience Editor](https://docs.lytics.com/docs/experience-editor) * [Display Rules](https://docs.lytics.com/docs/experience-display-rules) * [Experience Targeting](https://docs.lytics.com/docs/experience-targeting) ## Out-of-the-Box Experience Types ### Learning Objectives By the end of this section, you will be able to: \- Identify all built-in experience types including modals, slide-ins, bars, gates, and inline \- Choose the right experience type for your use case based on intrusiveness and goal \- Configure modals, slide-ins, bars, gates, and inline experiences with appropriate settings ### Out-of-the-Box Experience Types Pathfora supports multiple module types (`message`, `form`, `subscription`) and layouts. In Lytics training, focus on layouts most used for on-site experiences. #### Key Concepts * **Modal**: * high attention, * supports image, * good for strong CTA or lead capture. * **Slideout**: * lower interruption, * supports multiple corner/side positions, * useful for contextual nudges. * **Bar / Sticky Bar**: * full-width slim message area, * top or fixed positions, * good for announcements/promotions. * **Gate**: * modal-like with no close affordance, * user must act to continue, * suited for high-value content gating. * **Inline**: * injected into specified container, * ideal for embedded recommendations and page-native experiences. Important behavior details: * Gate unlock state is persisted via Pathfora cookie. * Inline modules require `positionSelector` and do not use close/cancel behavior like overlays. * Bar layout does not use `headline` in the same way as modal/slideout. #### Step-by-Step 1. Pick objective: inform, convert, capture, gate, or recommend. 2. Pick layout based on interruption tolerance and page context. 3. Pick module type (`message`, `form`, `subscription`) based on data collection need. 4. Configure layout-specific options (position, image, selector, push-down). 5. Test on desktop and mobile before activation. #### Examples ```text Layout selection by goal: - Announcement banner -> Bar - Newsletter capture -> Slideout form - Resource lock + lead form -> Gate - In-article recommendations -> Inline - Urgent conversion prompt -> Modal ``` ```javascript // Minimal custom Pathfora message example const module = new pathfora.Message({ id: "promo_bar_q2", layout: "bar", msg: "New feature release: explore what's new.", okMessage: "Learn more", }); pathfora.initializeWidgets([module]); ``` #### Diagrams & Screenshots ![Visual comparison of modal, slideout, bar, gate, and inline experience types.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ambe9929797a129924/b039eaec39accf42c9cf6772/visual_comparison_modal_slideout_bar.png) ### Summary Pathfora's five layout types — modal, slideout, bar, gate, and inline — cover the full range of on-site intervention patterns from low-interruption nudges to hard content gates. Choosing the right layout starts with the business objective, then factors in interruption tolerance and page context. Each layout has specific behavioral constraints (gate persistence via cookie, inline's `positionSelector` requirement, bar's headline behavior) that affect configuration and testing. ### Documentation Links * [Pathfora Widget Types](https://docs.lytics.com/docs/pathfora-widget-types) * [Pathfora SDK Reference](https://lytics.github.io/pathforadocs/) ## Use Cases ### Learning Objectives By the end of this section, you will be able to: \- Identify common personalization use cases such as lead capture, content promotion, and engagement \- Design experiences for lead capture, content promotion, and visitor engagement scenarios \- Combine Pathfora experiences with audience targeting for precise personalization ### Use Cases Use Pathfora where real-time audience context should shape the on-site message, timing, or action path. #### Key Concepts * **Unknown vs known journey**: deliver identity-capture only to users who need it. * **Audience-specific messaging**: tie creative to lifecycle state. * **Behavior-triggered timing**: use display conditions (delay, scroll, pageviews, exit intent). * **Frequency governance**: avoid fatigue with impression and session caps. #### Step-by-Step 1. Define audience and business outcome. 2. Select layout and module type. 3. Configure display triggers and frequency limits. 4. Configure CTA action and post-action hide behavior. 5. Launch, then optimize from reporting. #### Examples ```text Lead capture for anonymous traffic: - Audience: users without known email - Type/layout: subscription slideout - Trigger: show after 2 pageviews and 20 seconds - Frequency: 1 per session, max 5 ever - Post-submit: hide permanently ``` ```text Content promotion for engaged users: - Audience: high-affinity readers - Type/layout: inline recommendation module - Display: only on blog URLs - Goal: increase click-through to recommended content ``` ```text Exit-intent rescue: - Audience: cart abandoners - Type/layout: modal message or form - Trigger: show on exit intent - CTA: return to checkout with incentive ``` #### Diagrams & Screenshots ![Common Pathfora use case blueprints: lead capture, content promotion, and exit-intent rescue configured in the Experiences UI.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ame8fab2157b04f261/6e90fb15242d11e601732526/common_pathfora_case_blueprints_lead.gif) ### Summary Effective Pathfora use cases share a common structure: a precisely defined audience, a layout chosen for the interruption level the moment warrants, display triggers calibrated to visitor intent signals, and frequency caps that prevent fatigue. Lead capture targets anonymous visitors, content promotion targets engaged known visitors, and exit-intent experiences target high-value drop-off moments — each requiring a different audience, trigger, and message strategy. ### Documentation Links * [Web Personalization Use Cases](https://docs.lytics.com/docs/web-personalization-use-cases) * [Lead Capture](https://docs.lytics.com/docs/lead-capture) * [Content Recommendations](https://docs.lytics.com/docs/content-recommendations) ## Experience Reporting ### Learning Objectives By the end of this section, you will be able to: \- Access experience performance metrics from the reporting interface \- Interpret engagement and conversion data including impressions, clicks, and submissions \- Optimize experiences based on performance data to improve results over time ### Experience Reporting Performance review starts on each Experience summary page. #### Key Concepts * Core performance metrics: * **Reached**: unique users reached. * **Clicks**: unique users who clicked. * **Click Rate**: clicks divided by reached. * **Update cadence** for these metrics is documented as **every 2 hours**. * Optional **Experience Intelligence** modules may be available when Lytics View is enabled. * Reporting should be paired with configuration context (target audience, triggers, frequency, schedule) to interpret results correctly. #### Step-by-Step 1. Open experience summary page. 2. Review Reached, Clicks, and Click Rate trend. 3. Compare against expected reach from target audience. 4. If underperforming, diagnose in order: \- audience too narrow/broad, \- display rules too restrictive, \- trigger too late/early, \- CTA/copy mismatch, \- frequency too aggressive or too limited. 5. Pause, edit, and resume with one meaningful change at a time. 6. Re-measure after sufficient volume accumulates. #### Examples ```text Optimization loop example: Week 1: low reached, low clicks -> broaden appears-on rule Week 2: reached improves, click rate flat -> revise CTA copy/theme Week 3: click rate improves -> lock baseline and test trigger timing ``` ```text Diagnostic pattern: High reached + low click rate -> message/layout issue Low reached + good click rate -> targeting or display constraint issue ``` #### Diagrams & Screenshots ![Experience summary reporting with reached, clicks, and click rate metrics.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am8aa6b6e61e246acc/697457e52e56a0bc244d34b0/experience_summary_reporting_reached_clicks.png) ### Summary Experience reporting surfaces three core metrics — Reached, Clicks, and Click Rate — updated every two hours on each experience's summary page. The diagnostic approach pairs metric patterns against configuration: low reach points to targeting or display rule constraints, while high reach with a low click rate points to creative or layout issues. Optimizing one variable at a time, then re-measuring after sufficient volume, is the disciplined path to improving performance. ### Documentation Links * [Experience Reporting](https://docs.lytics.com/docs/experience-reporting) * [Experience Intelligence](https://docs.lytics.com/docs/experience-intelligence) ## What You've Learned Pathfora closes the loop between Lytics audience data and the on-site visitor experience. You've learned how the JS Tag powers candidate selection and widget rendering, how to manage the experience lifecycle from draft through active and archived, how the editor's design-target-display-review workflow maps to production-ready configuration, which widget types to choose for which objectives, and how to interpret performance metrics to drive continuous optimization. ### Key Terms > 📘 **Pathfora** — The client-side JavaScript presentation engine that renders targeted on-site modules (modals, slideouts, bars, gates, inline blocks) based on Lytics profile and audience data. > > 📘 **Experience** — A configured, audience-targeted on-site interaction unit managed in the Lytics UI. Experiences have a lifecycle (Draft, Active, Paused, Scheduled, Ended) and deliver via Pathfora. > > 📘 **Widget** — A single Pathfora module instance: a specific layout type (`message`, `form`, `subscription`) rendered to a visitor based on audience eligibility and display rules. > > 📘 **Experience Candidate** — An experience that is eligible for a given visitor based on audience membership. Multiple candidates may qualify; priority configuration determines which is rendered. > > 📘 **Display Rules** — Configuration on an experience that controls which pages it appears on (appears-on / hide-on URL rules), when it triggers (time delay, scroll depth, exit intent), and how frequently it shows (per-session and lifetime caps). > > 📘 **Reached** — The count of unique users who were shown an experience. One of the three core performance metrics alongside Clicks and Click Rate. > > 📘 **Gate** — A Pathfora widget layout with no close affordance. The visitor must complete an action to proceed. Gate unlock state is persisted via a Pathfora cookie. > > 📘 **Inline** — A Pathfora widget layout injected directly into a specified page container via `positionSelector`, delivering a page-native experience without overlaying the content. #### Key takeaways - Connect **Pathfora** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 16 — Use Cases #### Lesson text This capstone section ties together everything covered in the course by walking through six end-to-end implementation patterns that teams deploy most often on the Lytics platform. Each use case maps a business objective to the specific audiences, experiences, flows, exports, and measurement approaches needed to execute it. By the end of this section you will have a repeatable implementation template for unknown-to-known conversion, lead capture, lead nurture and conversion, customer suppression, server-side conversion event export, and personalized product recommendations. ## Unknown to Known ### Learning Objectives By the end of this section, you will be able to: \- Design a strategy for converting anonymous visitors to identified users \- Implement identity collection touchpoints using forms, gated content, and progressive profiling \- Measure unknown-to-known conversion rates and track improvement over time ### Unknown to Known This use case turns anonymous web traffic into known profiles with strong identifiers (typically email), then uses that identity in downstream activation channels. Core references: * [Lead Capture guide](https://docs.lytics.com/docs/lead-capture) * [JavaScript Tag](https://docs.lytics.com/docs/lytics-javascript-tag) * [Experiences](https://docs.lytics.com/docs/experiences) #### Key Concepts * **Anonymous vs known profile state**: * anonymous: behavior tracked, no strong identifier, * known: email or other durable ID present. * **Identity capture touchpoint**: Pathfora form, inline form, registration flow, or backend event. * **Strong identifier strategy**: * collect minimum required ID first (email), * progressively collect additional attributes later. * **Measurement pattern**: * audience size comparison of anonymous vs known, * campaign impressions (`ly_impressions`) and conversions (`ly_conversions`) for capture experiences. #### Step-by-Step 1. Verify JS Tag is installed and collecting events. 2. Ensure required profile/audience fields are surfaced for web personalization use. 3. Build or validate audiences for anonymous and known states. 4. Launch identity-capture experience targeted to anonymous audience only. 5. Submit known identifier into profile (via form submission and/or explicit identify call). 6. Confirm profile transition from anonymous to known. 7. Create reporting component comparing anonymous vs known audience trend over time. #### Examples ```javascript // Explicit identity capture fallback in custom flow jstag.identify({ email: "person@example.com", first_name: "Casey", }); ``` ```javascript // Pathfora lead capture targeted to anonymous audience jstag.on("pathfora.publish.done", function () { var module = new pathfora.Form({ id: "lead-capture-form", layout: "slideout", theme: "dark", headline: "Stay updated", msg: "Share your email for product updates", formElements: [{ type: "email", required: true, label: "Email", name: "email" }], }); pathfora.initializeWidgets({ target: [{ segment: "anonymous_profiles", widgets: [module] }], }); }); ``` #### Diagrams & Screenshots ![Unknown-to-known lifecycle from anonymous visit to identified profile, showing audience configuration, Pathfora form setup, and profile transition in the UI.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am878d647b35fa7751/c31b64400e2b4fb38f4ab0a1/unknown_known_lifecycle_anonymous_visit.png) ### Summary The unknown-to-known pattern begins with a clear distinction between anonymous and known profile states and a capture touchpoint — typically a Pathfora form — targeted exclusively to anonymous visitors. The identity signal collected (usually email) is written to the profile and triggers the transition to known status, unlocking that profile for all downstream activation channels that require a durable identifier. ### Documentation Links * [Lead Capture](https://docs.lytics.com/docs/lead-capture) * [JavaScript Tag Identity](https://docs.lytics.com/docs/lytics-javascript-tag#identity) * [Audience Building](https://docs.lytics.com/docs/audience-building) ## Capture Leads ### Learning Objectives By the end of this section, you will be able to: \- Design lead capture experiences tailored to visitor segments and page context \- Configure audience-targeted lead forms that appear to the right users at the right time \- Route captured leads to downstream systems such as CRM and marketing automation platforms ### Capture Leads Lead capture builds on unknown-to-known by adding targeting controls, conversion-safe UX, and reliable downstream routing. #### Key Concepts * **Audience-first lead capture**: * do not show lead form to users already known, * tailor trigger by behavior and intent. * **Display governance**: * trigger timing (delay, scroll, pageviews, exit intent), * frequency caps per session and lifetime. * **Form design**: * collect minimum viable data first, * enforce required email where needed. * **Routing pattern**: * use export jobs or webhook audience triggers to sync captured leads to CRM/ESP in real time. #### Step-by-Step 1. Build a lead-eligible audience (example: anonymous users active in last 7 days). 2. Build an exclusion audience for known or already-converted users. 3. Configure Pathfora lead form: \- layout and copy, \- required fields, \- target audience, \- display conditions, \- frequency limits. 4. Configure downstream export: \- webhook or integration destination, \- field mapping, \- enter/exit trigger behavior, \- optional backfill. 5. Validate end-to-end with test profile: \- form shows for eligible profile, \- submission updates profile, \- export event arrives downstream. #### Examples ```text Lead capture trigger policy example: - Show on blog pages only - Show after 20 seconds OR 50% scroll - Max 1 time per session - Hide permanently after successful submit ``` ```json { "id": "15761203643149024539", "data": { "email": "newlead@example.com", "segment_events": [ { "event": "enter", "slug": "lead_capture_qualified" } ] } } ``` #### Diagrams & Screenshots ![Lead capture flow from audience targeting through form submit to CRM sync, demonstrated end-to-end in the Lytics UI.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amd72ccd7f42420969/1d2d50acb7d582d40a7a0764/lead_capture_flow_audience_targeting.png) ### Summary Effective lead capture requires three aligned layers: an audience that precisely identifies who should see the form (excluding already-known users), a Pathfora experience configured with intent-aligned triggers and frequency governance, and a downstream export job that routes captured leads to the CRM or ESP in real time. Validating the full pipeline with a test profile before launch confirms each layer is functioning correctly. ### Documentation Links * [Lead Capture](https://docs.lytics.com/docs/lead-capture) * [Experiences](https://docs.lytics.com/docs/experiences) * [Export Jobs](https://docs.lytics.com/docs/export-jobs) ## Convert Lead ### Learning Objectives By the end of this section, you will be able to: \- Design lead nurturing flows that guide prospects toward conversion \- Create targeted on-site experiences for known leads based on engagement and intent signals \- Measure lead conversion effectiveness and optimize the funnel ### Convert Lead This use case connects audience progression, flow orchestration, and on-site/off-site actions to move known leads to conversion. #### Key Concepts * **Nurture orchestration**: Flows coordinate trigger, wait, split, and export actions. * **Behavior-based progression**: users move by audience/state changes rather than fixed one-size-fits-all sequencing. * **Conversion event definition**: conversion should be an explicit audience condition (purchase, demo booked, MQL threshold reached). * **Mutual exclusion logic**: converted users should be removed from acquisition-stage messaging paths. #### Step-by-Step 1. Define lead lifecycle audiences: \- new lead, \- marketing-qualified lead, \- sales-qualified, \- converted customer. 2. Build a flow triggered by lead-entry audience. 3. Add nurture sequence: \- wait step(s), \- conditional split(s) by profile attributes or engagement, \- export step(s) to email/CRM/ads. 4. Add suppression or exit branch for converted users. 5. Optionally add Pathfora experience for high-intent known leads on key pages. 6. Track stage conversion with audience movement and experience/flow metrics. #### Examples ```text Lead nurture flow pattern: Trigger: Added to "new_leads" -> Wait: 1 day -> Export: onboarding email -> Wait until lead_score >= 60 (max 7 days) -> Split: lead_score >= 60? Yes -> Export to CRM MQL queue No -> Export to low-intent nurture stream -> Exit if user joins "customers" ``` ```javascript // Refresh profile and campaign eligibility on SPA route changes router.onRouteChange(function () { jstag.pageView(); jstag.loadEntity(); }); ``` #### Diagrams & Screenshots ![Lead conversion journey with flow branches and conversion audience exit, configured in the Flows UI.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am8c98811cdbd0677d/8571b6afb09ef407d4586f50/lead_conversion_journey_flow_branches.png) ### Summary Lead conversion orchestration depends on four well-defined lifecycle audiences (new lead, MQL, SQL, converted customer), a flow that routes profiles through nurture steps and splits on behavioral signals like lead score, and a clear exit condition that removes converted users from acquisition messaging. Adding a Pathfora experience for high-intent known visitors on key conversion pages closes the on-site channel alongside the off-site email and CRM touchpoints. ### Documentation Links * [Flows](https://docs.lytics.com/docs/flows) * [Audience Building](https://docs.lytics.com/docs/audience-building) * [Experiences](https://docs.lytics.com/docs/experiences) ## Suppress Existing Customer ### Learning Objectives By the end of this section, you will be able to: \- Build suppression audiences for existing customers using profile attributes and behaviors \- Configure exclusion rules in advertising and marketing destinations \- Validate that suppression is working correctly by testing audience membership and exports ### Suppress Existing Customer Suppression protects budget and customer experience by excluding people who have already converted or should not receive acquisition messaging. #### Key Concepts * **Suppression audience**: explicit audience for existing customers (example: purchase exists). * **Acquisition audience**: include prospect criteria and exclude suppression audience. * **Goal-level suppression rule**: * suppression can be safely applied at overall audience level, * avoid exclusions that break downstream conversion-stage logic. * **Destination parity**: suppression must be consistent across all acquisition channels. #### Step-by-Step 1. Define `existing_customers` audience (purchase/order/subscription criteria). 2. Define acquisition audience as prospects **excluding** existing customers. 3. Apply acquisition audience to all paid or outreach destinations. 4. For server-side destinations, configure enter/exit trigger exports so suppression updates propagate quickly. 5. Test with known customer and known prospect profiles. 6. Monitor audience size drift and destination sync health. #### Examples ```text Audience pattern: - existing_customers: total_orders > 0 OR subscription_status = "active" - acquisition_candidates: all_users AND NOT existing_customers ``` ```text Validation checks: - Known customer appears in suppression audience - Known customer does not appear in acquisition audience - Destination receives expected exit/remove event for customer profile ``` #### Diagrams & Screenshots ![Suppression architecture from customer audience to multi-destination exclusion, showing audience builder configuration and export setup.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am38a59c794f93008c/0ded0d036789cd51e19f5081/suppression_architecture_customer_audience_multi.png) ### Summary Customer suppression is an audience-first approach: define existing customers precisely, build acquisition audiences that exclude them explicitly, and apply that exclusion consistently across every paid and outreach destination. Enter/exit trigger exports ensure suppression propagates to destinations in near real time when a prospect converts, protecting both budget and customer experience. ### Documentation Links * [Audience Building](https://docs.lytics.com/docs/audience-building) * [Export Jobs](https://docs.lytics.com/docs/export-jobs) * [Suppression](https://docs.lytics.com/docs/audience-suppression) ## Conversion API ### Learning Objectives By the end of this section, you will be able to: \- Use the Conversion API for offline and server-side event tracking \- Structure conversion events correctly with required fields and proper formatting \- Validate that conversions are attributed to the correct user profiles ### Conversion API This pattern has two layers: 1. capture conversion intent in Lytics profile/events, 2. export server-side conversion events to destination conversion APIs (Meta, Google, LinkedIn, etc.). #### Key Concepts * **Server-side conversion sync** improves matching and measurement reliability. * **Identity fields are mandatory** (email/phone and/or platform IDs depending on destination). * **De-duplication fields** like event ID/order ID are critical for clean attribution. * **Trigger model**: * most conversion API exports are audience-triggered, * many run continuously in batched near-real-time cycles. #### Step-by-Step 1. Define conversion audience in Lytics (example: completed purchase or offline close). 2. Ensure required identifiers are present and normalized on profile. 3. Configure destination conversion API export job (Meta/Google/LinkedIn). 4. Map required fields: \- event name/type, \- timestamp, \- user identifiers, \- currency/value where applicable, \- de-dup/event ID when supported. 5. Choose trigger events (enter, exit, or both) and optional existing-user backfill. 6. Start job and validate destination-side acceptance. 7. Reconcile sample user conversions between Lytics and destination reporting. #### Examples ```javascript // Capture conversion signal into Lytics from web app jstag.send({ event: "conversion", campaign_id: "spring_offer", variation_id: "variant_a", currency: "USD", value: 25.99, }); ``` ```json [ { "event_name": "Purchase", "event_id": "sample-event-id", "event_time": 1654729272, "user_data": { "em": "" }, "custom_data": { "currency": "USD", "value": 123 } } ] ``` #### Diagrams & Screenshots ![Server-side conversion pipeline from Lytics audience triggers to destination conversion APIs, showing export job configuration.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am0e3dcab20bb2520a/e70b6eec06780796d4dcdc7f/server_side_conversion_pipeline_lytics.png) ### Summary Server-side conversion event export provides ad platforms with a richer, more reliable signal than browser-side pixels alone. The pattern requires a well-defined conversion audience in Lytics, normalized identity fields on profiles, and correctly mapped export jobs that include event name, timestamp, user identifiers, and de-duplication IDs. Validating destination-side acceptance and reconciling sample conversions confirms the pipeline is working before scaling. ### Documentation Links * [Conversion API Export](https://docs.lytics.com/docs/conversion-api) * [Meta Conversion API](https://docs.lytics.com/docs/meta-conversion-api) * [Google Enhanced Conversions](https://docs.lytics.com/docs/google-enhanced-conversions) ## Product Recommendation ### Learning Objectives By the end of this section, you will be able to: \- Configure product and content recommendation strategies within the platform \- Deliver personalized recommendations via Pathfora experiences or the API \- Measure recommendation engagement and conversion to evaluate effectiveness ### Product Recommendation This use case delivers content or product suggestions personalized to each user's affinity profile. Key references: * [Content Recommendations](https://docs.lytics.com/docs/recommendations) * [Pathfora recommendations](https://lytics.github.io/pathforadocs/content_recommend/) #### Key Concepts * **Prerequisite pipeline**: * content must be classified, * topic graph and affinities need enough processing time (commonly 24-48 hours after setup). * **Collection-scoped recommendations**: * use content collections to control recommendation corpus, * API uses `contentsegment` as collection selector. * **Delivery methods**: * Lytics Experience in UI, * Pathfora recommend widget, * JS Tag recommend plugin, * direct recommendation API. * **Quality control**: * audience-to-collection affinity alignment should be moderate/high. #### Step-by-Step 1. Verify classification coverage and interest signals exist on profiles. 2. Select or create content collection for recommendation scope. 3. Choose delivery surface: \- modal/slideout recommendation, \- inline recommendation blocks, \- custom API-powered placement. 4. Configure audience targeting and page placement rules. 5. Launch and validate recommendation response quality. 6. Measure clicks and downstream conversion behavior. 7. Iterate on collection scope, ranking, and placement. #### Examples ```javascript // JS Tag recommendation request jstag.recommend( { collection: "all_content", limit: 3, visited: true, shuffle: false, }, function (items) { console.log("recommendations", items); } ); ``` ```javascript // Pathfora recommendation widget snippet var module = new pathfora.Message({ id: "content-rec-sample", layout: "slideout", headline: "Recommended for you", recommend: { collection: "all_content" }, variant: 3, }); pathfora.initializeWidgets({ target: [{ segment: "all", widgets: [module] }], }); ``` ```text API endpoint pattern: GET /api/content/recommend/{cid}/user/{fieldName}/{fieldVal}?contentsegment={collection_id}&limit=3 ``` #### Diagrams & Screenshots ![Recommendation flow from content graph to API and widget delivery, showing collection configuration, Pathfora recommend widget setup, and validation of response quality.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ama433d66426774248/aa4cd77fc261bb52a0394f08/recommendation_flow_content_graph_api.gif) ### Summary Personalized recommendations depend on a functioning content classification pipeline and sufficient affinity signal on profiles before delivery quality is meaningful. Once the prerequisite pipeline is in place, you scope recommendations via content collections, choose a delivery surface (Lytics Experience UI, Pathfora widget, JS Tag plugin, or direct API), and measure engagement to iterate on collection scope and placement. Audience-to-collection affinity alignment is the primary quality lever. ### Documentation Links * [Content Recommendations](https://docs.lytics.com/docs/recommendations) * [Content Collections](https://docs.lytics.com/docs/content-collections) * [Pathfora Recommendations](https://lytics.github.io/pathforadocs/content_recommend/) * [Recommendation API](https://docs.lytics.com/docs/recommendation-api) ## What You've Learned This section brought together the full Lytics platform across six end-to-end use cases. Unknown-to-known and lead capture establish the identity foundation that makes everything else possible. Lead conversion and customer suppression apply that identity data to lifecycle orchestration and budget protection. Conversion API export closes the measurement loop by feeding high-fidelity signals back to ad platforms. Product recommendations put content affinity scores to work as a direct personalization surface. Each pattern is a repeatable template — the specific audiences, experiences, flows, and exports change per client, but the structural logic is consistent across implementations. ### Key Terms > 📘 **Unknown Profile** — A Lytics profile for a visitor who has been tracked behaviorally but has no strong identifier (such as email) present. Can be targeted for identity capture but cannot be activated in most off-site channels. > > 📘 **Known Profile** — A Lytics profile that has at least one durable identifier (typically email) present. Eligible for activation across all channels including email, CRM, and paid media. > > 📘 **Identity Capture Touchpoint** — A mechanism through which a visitor's identifier is collected and written to their profile: a Pathfora form, a registration flow, a backend identify call, or an imported CRM record. > > 📘 **Suppression Audience** — An audience representing users who should be excluded from acquisition messaging — typically existing customers or recently converted leads. > > 📘 **Conversion API** — A server-side integration pattern in which Lytics exports conversion events directly to ad platform APIs (Meta, Google, LinkedIn), bypassing browser-side pixel limitations to improve match rates and attribution accuracy. > > 📘 **Content Collection** — A curated subset of classified content items used to scope recommendation responses. Collections control the corpus from which the recommendation engine selects items for a given user. > > 📘 **Lead Score** — A profile attribute that quantifies a lead's readiness to convert, typically computed from engagement frequency, recency, and depth. Used as a conditional split criterion in lead nurture flows. #### Key takeaways - Connect **Use Cases** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 17 — Setting Up Personalize #### Lesson text Full Personalize setup is handled in a dedicated **Personalize Implementation Course** that is separate from this Academy. This section serves as a scope marker — it explains why Personalize configuration is intentionally out of scope here, identifies the prerequisite Academy topics that support future Personalize work, and provides interim references for API-level and experience-level context while the dedicated course is in development. ## Scope and Status ### Learning Objectives By the end of this section, you will be able to: \- Explain why this topic is intentionally scoped out of the D&I Implementation Academy \- Identify where to continue learning until the dedicated Personalize course is available ### Why This Topic Is Not Covered Here This topic is intentionally blocked in the D&I Implementation Academy. * Full Personalize setup is handled in a separate **Personalize Implementation Course**. * This academy only covers adjacent implementation dependencies (for example, tag setup, audience definitions, and API usage patterns in other topics). * You should not treat this section as a setup guide for enabling Personalize in production. #### Key Concepts * **Course boundary**: this section is a scope marker, not an implementation walkthrough. * **Dependency mapping**: Personalize depends on data quality, identity health, and delivery tooling already covered in this academy. * **Operational readiness**: setup decisions should follow the dedicated Personalize curriculum when available. #### Step-by-Step 1. Confirm this topic status before planning Personalize implementation work. 2. Complete prerequisite academy topics that support Personalize outcomes. 3. Use the interim resources listed below for API-level or experience-level context. 4. Track the dedicated course release before finalizing production setup decisions. #### Examples ```text Scope rule: - Use this section to understand where Personalize setup belongs. - Do not use this section as a substitute for the dedicated Personalize setup course. ``` ### Summary This section establishes that Personalize setup is intentionally out of scope in the D&I Implementation Academy. The dedicated Personalize Implementation Course handles production setup end-to-end. Until that course is available, complete the prerequisite Academy topics and use the interim references in the next section for API and delivery context. ### Documentation Links * [Personalize Overview](https://docs.lytics.com/docs/personalize) * [Experience Delivery](https://docs.lytics.com/docs/experience-delivery) ## Interim Learning Path ### Learning Objectives By the end of this section, you will be able to: \- Locate related academy sections that support future Personalize setup work \- Use available API and experience references without bypassing course boundaries ### What to Use in the Meantime * For API-level profile lookup patterns, see [Personalize API](/academy/courses/lytics-course/integrations-connections#personalize-api). * For delivery mechanics and experience orchestration, see [Pathfora](/academy/courses/lytics-course/pathfora). * For tag dependency and identity readiness, see [Tag](/academy/courses/lytics-course/tag) and [ID Resolution](/academy/courses/lytics-course/id-resolution). When the dedicated Personalize course is published, this placeholder should be updated to link directly to it. ### Summary The interim path for Personalize work runs through existing Academy sections: the Integrations & Connections module for API-level profile lookup patterns, Pathfora for delivery mechanics and experience orchestration, and the Tag and ID Resolution modules for foundational readiness. None of these are substitutes for the dedicated Personalize course, but they provide the implementation grounding you will need when that course becomes available. ### Documentation Links * [Personalize API Reference](https://docs.lytics.com/docs/personalize-api) * [Identity Resolution](https://docs.lytics.com/docs/identity-resolution) * [JavaScript Tag](https://docs.lytics.com/docs/jstag) ## What You've Learned This section established the scope boundary for Personalize within the D&I Implementation Academy. Personalize setup is a distinct implementation domain handled by its own dedicated course. The Academy covers the adjacent building blocks — tag installation, identity resolution, audience definitions, and delivery mechanics via Pathfora — that Personalize depends on. Until the dedicated course is available, those adjacent modules are the correct interim references for API-level and experience-level context. ### Key Terms > 📘 **Personalize** — A Lytics capability for delivering real-time, profile-driven web experiences. Full setup is covered in the dedicated Personalize Implementation Course, not in this Academy. > > 📘 **Course boundary** — A scope marker indicating that a topic is intentionally excluded from a given curriculum and is handled in a separate, dedicated course. > > 📘 **Operational readiness** — The state in which prerequisite data quality, identity health, and delivery tooling are sufficiently in place to support a production Personalize deployment. #### Key takeaways - Connect **Setting Up Personalize** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 18 — Permissions & User Management #### Lesson text This section is a status placeholder. The Permissions & User Management topic is currently blocked pending finalized product specifications for the Lytics access model. Rather than publish governance guidance that does not reflect current product behavior, this section describes why the topic is blocked, what preparatory work you can do in the meantime, and how to track unblock status so your team is ready to implement permissions efficiently once the product-aligned documentation is available. ## Status and Scope ### Learning Objectives By the end of this section, you will be able to: \- Explain why this topic is blocked and cannot yet be finalized \- Identify which permissions concepts are expected once updated product specifications are released ### Why This Topic Is Blocked This topic is currently blocked pending updated product stream information for the permissions model. * The access model is undergoing product changes. * Final role definitions, permission boundaries, and UI workflows are not yet stable for academy publication. * Implementation instructions are intentionally withheld to avoid publishing inaccurate governance guidance. #### Key Concepts * **Stability requirement**: permission guidance must match current product behavior exactly. * **Enterprise impact**: role and access design affects compliance, security, and operational ownership. * **Deferred publication**: this section should only be expanded when product specifications are finalized. #### Step-by-Step 1. Treat this topic as a status placeholder, not an implementation source. 2. Continue using account-level controls documented in [Account Configuration](/academy/courses/lytics-course/account-configuration). 3. Track unblock status in the section-specific CLAUDE instructions. 4. Revisit this topic when product-approved permissions documentation is available. #### Examples ```text Blocked-topic rule: - Do not publish role matrices or permission screenshots until product specifications are finalized. ``` ### Summary This topic is intentionally blocked because the Lytics access model is undergoing active product changes. Publishing role matrices or permission workflows before specifications are finalized would risk introducing inaccurate governance guidance into enterprise implementations. Track unblock status in the CLAUDE topic notes and revisit this section once product-approved documentation is available. ### Documentation Links * [Account Configuration](https://docs.lytics.com/docs/account-configuration) * [User Management](https://docs.lytics.com/docs/user-management) ## Preparation Until Unblocked ### Learning Objectives By the end of this section, you will be able to: \- Prepare account governance inputs needed for future permissions implementation \- Document open questions so the final permissions rollout can be completed efficiently ### Interim Readiness Work Until this topic is unblocked, you can prepare the following: * Document team roles and operational responsibilities (implementation, analytics, marketing ops, security). * Inventory integrations and destinations that will require scoped access controls. * Define review cadence for access audits and ownership changes. * Track open questions internally until product-approved documentation is available. ### Summary The most productive use of this blocked period is building the governance inputs the permissions rollout will need: a documented map of team roles and responsibilities, an inventory of integrations requiring scoped access, and a defined audit cadence. Capturing open questions now means the final implementation can move quickly once the product specifications are stable. ### Documentation Links * [Single Sign-On Overview](https://docs.lytics.com/docs/single-sign-on) * [Account Security](https://docs.lytics.com/docs/account-security) ## What You've Learned This section established that Permissions & User Management is a blocked topic within the D&I Implementation Academy, deferred until the Lytics access model product specifications are finalized. Publishing incomplete or inaccurate governance guidance carries enterprise-level compliance and security risk, which is why this section functions as a placeholder rather than an implementation guide. The preparatory work outlined here — documenting team roles, inventorying integrations, and capturing open questions — ensures that when the block is lifted, the implementation can proceed without delay. ### Key Terms > 📘 **Permissions model** — The system that defines which roles can perform which actions within a Lytics account. Role definitions, permission boundaries, and UI workflows are pending product finalization at the time of this writing. > > 📘 **Access control** — The set of rules and configurations that govern which users can view, edit, or manage specific platform resources, including integrations, audiences, and account settings. > > 📘 **Governance runbook** — A documented set of operational procedures for managing user access, including onboarding, access reviews, ownership changes, and offboarding. #### Key takeaways - Connect **Permissions & User Management** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 19 — Ongoing Maintenance #### Lesson text A successful Lytics implementation does not end at launch. Profiles drift, schemas accumulate unused fields, consent policies change, and integrations break. This section covers the operational disciplines that keep a production Lytics account healthy over time: account health monitoring, schema auditing, day-to-day operational shortcuts, consent compliance maintenance, and data flow validation. Each topic includes a repeatable process you can operationalize with your team. ## Account Health ### Learning Objectives By the end of this section, you will be able to: \- Identify key account health metrics including data volume, profile counts, and integration status \- Set up proactive health monitoring with alerts and dashboards \- Establish a regular health check cadence with defined responsibilities and review schedule ### Account Health Healthy Lytics accounts are maintained, not assumed. The right pattern is continuous monitoring plus scheduled operational review. Primary references: * [Monitoring Metrics and Alerts](https://docs.lytics.com/docs/lytics-monitoring) * [Job Alerts](https://docs.lytics.com/docs/job-alerts) * [Usage Metrics](https://docs.lytics.com/docs/usage-metrics) #### Key Concepts * **Core health signals**: * ingest continuity, * workflow status, * quota/volume trends, * destination delivery health. * **Metric API heartbeats**: * `monitoring_heartbeat` (platform integration runtime health), * `collection_count` (ingress event volume), * `stream_count` (stream-level throughput). * **Alert channels**: Slack, Microsoft Teams, and email. * **Job-state awareness**: * Running, * Sleeping, * Failed, * Paused, * Completed. #### Step-by-Step 1. Configure account-level alert routing: \- operations channel for global alerts, \- owner-specific alerts for critical workflows. 2. Enable alerts for high-priority sources and destinations. 3. Build a recurring health cadence: \- daily: check failed jobs and unusual volume drops, \- weekly: review job trends and quota consumption, \- monthly: review runbook updates and ownership. 4. Track usage from Vault Usage: \- inbound events, \- outbound events, \- quota meter progression. 5. Inspect failing jobs in Conductor diagnostics and logs, then resume/restart after remediation. #### Examples ```text Suggested alert policy: - Critical imports/exports: alert on Error + Failed + prolonged Sleeping - Non-critical jobs: alert on Failed only - One daily digest channel + immediate paging for critical pipelines ``` ```text Heartbeat alert threshold guideline: Do not alert on a single missed minute. Use a multi-minute missing window (for example 5 minutes) to reduce false positives. ``` #### Diagrams & Screenshots ![Account health dashboard with usage, job status, and alert routing.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am0c36db865b910269/202c1b01e82cf1f088718646/account_health_dashboard_usage_job.png) ### Summary Account health monitoring requires both continuous alerting and a scheduled review cadence. Configure alert routing for critical jobs first, then build a daily/weekly/monthly review rhythm that covers failed jobs, quota consumption, and runbook currency. The `monitoring_heartbeat`, `collection_count`, and `stream_count` metrics are the primary signals to watch; use multi-minute windows for heartbeat alerts to reduce false positives. ### Documentation Links * [Monitoring Metrics and Alerts](https://docs.lytics.com/docs/lytics-monitoring) * [Job Alerts](https://docs.lytics.com/docs/job-alerts) * [Usage Metrics](https://docs.lytics.com/docs/usage-metrics) ## Schema Audit ### Learning Objectives By the end of this section, you will be able to: \- Conduct a schema audit to review all fields, types, and mappings \- Identify stale or unused fields that can be deprecated or removed \- Clean up and optimize the schema for performance and clarity ### Schema Audit Schema drift is one of the most common long-term causes of poor segmentation quality and operational confusion. Primary references: * [Schema Audit](https://docs.lytics.com/docs/schema-audit) * [Data Streams](https://docs.lytics.com/docs/data-streams) #### Key Concepts * **Schema Audit focus areas**: * which fields are populated, * which fields are actually used in audiences, * which fields merge multiple streams, * which field types may be expensive (especially complex `map` patterns). * **High-value table columns**: * sources, * users with field, * cardinality, * times used. * **Field quality lifecycle**: * active, * candidate for deprecation, * deprecated/retired. #### Step-by-Step 1. Open **Data > Schema Audit**. 2. Filter by: \- users with field threshold, \- data stream, \- field name search. 3. Review visual summary: \- percentage of fields with data, \- percentage used in audiences, \- multi-stream merge usage. 4. Export or document candidate cleanup list: \- no data, \- no audience usage, \- obsolete campaign fields, \- duplicate semantic fields. 5. Validate dependencies before cleanup: \- audience definitions, \- destination mappings, \- templates and downstream queries. 6. Apply cleanup incrementally, then re-audit after one cycle. #### Examples ```text Monthly schema audit rubric: - Keep: populated + actively used - Investigate: populated but never used - Remove/deprecate: unused + obsolete + no active downstream dependency ``` ```text Common anti-pattern: Many near-duplicate fields for the same concept (e.g., email_1, email_addr, emailAddress). Standardize to one canonical field and map sources accordingly. ``` #### Diagrams & Screenshots ![Schema audit charts and field usage table.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am74e0c741e6e52752/947f417680883dd7f43431d8/schema_audit_charts_field_usage.png) ### Summary Schema drift accumulates silently and degrades segmentation quality over time. A monthly schema audit using the **Schema Audit** view gives you a structured way to identify fields that are populated but unused, unused and obsolete, or duplicating existing concepts. Always validate audience, destination, and template dependencies before removing any field, and apply cleanups incrementally to avoid unintended side effects. ### Documentation Links * [Schema Audit](https://docs.lytics.com/docs/schema-audit) * [Data Streams](https://docs.lytics.com/docs/data-streams) * [Schema Manager](https://docs.lytics.com/docs/schema-manager) ## Tips and Tricks ### Learning Objectives By the end of this section, you will be able to: \- Apply operational shortcuts and efficiency patterns for routine maintenance tasks \- Avoid common maintenance gotchas that can cause data issues or downtime \- Streamline routine tasks with repeatable processes and automation where possible ### Tips and Tricks These practices reduce operational noise and shorten recovery time when issues occur. #### Key Concepts * **Name everything clearly**: * jobs, authorizations, audiences, and flows should encode purpose and owner. * **Separate streams by intent**: * behavioral events vs profile attribute updates, * avoid mixed semantics in one stream where possible. * **Avoid over-hidden stream keys**: * hidden keys cannot be restored from UI (API/support path required). * **Webhook timing guardrail**: * time-window audience triggers for webhooks should use at least 30 minutes. * **Runbook over tribal knowledge**: * each critical job needs owner, dependency map, and recovery procedure. #### Step-by-Step 1. Standardize naming conventions account-wide. 2. Add owner metadata and escalation route to each critical job. 3. Build a "top 10 critical workflows" runbook with: \- expected cadence, \- acceptable lag, \- restart steps, \- destination-side checks. 4. Add monthly dry-run incident drills for the highest-risk jobs. 5. Keep a change log for schema and audience definition updates. #### Examples ```text Job label convention: [SourceOrDestination]-[Purpose]-[OwnerTeam]-[Cadence] Example: SFMC-Export-MQLLifecycle-MarketingOps-Realtime ``` ```text Fast triage pattern: 1) Check job status 2) Check most recent log error 3) Validate upstream stream freshness 4) Validate destination auth/token validity 5) Resume/restart and verify next successful sync ``` #### Diagrams & Screenshots ![Operations runbook and escalation flow.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am2e4f9e533b265289/f20a2a0e984edadee542d6bc/operations_runbook_escalation_flow.png) ### Summary Operational efficiency in Lytics comes from disciplined naming, stream separation, and documented runbooks. Encoding purpose and owner into every job name makes triage faster. Separating behavioral event streams from profile attribute update streams reduces mapping confusion. A written runbook for each critical workflow — with restart steps and destination-side checks — converts tribal knowledge into recoverable process. Periodic dry-run drills surface gaps before real incidents do. ### Documentation Links * [Job Management](https://docs.lytics.com/docs/job-management) * [Data Streams](https://docs.lytics.com/docs/data-streams) * [Webhooks](https://docs.lytics.com/docs/webhooks) ## Consent Handling ### Learning Objectives By the end of this section, you will be able to: \- Maintain consent compliance as privacy regulations evolve and new requirements emerge \- Update consent flows when legal or business requirements change \- Audit consent implementation to verify it matches current policy and regulatory needs ### Consent Handling Consent maintenance is both legal and technical. The implementation must stay aligned with policy changes, not just initial launch requirements. Primary references: * [Consent and Privacy](https://docs.lytics.com/docs/consent) * [Privacy and Data Protection](https://docs.lytics.com/docs/privacy-and-data-protection) #### Key Concepts * **Consent model dimensions**: * purpose, * state (`consented` true/false), * source/document, * location, * timestamp. * **Field design strategy**: * simple cases: string/boolean with `latest` merge behavior, * granular cases: map field with merge semantics for key-level state. * **Audience enforcement**: * build consented/not-consented building-block audiences, * compose campaign audiences using those blocks. * **Tag-level enforcement**: * JS Tag consent plugin can block data collection until opt-in, * `optIn()` resumes collection, `optOut()` blocks and clears cookies, * OneTrust integration can drive this behavior from consent categories. #### Step-by-Step 1. Review current legal/policy requirements with legal/privacy owner. 2. Validate consent schema still supports required granularity. 3. Audit mappings for all consent-related events and channels. 4. Validate segment enforcement: \- required-consent audiences, \- suppression audiences for opt-out users. 5. Validate web/mobile SDK consent flows (including tag blocking behavior). 6. Re-test downstream job filters that depend on consent audiences. 7. Document policy change date and technical deployment date. #### Examples ```javascript // Web consent event example jstag.send({ event: "form-submit", consent: { purpose: "marketing", consented: true, documents: ["terms_2026_01"], location: "US", }, }); ``` ```text Quarterly consent audit outputs: - Active consent schema map - Audience enforcement matrix by channel - Gaps and remediation owner/date ``` #### Diagrams & Screenshots ![Consent lifecycle from collection to profile mapping to audience enforcement.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am728079a53eca8119/f5bd2d81409e9b1b9a59ca94/consent_lifecycle_collection_profile_mapping.png) ### Summary Consent compliance requires ongoing maintenance as privacy regulations and business policies evolve. Your consent schema must support the granularity your legal requirements demand — simple boolean fields for straightforward cases, map fields for purpose-level or jurisdiction-level granularity. Audience-based enforcement (consented vs. suppressed building blocks) is the most reliable way to propagate consent state into downstream jobs. Run a quarterly audit that produces a current schema map, an audience enforcement matrix by channel, and a documented gap remediation plan. ### Documentation Links * [Consent and Privacy](https://docs.lytics.com/docs/consent) * [Privacy and Data Protection](https://docs.lytics.com/docs/privacy-and-data-protection) * [JavaScript Tag Consent Plugin](https://docs.lytics.com/docs/jstag-consent) ## Data Flow Validation ### Learning Objectives By the end of this section, you will be able to: \- Validate that data continues to flow correctly across all integrations and sources \- Debug data flow interruptions by tracing events from source to profile \- Set up data flow monitoring to detect issues before they impact audiences and campaigns ### Data Flow Validation Data flow validation should confirm the full path: source event -> stream key -> schema mapping -> profile field -> audience membership -> activation/export. Primary references: * [Data Streams](https://docs.lytics.com/docs/data-streams) * [Monitoring a Job](https://docs.lytics.com/docs/monitoring-a-job) * [Webhooks](https://docs.lytics.com/docs/webhooks) #### Key Concepts * **Stream-level checks**: * event ingress trend, * last message received, * raw key first/last seen and sample values. * **Job-level checks**: * status transitions, * sync/error events, * configuration integrity, * authorization validity. * **Profile-level checks**: * mapped field appears with expected type/value, * audience entry/exit reflects expected behavior. * **Activation-level checks**: * destination receives expected payload, * trigger events (enter/exit/change) fire as configured. #### Step-by-Step 1. Validate stream ingestion at **Conductor > Pipeline > Streams**. 2. Inspect raw key sample values for changed payload formats. 3. Validate field mappings and resulting profile materialization. 4. Validate target audience membership changes for test users. 5. Validate destination job logs and payload delivery. 6. If failure exists, isolate by layer: \- source emission, \- ingestion, \- mapping, \- audience, \- destination. 7. Remediate, resume/restart job, and confirm successful sync event. #### Examples ```text End-to-end test event checklist: - Send deterministic test event with known unique identifier - Confirm event appears in expected stream - Confirm mapped profile field updates - Confirm audience enter/exit event - Confirm destination payload receipt ``` ```text Common interruption patterns: - Stream active but no audience movement -> mapping or audience rule issue - Audience movement but no destination events -> export auth/config issue - Destination failures after policy update -> consent/suppression filter mismatch ``` #### Diagrams & Screenshots ![Data flow validation pipeline from source to destination.](https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amcb3a82dc9d41b553/b1acdfc8af2b5f9d81a83bbc/data_flow_validation_pipeline_source.png) ### Summary Data flow validation is a layered diagnostic process: confirm ingestion at the stream level, verify field mapping at the profile level, check audience membership changes, then validate destination payload delivery. Isolating failures by layer — source, ingestion, mapping, audience, destination — is the fastest way to narrow the root cause. Sending a deterministic test event with a known identifier is the most reliable end-to-end check after any schema change, integration update, or consent policy modification. ### Documentation Links * [Data Streams](https://docs.lytics.com/docs/data-streams) * [Monitoring a Job](https://docs.lytics.com/docs/monitoring-a-job) * [Profile Lookup](https://docs.lytics.com/docs/profile-lookup) ## What You've Learned Ongoing maintenance is the operational discipline that protects the quality of your Lytics implementation over time. You now have repeatable processes for monitoring account health with alerts and cadenced reviews, auditing the schema to remove drift and unused fields, applying operational efficiency patterns that reduce triage time, keeping consent implementation aligned with evolving legal requirements, and validating end-to-end data flow across all integrations. These are not one-time tasks — they are the recurring practices that distinguish a well-operated production account from one that degrades silently. ### Key Terms > 📘 **Schema drift** — The gradual accumulation of unused, duplicated, or mistyped fields in the profile schema, typically caused by onboarding new data sources without retiring old ones. Drift degrades segmentation quality and increases operational confusion. > > 📘 **Health cadence** — A structured schedule of account health reviews, typically daily (failed jobs and volume drops), weekly (job trends and quota), and monthly (runbook updates and ownership review). > > 📘 **Consent enforcement** — The use of audience-based suppression and inclusion rules to ensure that only profiles with the required consent state are included in downstream jobs and activations. > > 📘 **Data flow validation** — A layered diagnostic process that confirms data moves correctly from source event through stream ingestion, schema mapping, profile materialization, audience membership, and destination delivery. > > 📘 **Runbook** — A documented operational procedure for a critical job or workflow, including expected cadence, acceptable lag, restart steps, and escalation path. Runbooks convert tribal knowledge into recoverable process. #### Key takeaways - Connect **Ongoing Maintenance** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ## Resources & references | Page | Companion Markdown | | --- | --- | | /courses/lytics-implementation/welcome-to-lytics | /academy/md/courses/lytics-implementation/welcome-to-lytics.md | | /courses/lytics-implementation/account-configuration | /academy/md/courses/lytics-implementation/account-configuration.md | | /courses/lytics-implementation/data-flow | /academy/md/courses/lytics-implementation/data-flow.md | | /courses/lytics-implementation/profile | /academy/md/courses/lytics-implementation/profile.md | | /courses/lytics-implementation/id-resolution | /academy/md/courses/lytics-implementation/id-resolution.md | | /courses/lytics-implementation/tag | /academy/md/courses/lytics-implementation/tag.md | | /courses/lytics-implementation/schema | /academy/md/courses/lytics-implementation/schema.md | | /courses/lytics-implementation/integrations-connections | /academy/md/courses/lytics-implementation/integrations-connections.md | | /courses/lytics-implementation/audience-building | /academy/md/courses/lytics-implementation/audience-building.md | | /courses/lytics-implementation/content | /academy/md/courses/lytics-implementation/content.md | | /courses/lytics-implementation/audience-insights-app | /academy/md/courses/lytics-implementation/audience-insights-app.md | | /courses/lytics-implementation/lookalike-model | /academy/md/courses/lytics-implementation/lookalike-model.md | | /courses/lytics-implementation/reports | /academy/md/courses/lytics-implementation/reports.md | | /courses/lytics-implementation/flows | /academy/md/courses/lytics-implementation/flows.md | | /courses/lytics-implementation/pathfora | /academy/md/courses/lytics-implementation/pathfora.md | | /courses/lytics-implementation/use-cases | /academy/md/courses/lytics-implementation/use-cases.md | | /courses/lytics-implementation/setting-up-personalize | /academy/md/courses/lytics-implementation/setting-up-personalize.md | | /courses/lytics-implementation/permissions-user-management | /academy/md/courses/lytics-implementation/permissions-user-management.md | | /courses/lytics-implementation/ongoing-maintenance | /academy/md/courses/lytics-implementation/ongoing-maintenance.md | ## Supplement for indexing ### Content summary Overview Lytics Implementation is a comprehensive training program designed to help technical teams, marketers, and content strategists successfully implement, operate, and maintain the Lytics Customer Data Platform. The… Overview Lytics Implementation is a comprehensive training program designed to help technical teams, marketers, and content strategists successfully implement, operate, and maintain the Lytics Customer Data Platform. The course walks learners through the full data lifecycle: setting up secure account settings, ingesting real-time events, stitching anonymous browser behavior into unified profiles using identity resolution, and mapping custom data schemas. From there, it focuses on driving measurable business outcomes. Learners discover how to build dynamic audiences, leverage machine learning f ### Retrieval tags - Contentstack Academy - lytics-implementation - Welcome - Lytics - Account - Configuration - Data - Flow - Profile - Resolution - Tag - Schema - Integrations - Connections ### Indexing notes Chunk at each "### Lesson NN — Title" heading; copy lesson_id and topics from the preceding HTML comment into chunk metadata for RAG filters. Course slug: lytics-implementation. Union of lesson topic tokens: Welcome, Lytics, Account, Configuration, Data, Flow, Profile, Resolution, Tag, Schema, Integrations, Connections, Audience, Building, Content, Insights, App, Lookalike, Model, Reports, Flows, Pathfora, Use, Cases, Setting, Personalize, Permissions, User, Management, Ongoing, Maintenance. Do not embed or retrieve LMS-only quiz items or mastery exam answer keys from this export. ### Asset references | Label | URL | | --- | --- | | Walkthrough of the Lytics UI navigation: Home dashboard, Data Pipeline, Building Profiles, Using Profiles, Content, and Account areas. Show where key tools live | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ambad89731e1aa6efd/50a5de84b053715c2ca843c4/walkthrough_lytics_ui_navigation_home.gif` | | Vault landing page showing the five top-level navigation sections (Usage, Settings, Users, Security, Setup). | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am706541a37c1fef70/1dae4ba926e6313667d82802/vault_landing_page_five_top.png` | | Security settings page showing login session and login policy configuration options. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am356bdc3a05ba9079/f76f83eb19ebff55a5986e8d/security_settings_page_login_session.png` | | Walk through inviting a new user: click Create New, enter email, assign roles, and show the resulting invitation. Then demonstrate editing roles on an existing | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am9f6561352bf55ef7/194853f2e36b1d179e52b1ce/walk_inviting_user_click_create.gif` | | Demonstrate creating an access token: click Create New, fill in name/description/expiration/roles, click Create, and copy the one-time token value. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am7bef78007522ae3d/cb28687212ac0abc5d3e1dec/demonstrate_creating_access_token_click.gif` | | Walk through creating an authorization: open the wizard, select a provider, choose the authorization method, complete the configuration, and verify health statu | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am84b1e1ae7ef39120/b3dff2264a5554c12d0bd6b7/walk_creating_authorization_open_wizard.gif` | | Demonstrate both installation methods: direct snippet installation in a site's HTML head, and Google Tag Manager setup with Custom HTML tag and All Pages trigge | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ama7505f0b0263439c/64fa60912826345b5a536022/demonstrate_both_installation_methods_direct.gif` | | Lytics Dev Tools Chrome extension side panel showing the Status tab: JavaScript SDK version, Account ID, stream, cookie name, profile key, and last-activity ind | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amb3dfba931b26e21d/36a91aac9550bfbd2a94f376/demonstrate_verifying_javascript_tag_installation.png` | | Navigate to Conductor > Pipeline > Streams, select a stream, explore the event ingress graph, and walk through the raw keys table including filters (Used, Unuse | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am48f6d6deba9bcaae/4a2f13207055356b65c4d75d/navigate_conductor_pipeline_streams_select.gif` | | Conductor > Pipeline > Streams view showing the event ingress graph, stream metadata, and raw keys table for a sample stream. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amf3347ed3e5011834/6ef3dfbc1eec214ebb96f8da/conductor_pipeline_streams_view_event.png` | | Walk through creating a field and mapping: navigate to Schema > Fields, create a new field with data type and merge operator, then navigate to Schema > Mappings | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ama2c0a623318abc00/3203ffcfdfdbc092f44bbbfd/walk_creating_field_mapping_navigate.gif` | | Building Profiles > Search interface showing the identifier type dropdown and search results for an example profile. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am4e06b256981c76f3/8626dfca2adacc4b88db470f/building_profiles_search_interface_identifier.png` | | Profile view showing the Intelligence tab with behavioral scores, content affinity, and event heatmap for a sample profile. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amba41acc1cca88a91/3b364f05b4b660edbb4db99c/profile_view_intelligence_tab_behavioral.png` | | Identity Rules visualization showing multiple streams connected through shared identity keys, with at least one isolated stream node for contrast. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am93d805b00d6ea64d/5483a94e95031405194b97ef/identity_rules_visualization_multiple_streams.png` | | Building Profiles > Schema > Fields showing the field creation wizard with data type, merge operator, and capacity settings visible. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am157b2895912a318e/6dfb0f95e8451c81eb4f347e/building_profiles_schema_fields_field.png` | | Walk through the Identity Explorer for a sample profile: show Identity graph, Profile Fields with filtering, Raw Data JSON, Behavior scores, Content Affinity to | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am10a4da547461bc2b/72d6e001ffe636b182a9f722/walk_identity_explorer_sample_profile.gif` | | Identity graph showing email and cookie fragments with ranked conflict resolution. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am539fd699a2e67d38/c0d330146d4a4d3350b65e7e/identity_graph_email_cookie_fragments.png` | | Identity Rules page showing identifier rank ordering. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am78ddd270b9c625e9/8810061a9d56f2327f59ea34/identity_rules_page_identifier_rank.png` | | Unhealthy Profiles audience trend line compared to total profiles. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am0fe8ee37c111791b/bbfa34357a2f89474c7af353/unhealthy_profiles_audience_trend_line.png` | | Identity Explorer profile showing processing failure metadata fields. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am3fc1259ad95e544d/55e4b2f7c33ccff8c5f660fd/identity_explorer_profile_processing_failure.png` | | Identity Explorer with graph and fragment conflict indicators. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amcd2abdd66b7fb226/56577621a8650db4fc900e5e/identity_explorer_graph_fragment_conflict.png` | | Profile Simulator showing step analyses and graph output. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am34a08ae867c6619d/a2f7bc088228e3ded7082a2f/profile_simulator_step_analyses_graph.png` | | Identity health dashboard with unhealthy profile and traversal-limit indicators. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am6b259f015c7163e3/76cec8a69da52e3290e43f53/identity_health_dashboard_unhealthy_profile.png` | | Change control checklist for identifier rank updates. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am571092fe295d8a0e/8118f8cf8fd8ee152dea6600/change_control_checklist_identifier_rank.png` | | Browser page with Lytics tag installed and a successful network collect call. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am18cce815c774d9d1/b5988fdb035592704a04d127/browser_page_lytics_tag_installed.png` | | Custom event instrumentation plan mapped to page interactions. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ame290e3c4eae2952d/22e62af764489284f0bda25e/custom_event_instrumentation_plan_mapped.png` | | Chrome DevTools Console on redpandaresorts.com showing jstag.getEntity() returning a real live profile: behavioral scores (consistency, frequency, intensity, mo | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am63b4eb5a18b5ec65/4a42c4a40ad1d568fd1859b0/spa_route_change_flow_calling.png` | | Cookie and session values in browser storage after jstag initialization. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ameecb12fcee31802b/44760ddf194e3a90ebbd18b8/cookie_session_values_browser_storage.png` | | Identity stitching flow from anonymous \_uid to known customer\_id and email. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am0f1ff55227c42fa8/521b64c05886a4b503d4b83e/identity_stitching_flow_anonymous_uid.png` | | Schema Manager showing the Versions, Fields, Mappings, and Ranks navigation tabs with an active draft version visible. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am92d279cefd0612c2/1977d461a33b652a1044674c/schema_manager_versions_fields_mappings.png` | | Field creation dialog showing the data type dropdown, merge operator selection, and identity key/PII flag settings. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am168fc4da61fd23af/65653f6f57f4e8908a5303dc/field_creation_dialog_data_type.png` | | Mapping editor showing the stream selector, expression input, condition field, and target field dropdown for an active mapping. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am190ccabb324a3877/e5db52ac7bbe06b8a765793e/mapping_editor_stream_selector_expression.png` | | Data dictionary spreadsheet template showing field ID, business meaning, merge operator, source streams, downstream dependencies, and lifecycle status columns. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amb4a177dbd8cc813c/0c28dcb6482c8b4dce4e7330/data_dictionary_spreadsheet_template_field.png` | | Mapping editor showing a nested LQL function expression with a condition filter, illustrating function composition in a production mapping. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am69c958a6732e0334/aac5d874f86c7facf97deb01/mapping_editor_nested_lql_function.png` | | Schema Fields view filtered by category, showing a list of Identity-category fields with their field IDs, types, and merge operators. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amc9770f2cd222d6f9/51314dff968fa4871eb073d2/schema_fields_filtered_category_identity.png` | | Schema Fields view showing universal schema fields (identifiers, behavioral scores, intelligence fields) alongside common schema fields, with their categories l | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amd7c50bf7b0dba348/9e4274c2637e47c811649f6e/schema_fields_universal_common.png` | | Schema version history view showing a published version with change description, alongside the Publish Changes and Discard Changes controls. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ama99a1960d7d2e17f/818f40e627ff9f98eef67919/schema_version_history_published_version.png` | | Integrations landscape across Jobs, Cloud Connect, and Authorizations. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am4d037ec328ffaa7a/17496303b1cd4009ce3f3548/integrations_landscape_jobs_cloud_connect.png` | | Authorization creation wizard showing provider and method selection. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am5adcb9e988f635e9/d7a1b5c95067ec410516f3ce/authorization_creation_wizard_provider_method.png` | | Destination filtering pattern with allowlist fields and exclusion audiences. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am96484b7acac52307/2dee2ce740beb04c632c2340/destination_filtering_pattern_allowlist_fields.png` | | Cloud Connect flow from warehouse query to profile enrichment. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am35a98e09daf4e6a8/5779b5a64bd97c42f59a0544/cloud_connect_flow_warehouse_query.png` | | Attributes API request flow: an external system GETs a profile's current attributes, then PATCHes a single new field (loyalty\_tier=gold) with mergeExisting=tru | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am6cf3ac6d37b3289c/1d07c14a2fea8486839a16ec/attributes_api_request_flow_get.png` | | Prebuilt integration workflow from auth to production monitoring. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am3ef85362f96624b1/c41f33931779d863480f950f/prebuilt_integration_workflow_auth_production.gif` | | Webhook trigger with template transformation before destination POST. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am8c5be2a8c38e5031/1aec72ba2d7b3f9fe641ff1a/webhook_trigger_template_transformation_before.png` | | Server authentication flow emitting login event to Collect API. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am95fb7dad9e71261b/48a278b419fc3b22434567f0/server_authentication_flow_emitting_login.png` | | Personalize API lookup and decisioning flow with segment-aware response. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am792812e20e53de88/b141d13a7a4f3807b39d2e7b/personalize_api_lookup_decisioning_flow.png` | | Video thumbnail: Audience Building | `https://cdn.jwplayer.com/v2/media/xf4x1xiI/poster.jpg?width=720` | | audience-builder-scores.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt3f9f9274ec8303b0/68655529b734d046be943a36/audience-builder-scores.png` | | audience-builder-real-time-count.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt8e78d5d82ef1d51a/6865552a4431706cfdfdb457/audience-builder-real-time-count.png` | | audience-builder-and-example.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blt9ad8ec0292ff6a92/686604caf4c619a376fcf0cf/audience-builder-and-example.png` | | audience-builder-or-example.png | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/blta8aed82bb6a21eaa/686604ca8628602d45348b9a/audience-builder-or-example.png` | | Content ingestion flow from URL events through enrichment into the content table. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amf8c7aa00b681aecf/b1c1cdaa0468c6fa0bd3fe9e/content_ingestion_flow_url_events.png` | | Classification dashboard showing activity, content flow states, and manual classify panel. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am73bc3e943df8481f/d27a146ceac1ae66ed53d938/classification_dashboard_activity_content_flow.png` | | Context layer creation wizard showing inventory mapping and output field configuration. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amdc6605baf3a80c4a/228e9fb477051fb2996a01ce/context_layer_creation_wizard_inventory.png` | | Content collection builder showing dynamic filters and advanced editor options. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amb5f59cec271f9d2c/4ce3515fe60a0ea62b737cbe/content_collection_builder_dynamic_filters.png` | | Recommendation workflow from collection definition to API delivery and performance optimization. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amb9ea60d6f11ac644/85d48ee6e5b356ea1abb70b0/recommendation_workflow_collection_definition_api.gif` | | Audience insights workflow from audience summary pages to comparative reports and activation actions. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am1b04ae013ea8e208/8d407e9c32f207b411b201c2/audience_insights_workflow_audience_summary.png` | | Audience comparison report with size, overlap, and composition components configured for three audiences. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am4df9c086acf3388c/e984edd3cef9de184aa04375/audience_comparison_report_size_overlap.png` | | Lookalike model workflow from source/target selection to scoring and predictive audience activation. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amcab82ebd9a8794e1/984a3252933be7c0494877cf/lookalike_model_workflow_source_target.png` | | Lookalike model summary view with audience cards, threshold explorer, and feature importance charts. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amde3193a79426d72a/bbba365fe3b7975fb7a0aa4e/lookalike_model_summary_view_audience.png` | | Goal definition worksheet showing source, target, threshold strategy, and activation plan. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am27cf6e0d1f4a70e3/3a32acb07e6c181615cdc711/goal_definition_worksheet_source_target.png` | | Lookalike model configuration wizard showing source/target and advanced options. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am2743f4cb06638c5c/4452c4302d63af5eba247509/lookalike_model_configuration_wizard_source.png` | | Model diagnostics view with R squared, AUC, error rates, and decision threshold. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am8bb25208a6d75565/3fbaa83d3f77c3a4ff138897/model_diagnostics_view_r_squared.png` | | Activation workflow from model status toggle to predictive audience exports and campaign measurement. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am0fb32c4c0bfc4477/d45f06c90163a56e686b0445/activation_workflow_model_status_toggle.png` | | Reports index page showing report list, lock/star indicators, and create action. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ame864a03e0a87d3c4/5bca08d7f5dc917b7619f523/reports_index_page_report_list.png` | | Default dashboard report with size, dataflow, composition, and overlap components. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am26898fe5e9b33048/3fa67f2275795560afebbe0c/default_dashboard_report_size_dataflow.png` | | Custom report editor with add component modal and drag-to-reorder dashboard layout. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am633f9723379dea91/b7086aeab36d9aefcb633169/custom_report_editor_add_component.png` | | Report configuration form showing private toggle and collaborators selector. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am22f732e0bac9dc36/51e310d3572f4db79c4d2614/report_configuration_form_private_toggle.png` | | Component picker showing Composition, Size, Audience Overlap, and Data Flow options. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am2ee96b46a5632199/67b3696a1d989a219736a62a/component_picker_composition_size_audience.png` | | Flows dashboard and canvas overview. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am1f99367746152699/5ce163e51012aa922d3262d2/flows_dashboard_canvas_overview.png` | | Flow components and drawer configuration examples. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am41475c5c5ade89f8/c12534ffb8d4056d504985f2/flow_components_drawer_configuration_examples.png` | | Common flow blueprints: welcome, re-engagement, and qualification flows built step-by-step in the builder. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am802f683edfbc3650/8982c40c0d11ee157a808640/common_flow_blueprints_welcome_re.gif` | | Flow troubleshooting checklist and status indicators. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am35d2c48ce4f36562/48bab258e8f1b3cd69034778/flow_troubleshooting_checklist_status_indicators.png` | | Flow planning worksheet example. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am5deaf00a9d54aa02/7c9aa7c1ad6257d6426dff51/flow_planning_worksheet_example.png` | | Publish validation modal with step readiness indicators. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amfaf086423bdc732e/0925eefe7324f6732e5e44bb/publish_validation_modal_step_readiness.png` | | Pathfora architecture: JS Tag, profile load, candidate selection, widget render. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am85312a90db368fba/d3e9155e82a358f9b0f3020c/pathfora_architecture_js_tag_profile.png` | | Experiences list view with status filters and summary actions. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am6664283772906285/3a1fc7f5227df806851fe0a2/experiences_list_view_status_filters.png` | | Experience editor flow: provider selection, design, target, display, and review steps. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am504321d9284c6ff0/d0ea4974666fd6df41f1c552/experience_editor_flow_provider_selection.gif` | | Visual comparison of modal, slideout, bar, gate, and inline experience types. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ambe9929797a129924/b039eaec39accf42c9cf6772/visual_comparison_modal_slideout_bar.png` | | Common Pathfora use case blueprints: lead capture, content promotion, and exit-intent rescue configured in the Experiences UI. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ame8fab2157b04f261/6e90fb15242d11e601732526/common_pathfora_case_blueprints_lead.gif` | | Experience summary reporting with reached, clicks, and click rate metrics. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am8aa6b6e61e246acc/697457e52e56a0bc244d34b0/experience_summary_reporting_reached_clicks.png` | | Unknown-to-known lifecycle from anonymous visit to identified profile, showing audience configuration, Pathfora form setup, and profile transition in the UI. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am878d647b35fa7751/c31b64400e2b4fb38f4ab0a1/unknown_known_lifecycle_anonymous_visit.png` | | Lead capture flow from audience targeting through form submit to CRM sync, demonstrated end-to-end in the Lytics UI. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amd72ccd7f42420969/1d2d50acb7d582d40a7a0764/lead_capture_flow_audience_targeting.png` | | Lead conversion journey with flow branches and conversion audience exit, configured in the Flows UI. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am8c98811cdbd0677d/8571b6afb09ef407d4586f50/lead_conversion_journey_flow_branches.png` | | Suppression architecture from customer audience to multi-destination exclusion, showing audience builder configuration and export setup. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am38a59c794f93008c/0ded0d036789cd51e19f5081/suppression_architecture_customer_audience_multi.png` | | Server-side conversion pipeline from Lytics audience triggers to destination conversion APIs, showing export job configuration. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am0e3dcab20bb2520a/e70b6eec06780796d4dcdc7f/server_side_conversion_pipeline_lytics.png` | | Recommendation flow from content graph to API and widget delivery, showing collection configuration, Pathfora recommend widget setup, and validation of response | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ama433d66426774248/aa4cd77fc261bb52a0394f08/recommendation_flow_content_graph_api.gif` | | Account health dashboard with usage, job status, and alert routing. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am0c36db865b910269/202c1b01e82cf1f088718646/account_health_dashboard_usage_job.png` | | Schema audit charts and field usage table. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am74e0c741e6e52752/947f417680883dd7f43431d8/schema_audit_charts_field_usage.png` | | Operations runbook and escalation flow. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am2e4f9e533b265289/f20a2a0e984edadee542d6bc/operations_runbook_escalation_flow.png` | | Consent lifecycle from collection to profile mapping to audience enforcement. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am728079a53eca8119/f5bd2d81409e9b1b9a59ca94/consent_lifecycle_collection_profile_mapping.png` | | Data flow validation pipeline from source to destination. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/amcb3a82dc9d41b553/b1acdfc8af2b5f9d81a83bbc/data_flow_validation_pipeline_source.png` | ### External links | Label | URL | | --- | --- | | Contentstack Academy home | `https://www.contentstack.com/academy/` | | Training instance setup | `https://www.contentstack.com/academy/training-instance` | | Academy playground (GitHub) | `https://github.com/contentstack/contentstack-academy-playground` | | Contentstack documentation | `https://www.contentstack.com/docs/` | | What is Lytics? | `https://docs.lytics.com/docs/lytics-overview` | | Getting Started | `https://docs.lytics.com/docs/getting-started` | | Data Pipeline Overview | `https://docs.lytics.com/docs/data-pipeline` | | Identity Resolution | `https://docs.lytics.com/docs/identity-resolution` | | Behavioral Scoring | `https://docs.lytics.com/docs/behavioral-scoring` | | Walkthrough of the Lytics UI navigation: Home dashboard, Data Pipeline, Building Profiles, Using Profiles, Content, and Account areas. Show where key tools live | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ambad89731e1aa6efd/50a5de84b053715c2ca843c4/walkthrough_lytics_ui_navigation_home.gif` | | Navigating Lytics | `https://docs.lytics.com/docs/navigating-lytics` | | Account Settings | `https://docs.lytics.com/docs/account-settings` | | Use Cases | `https://docs.lytics.com/docs/use-cases` | | Web Personalization | `https://docs.lytics.com/docs/web-personalization` | | Audience Activation | `https://docs.lytics.com/docs/audience-activation` | | Vault landing page showing the five top-level navigation sections (Usage, Settings, Users, Security, Setup). | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am706541a37c1fef70/1dae4ba926e6313667d82802/vault_landing_page_five_top.png` | | Security settings page showing login session and login policy configuration options. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am356bdc3a05ba9079/f76f83eb19ebff55a5986e8d/security_settings_page_login_session.png` | | Walk through inviting a new user: click Create New, enter email, assign roles, and show the resulting invitation. Then demonstrate editing roles on an existing | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am9f6561352bf55ef7/194853f2e36b1d179e52b1ce/walk_inviting_user_click_create.gif` | | Demonstrate creating an access token: click Create New, fill in name/description/expiration/roles, click Create, and copy the one-time token value. | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am7bef78007522ae3d/cb28687212ac0abc5d3e1dec/demonstrate_creating_access_token_click.gif` | | Walk through creating an authorization: open the wizard, select a provider, choose the authorization method, complete the configuration, and verify health statu | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/am84b1e1ae7ef39120/b3dff2264a5554c12d0bd6b7/walk_creating_authorization_open_wizard.gif` | | User Management | `https://docs.lytics.com/docs/user-management` | | Access Tokens | `https://docs.lytics.com/docs/api-tokens` | | Authorizations | `https://docs.lytics.com/docs/authorizations` | | Platform Limits | `https://docs.lytics.com/docs/platform-limits` | | Demonstrate both installation methods: direct snippet installation in a site's HTML head, and Google Tag Manager setup with Custom HTML tag and All Pages trigge | `https://images.contentstack.io/v3/assets/bltebc53cfaf0dd6403/ama7505f0b0263439c/64fa60912826345b5a536022/demonstrate_both_installation_methods_direct.gif` |