Lytics Jstag

Google Tag Manager

1. Create a Custom HTML tag in GTM
2. Paste the Lytics JS Tag snippet
3. Trigger on All Pages
4. Submit and publish

Next.js (via GTM)

If GTM is already installed in app/layout.tsx via next/script, the Lytics tag loads automatically through the GTM Custom HTML tag — no additional code-side work needed.

Configuration

jstag.init({
  src: '//c.lytics.io/api/tag/YOUR_ACCOUNT_ID/latest.min.js',
  loadid: true,                    // Cross-domain identity (third-party cookie)
  stream: 'web_main',             // Custom stream name (default: "default")
  sessecs: 1800,                   // Session timeout in seconds
  qsargs: ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'],
  cookies: { domain: '.yoursite.com' }  // Cookie domain for subdomain tracking
});

Configuration Options

Data Collection

Automatically Collected Fields

Every event automatically includes:

Page Views

Captured automatically on full page loads. For SPAs, call manually:

jstag.pageView();

Custom Events — jstag.send()

jstag.send({
  event: "button_clicked",
  button_name: "hero_cta",
  page_section: "homepage"
});

Signature

jstag.send(STREAM, PAYLOAD, CALLBACK);

jstag.send('checkout_events', { event: "cart_updated", item_count: 3 }, function(response) {
  console.log("Event sent:", response);
});

Payload Best Practices

• Use flat key-value pairs (no nesting)
• Use lowercase snake_case for event names and field keys
• Be specific with event names (product_viewed not click)

// Good
jstag.send({ event: "product_viewed", product_id: "SKU-123", product_category: "shoes" });

// Bad — nested objects, mixed case
jstag.send({ event: "Product Viewed", order: { id: "ORD-456", total: { value: 129.99 } } });

Identity & User Identification

Anonymous Tracking

On first visit, the JS Tag generates a unique _uid stored as a first-party cookie (seerid). This links all activity to a single anonymous profile across sessions.

Identifying Known Users

Send identity data whenever available (login, registration, form submission):

jstag.send({
  event: "login",
  email: "[email protected]",
  userid: "USR-12345",
  first_name: "Jane",
  last_name: "Doe"
});

This merges the anonymous cookie-based profile with any existing profile for that email/user ID.

Custom Entity Identifiers

Use a stronger identifier for authenticated users instead of the cookie:

var user = getAuthenticatedUser();
var config = {
  src: '//c.lytics.io/api/tag/YOUR_ACCOUNT_ID/latest.min.js'
};

if (user && user.id) {
  config.entity = {
    byFieldKey: 'user_id',
    byFieldValue: user.id
  };
} else if (user && user.email) {
  config.entity = {
    byFieldKey: 'email',
    byFieldValue: user.email
  };
}

jstag.init(config);

Cross-Domain Tracking

jstag.init({
  src: '//c.lytics.io/api/tag/YOUR_ACCOUNT_ID/latest.min.js',
  loadid: true
});

Accessing the Anonymous ID

jstag.getid(function(id) {
  console.log("Visitor ID:", id);
});

Common Tagging Patterns

Login / Registration

jstag.send({ event: "login", email: user.email, userid: user.id });
jstag.send({ event: "registration", email: user.email, signup_source: "website", plan: "free" });

Form Submissions

jstag.send({
  event: "newsletter_signup",
  email: email,
  form_name: "footer_newsletter"
});

jstag.send({
  event: "contact_form_submitted",
  email: formData.email,
  name: formData.name,
  inquiry_type: formData.subject
});

E-Commerce

// Product view
jstag.send({ event: "product_viewed", product_id: "SKU-789", product_name: "Running Shoes", product_price: 89.99 });

// Add to cart
jstag.send({ event: "add_to_cart", product_id: "SKU-789", quantity: 1, cart_value: 89.99 });

// Purchase
jstag.send({ event: "purchase_completed", order_id: "ORD-456", order_value: 129.99, currency: "USD", item_count: 2 });

Content Engagement

jstag.send({ event: "search", search_query: "running shoes", results_count: 24 });
jstag.send({ event: "video_played", video_id: "VID-001", video_title: "Product Demo", video_duration: 180 });
jstag.send({ event: "file_downloaded", file_name: "whitepaper.pdf", file_type: "pdf" });

Campaign & UTM Attribution

Capture automatically via config:

jstag.init({
  src: '//c.lytics.io/api/tag/YOUR_ACCOUNT_ID/latest.min.js',
  qsargs: ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content']
});

Declarative Tracking with lx-* Attributes

Track interactions directly in HTML markup — no JavaScript required.

Enable the Plugin

jstag.init({
  src: '//c.lytics.io/api/tag/YOUR_ACCOUNT_ID/latest.min.js',
  lx: { disabled: false }
});

Attributes

All attributes also work with data- prefix (e.g., data-lx-trigger).

Examples

<!-- Button click -->
<button lx-trigger="click" lx-send="event=cta_clicked&button_name=hero_signup">
  Sign Up Now
</button>

<!-- Using individual attributes -->
<button lx-trigger="click" lx-send-event="cta_clicked" lx-send-button_name="hero_signup">
  Sign Up Now
</button>

<!-- Form submission (auto-collects all field values) -->
<form lx-trigger="submit">
  <input name="email" type="email" />
  <input name="signup_source" type="hidden" value="footer_newsletter" />
  <button type="submit">Subscribe</button>
</form>

<!-- Custom stream -->
<button lx-trigger="click" lx-send="event=download&file=whitepaper.pdf" lx-stream="content_engagement">
  Download
</button>

Notes

