Analytics

Track user behavior and custom events. Analytics can be enabled/disabled in your configuration.

Configuration

{
  analytics: {
    enabled: true,
    endpoint: "https://logs.sesamy.com/events"
  }
}

Methods

analytics.track()

Track custom events with optional properties.

Parameters:

• eventName (string) - Event name
• properties (object, optional) - Event properties

Returns: Promise<void>

Example:

// Basic event
await window.sesamy.analytics.track('article_read');

// Event with properties
await window.sesamy.analytics.track('article_read', {
  articleId: 'article_123',
  category: 'technology',
  readTime: 120,
  author: 'John Doe',
});

// Track purchase intent
await window.sesamy.analytics.track('checkout_started', {
  sku: 'premium_monthly',
  price: 9.99,
  currency: 'USD',
});

// Track engagement
await window.sesamy.analytics.track('video_play', {
  videoId: 'video_456',
  duration: 300,
  position: 45,
});

Automatic Tracking

The SDK automatically tracks certain events:

• Page views - Tracked on page load and router updates
• Scroll depth - Tracked at 25%, 50%, 75%, and 100%
• Active/idle time - User engagement duration
• Authentication events - Login, logout
• Purchase events - Checkout creation, completion

Common Patterns

Track Article Engagement

window.addEventListener('sesamyJsReady', async () => {
  const article = window.sesamy.content.get('article.main');

  // Track article view
  await window.sesamy.analytics.track('article_view', {
    articleId: article.id,
    title: article.title,
    category: article.category,
  });

  // Track reading progress
  let readTime = 0;
  const interval = setInterval(async () => {
    readTime += 10;

    if (readTime % 60 === 0) {
      await window.sesamy.analytics.track('article_reading', {
        articleId: article.id,
        secondsRead: readTime,
      });
    }
  }, 10000); // Every 10 seconds

  // Track completion
  window.addEventListener('beforeunload', async () => {
    clearInterval(interval);
    await window.sesamy.analytics.track('article_complete', {
      articleId: article.id,
      totalReadTime: readTime,
    });
  });
});

Track Purchase Funnel

// Track funnel stages
async function trackPurchaseFunnel() {
  // 1. Product view
  await window.sesamy.analytics.track('product_viewed', {
    sku: 'premium_monthly',
    price: 9.99,
  });

  // 2. Add to cart (when user clicks subscribe)
  document.querySelector('#subscribe-btn').addEventListener('click', async () => {
    await window.sesamy.analytics.track('add_to_cart', {
      sku: 'premium_monthly',
    });

    // Create checkout
    const checkout = await window.sesamy.checkouts.create({
      items: [{ sku: 'premium_monthly' }],
      redirectUrl: window.location.href,
    });

    // 3. Checkout started
    await window.sesamy.analytics.track('checkout_started', {
      checkoutId: checkout.id,
      sku: 'premium_monthly',
    });

    window.location.href = checkout.checkoutUrl;
  });
}

// 4. Track completion (on return from checkout)
window.addEventListener('sesamyJsReady', async () => {
  const urlParams = new URLSearchParams(window.location.search);
  if (urlParams.get('checkout_complete')) {
    await window.sesamy.analytics.track('purchase_complete', {
      checkoutId: urlParams.get('checkout_id'),
    });
  }
});

Track User Engagement

// Track feature usage
async function trackFeatureUsage() {
  // Track filter usage
  document.querySelector('#filter').addEventListener('change', async (e) => {
    await window.sesamy.analytics.track('filter_used', {
      filterType: 'category',
      filterValue: e.target.value,
    });
  });

  // Track search
  document.querySelector('#search').addEventListener('submit', async (e) => {
    e.preventDefault();
    await window.sesamy.analytics.track('search_performed', {
      query: e.target.querySelector('input').value,
    });
  });

  // Track social sharing
  document.querySelectorAll('.share-btn').forEach((btn) => {
    btn.addEventListener('click', async () => {
      await window.sesamy.analytics.track('content_shared', {
        platform: btn.dataset.platform,
        contentId: btn.dataset.contentId,
      });
    });
  });
}

Best Practices

1. Use Descriptive Event Names - Use clear, consistent naming (e.g., article_viewed, not view)
2. Include Relevant Context - Add properties that help analyze behavior
3. Track Key Moments - Focus on actions that indicate engagement or intent
4. Respect Privacy - Don't track personally identifiable information in properties
5. Test Events - Verify events are firing correctly before deployment

Disabling Analytics

You can disable analytics in configuration:

{
  analytics: {
    enabled: false;
  }
}

Or conditionally based on user consent:

// Check user consent before enabling
const hasConsent = localStorage.getItem('analytics_consent') === 'true';

await init({
  clientId: 'your-client-id',
  analytics: {
    enabled: hasConsent,
  },
});

Next Steps

• API Reference - Track with purchase and access events
• Content Management - Track content engagement