@readyplayerme/icp-analytics

@readyplayerme/icp-analytics

A TypeScript analytics package designed for Next.js server-side environments to track user interactions and page loads for Ready Player Me ICP (Interactive Character Platform) applications.

Features

• 🎯 Server-side Session Tracking: Cookie-based session management with 30-minute timeout
• 👤 User Identification: Persistent user IDs across sessions via cookies
• 🌍 Geolocation: Automatic country detection via Vercel geo headers with IP fallback
• 📱 Device Detection: Server-side device type detection from user-agent
• 🚀 Traffic Source Tracking: UTM parameters and referrer tracking
• 📊 Flow Analytics: Sequential interaction numbering within sessions
• 🔄 Auto-retry: Robust error handling with graceful fallbacks
• 🍪 Cookie Management: Automatic session persistence via HTTP cookies

Prerequisites

Next.js Project

This package requires a Next.js project (version 13 or higher) with server-side capabilities.

Environment Variables

Set these environment variables in your Next.js project:

EVENTS_WEBHOOK_URL=https://us-webhook.hevodata.com/t/your-webhook-id
EVENTS_ACCESS_KEY=your-access-key
EVENTS_SECRET_KEY=your-secret-key

Installation

npm install @readyplayerme/icp-analytics

Usage

In API Routes or Server Components

import { NextRequest, NextResponse } from 'next/server';
import { 
  trackIcpLoaded, 
  trackIcpInteracted, 
  createTrackingContext 
} from '@readyplayerme/icp-analytics';

// In an API route
export async function GET(request: NextRequest) {
  const context = createTrackingContext(request, 'my_game_project');
  
  // Track page load
  const { sessionCookie } = await trackIcpLoaded(context, 'homepage');
  
  const response = NextResponse.json({ success: true });
  
  // Set session cookie
  response.cookies.set('icp_session', sessionCookie, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    maxAge: 30 * 60 * 1000 // 30 minutes
  });
  
  return response;
}

// Track user interaction
export async function POST(request: NextRequest) {
  const context = createTrackingContext(request);
  
  const { sessionCookie } = await trackIcpInteracted(
    context,
    'start_game_button',
    'Chess Game Card',
    'games_page'
  );
  
  const response = NextResponse.json({ success: true });
  response.cookies.set('icp_session', sessionCookie, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    maxAge: 30 * 60 * 1000
  });
  
  return response;
}

In Middleware

import { NextRequest, NextResponse } from 'next/server';
import { trackIcpLoaded, createTrackingContext } from '@readyplayerme/icp-analytics';

export async function middleware(request: NextRequest) {
  // Track page loads automatically
  if (request.nextUrl.pathname.startsWith('/games')) {
    const context = createTrackingContext(request);
    const { sessionCookie } = await trackIcpLoaded(context, 'games_page');
    
    const response = NextResponse.next();
    response.cookies.set('icp_session', sessionCookie, {
      httpOnly: true,
      secure: process.env.NODE_ENV === 'production',
      sameSite: 'lax',
      maxAge: 30 * 60 * 1000
    });
    
    return response;
  }
}

API Reference

createTrackingContext(request: NextRequest, projectName?: string)

Creates a tracking context for server-side analytics.

Parameters:

• request (required): Next.js request object
• projectName (optional): Custom project name, defaults to hostname-based name

Returns: TrackingContext object

trackIcpLoaded(context: TrackingContext, screenCategory: string, screenName?: string)

Tracks page or screen load events server-side.

Parameters:

• context (required): Tracking context from createTrackingContext()
• screenCategory (required): Readable name of the page (e.g., 'homepage', 'games_page')
• screenName (optional): Custom screen name, defaults to request pathname

Returns: Promise resolving to { sessionCookie: string }

trackIcpInteracted(context: TrackingContext, elementName: string, subelementId: string, screenCategory: string, screenName?: string)

Tracks user interaction events server-side.

Parameters:

• context (required): Tracking context from createTrackingContext()
• elementName (required): Name of the interactive element (e.g., 'start_game_button')
• subelementId (required): Detailed information about what was clicked (e.g., 'Chess Game Card')
• screenCategory (required): Readable name of the page where interaction occurred
• screenName (optional): Custom screen name, defaults to request pathname

Returns: Promise resolving to { sessionCookie: string }

getClientIP(request: NextRequest)

Utility function to extract client IP from request headers.

Parameters:

• request (required): Next.js request object

Returns: Client IP address string

enhanceSessionWithCountry(sessionData: SessionData, clientIP: string)

Enhances session data with country information from IP lookup.

Parameters:

• sessionData (required): Session data object
• clientIP (required): Client IP address

Returns: Promise resolving to enhanced SessionData

Event Data Structure

Both functions send events with the following structure:

{
  event: 'icp_interacted',
  properties: {
    user_session_id: 'unique-session-id',
    user_pseudo_id: 'unique-user-id',
    product_name: 'project-name',
    screen_name: '/path/or/custom-name',
    screen_category: 'readable-page-name',
    interaction: 'loaded' | 'tap',
    element_name: 'element-name' | null,
    subelement_id: 'subelement-details' | null,
    flow_number: 1,
    country: 'US',
    device_type: 'desktop' | 'mobile' | 'tablet' | 'unknown',
    traffic_source: 'direct' | 'utm-source' | 'referrer-domain'
  }
}

Automatic Data Collection

The package automatically collects:

• Session ID: Unique per session, expires after 30 minutes of inactivity
• User ID: Persistent across sessions using HTTP cookies
• Project Name: Extracted from hostname (converts hyphens to underscores)
• Country: From Vercel geo headers or IP geolocation fallback
• Device Type: Based on user agent detection
• Traffic Source: From UTM parameters or referrer
• Flow Number: Auto-incrementing counter per session

Cookie Management

The package uses HTTP-only cookies for session persistence:

// Recommended cookie settings
response.cookies.set('icp_session', sessionCookie, {
  httpOnly: true,                                    // Security
  secure: process.env.NODE_ENV === 'production',    // HTTPS only in production
  sameSite: 'lax',                                   // CSRF protection
  maxAge: 30 * 60 * 1000                            // 30 minutes
});

Browser Compatibility

• Server-side only (Next.js 13+)
• No browser dependencies
• Works with any client device

Error Handling

The package includes robust error handling:

• Network failures are logged but don't throw errors
• Invalid data gracefully falls back to 'unknown' values
• Missing environment variables are handled gracefully

Privacy Considerations

• Uses HTTP-only cookies for session persistence
• Country detection via IP geolocation service
• No personal data is collected beyond anonymous user IDs
• Server-side processing ensures data security

Development

Building the Package

npm run build

Type Definitions

TypeScript definitions are included. The package exports proper types for all functions.

License

MIT

Support

For issues related to this package, please contact the Ready Player Me development team.