• Hyphens in lx-send-* names convert to dots in payload (lx-send-user-name -> user.name)
• Uses event delegation — dynamically added elements are tracked automatically
• lx-trigger="submit" calls preventDefault() — handle form submission separately

Single Page Apps (SPA)

Route Change Handling

function onRouteChange() {
  jstag.pageView();
  jstag.loadEntity(function(profile) {
    console.log("Profile refreshed:", profile.data);
  });
}

React

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function LyticsPageTracker() {
  const location = useLocation();
  useEffect(() => {
    window.jstag.pageView();
    window.jstag.loadEntity();
  }, [location.pathname]);
  return null;
}

Next.js App Router

For Next.js with App Router, track route changes in a client component:

"use client";
import { useEffect } from "react";
import { usePathname } from "next/navigation";

export default function LyticsPageTracker() {
  const pathname = usePathname();
  useEffect(() => {
    if (window.jstag) {
      window.jstag.pageView();
      window.jstag.loadEntity();
    }
  }, [pathname]);
  return null;
}

Widget Refresh Control

Prevent widget flickering on frequent route changes:

jstag.init({
  src: '//c.lytics.io/api/tag/YOUR_ACCOUNT_ID/latest.min.js',
  pathfora: { publish: { listenForProfileChange: true } }
});

Accessing Visitor Profiles

Entity Ready Callback

jstag.call('entityReady', function(profile) {
  var user = profile.data.user;
  console.log("Audiences:", user.segments);
  console.log("Email:", user.email);
});

Profile Data Structure

{
  "data": {
    "user": {
      "email": "[email protected]",
      "segments": ["all", "known_users", "high_value"],
      "first_name": "Jane"
    },
    "experiences": [
      {
        "experience_id": "f53e136b35c498ac944b56a0658ab672",
        "experience_slug": "welcome_offer"
      }
    ]
  }
}

Audience Membership

// Via callback (recommended)
jstag.call('entityReady', function(profile) {
  var audiences = profile.data.user.segments;
  if (audiences.indexOf('high_value') !== -1) {
    showVIPExperience();
  }
});

// Via direct method (only after profile loaded)
jstag.getSegments();

// Via localStorage (zero latency, cached)
var audiences = JSON.parse(localStorage.lytics_segments);

Reloading the Profile

jstag.loadEntity(function(profile) {
  console.log("Profile refreshed:", profile.data);
});

Content Recommendations

jstag.recommend(
  { limit: 5, collection: "blog-posts", visited: false, shuffle: true },
  function(recommendations) {
    recommendations.forEach(function(item) {
      console.log("Recommended:", item.title, item.url);
    });
  }
);

Options

Error Handling

jstag.on("recommend.failure", function(error) {
  console.error("Recommendation error:", error);
  displayFallbackContent();
});

Integration Patterns

Forward Profile to Other Tools

jstag.call('entityReady', function(profile) {
  var user = profile.data.user;
  if (!user) return;

  // Google Analytics 4
  gtag('set', { 'audience_name': user.segments });

  // Any other tool
  yourTool.setUserData({
    lytics_audiences: user.segments,
    lytics_email: user.email
  });
});

Data Flow

Browser (jstag.send)
    -> /c endpoint (collection)
        -> Data Stream (e.g., "default")
            -> LQL Processing (field mapping, identity resolution)
                -> User Profile (audiences, scores, affinities)
                    -> /personalize endpoint
                        -> Browser (entityReady callback)

Quick Reference

Methods

Events

Cookies & Storage

Debugging

jstag.config.version          // Tag version
jstag.isLoaded                // True if all resources loaded
jstag.getSegments()           // Current audience membership
jstag.getEntity()             // Full profile data
jstag.getid(id => console.log(id))  // Anonymous visitor ID

In the Network tab, filter for lytics.io:

• /c endpoint — collection requests from jstag.send()
• /personalize endpoint — profile fetch requests

Manual Steps (Cannot Be Automated)

1. Create a Lytics account — Sign up at lytics.com and get your account ID from Account Settings.

2. Install the JS Tag — If using GTM, create a Custom HTML tag in the GTM UI with the Lytics snippet, trigger on All Pages, and publish. This is already done if the GTM container has the "Lytics CDP - Initialize" tag.

3. Configure streams and LQL — Custom streams require corresponding LQL statements in the Lytics app to map raw fields to user profile fields. This is done in the Lytics UI under Data > Streams.

4. Set up audiences — Create audiences in the Lytics app that will be available via getSegments() and the entityReady callback. Enable API access for audiences you want surfaced client-side.

5. Surface profile fields — In Lytics Account Settings, configure which user attributes are returned by the /personalize endpoint (and thus available in entityReady callbacks).

6. Configure content collections — For jstag.recommend(), set up content collections in the Lytics app that define which content is eligible for recommendations.

Troubleshooting

Tag Not Loading

• Verify jstag is defined in the console
• Check that the src URL is correct and accessible
• If using GTM, verify the tag is firing (use GTM Preview mode)

Data Not Being Sent

• Check Network tab for requests to lytics.io/c
• Test with jstag.send({ event: "test" }) in the console
• Verify the stream exists in the Lytics app

Profile Not Loading

• Check Network tab for /personalize requests
• Verify audiences are enabled for API access
• Use jstag.getEntity() to inspect current profile data

Numbers Not Matching Other Tools

• Lytics merges profiles across devices — counts may be lower than cookie-based tools
• Compare same time period, property, and filters
• Account for employee traffic and bots

Reference

• Lytics JS Tag Documentation
• Data Upload API
• Personalization API
• Lytics App Installation