@hrnt/ecosystem-core

Cross-site behavioral science and analytics engine for the HRNT ecosystem.

Overview

This package provides a unified system for tracking visitor behavior across all HRNT sites (Portfolio, Shop, Bio, Docs, Booking) with:

• Cross-domain visitor identity (shared cookies across .irakozehornet.com)
• 7-segment visitor classification including Wildcard detection
• GDPR-compliant consent management
• Unified event tracking across all sites
• Behavioral science patterns (exit intent, social proof, etc.)

Installation

npm install @hrnt/ecosystem-core

Quick Start

Basic Setup

import { EcosystemIdentity, SegmentEngine, EcosystemTracker, ConsentManager } from '@hrnt/ecosystem-core';

// 1. Initialize visitor identity
const identity = new EcosystemIdentity('portfolio');
const visitor = identity.init();

// 2. Set up consent
const consent = createConsentManager('portfolio');

// 3. Initialize tracker
const tracker = new EcosystemTracker({
  site: 'portfolio',
  endpoint: 'https://api.irakozehornet.com/analytics'
});
tracker.setVisitor(visitor);

// 4. Set up segmentation
const segmentEngine = new SegmentEngine();
segmentEngine.onSegmentChange((from, to, confidence) => {
  console.log(`Visitor changed from ${from} to ${to} (${confidence} confidence)`);
});

// 5. Track events
tracker.pageView();
tracker.click('hero-cta');

Visitor Segmentation

The system classifies visitors into 7 segments:

| Segment | Detection | Purpose | |---------|-----------|---------| | New | First visit | Welcome flow | | Brand | Views /partnerships, /media-kit, 90s+ engagement | Sponsorship pipeline | | Buyer | Shop product views, cart, purchase | Conversion optimization | | Reader | Blog dwell, newsletter signup | Content engagement | | Fan | 3+ sites visited, returns frequently | Community building | | Client | Booking views, service pages | Consultation funnel | | Creator | Resource downloads, LUT views | Free → paid conversion | | Wildcard | Low engagement, no conversions, returns | Capture & remarketing |

Wildcard Detection Algorithm

Wildcards are detected using a 35+ point scoring system:

// Signals (max 100 points)
- Low time on site (<30s): 15 points
- Low scroll depth (<25%): 10 points
- Single page session: 10 points
- No clicks: 5 points
- No conversions: 15 points
- Returns without converting: 15 points
- No form interactions: 10 points
- Direct traffic: 10 points
- Forum referrer: 10 points

// Classification
if (score >= 35) segment = 'wildcard';

GDPR Compliance

Consent Categories

• Essential: Always enabled (site function)
• Analytics: Visitor tracking, page views
• Personalization: Recommendations, segmentation
• Marketing: Retargeting, email capture

Usage

const consent = createConsentManager('portfolio');

// Check permissions
if (consent.canTrackAnalytics()) {
  tracker.pageView();
}

if (consent.canCaptureWildcard()) {
  showWildcardCaptureModal();
}

// Give consent
consent.giveConsent({ analytics: true, personalization: true });
consent.acceptAll();
consent.rejectAll();

// Withdraw
consent.withdrawConsent();

Cross-Domain Tracking

All sites share cookies on .irakozehornet.com:

• hrnt_vid: Visitor ID (38 months)
• hrnt_sid: Session ID (30 minutes, sliding)
• hrnt_consent: GDPR consent (365 days)

This enables:

• Single visitor identity across sites
• Cross-site journey tracking
• Unified segmentation

API Reference

EcosystemIdentity

const identity = new EcosystemIdentity(site, options);
identity.init(); // Initialize and get visitor
identity.getIdentity(); // Get current identity
identity.isNewVisitor(); // Check if first visit
identity.isReturning(); // Check if returning

SegmentEngine

const engine = new SegmentEngine(signals, crossSiteData);
engine.updateSignals({ timeOnSite: 45 });
engine.detect(currentUrl); // Get segment
engine.onSegmentChange(callback);

EcosystemTracker

const tracker = new EcosystemTracker(config);
tracker.setVisitor(visitor);
tracker.track('event_type', properties);
tracker.pageView();
tracker.click('target');
tracker.conversion('purchase', 99.99);
tracker.wildcardCapture('email');

ConsentManager

const consent = createConsentManager(site);
consent.hasConsent();
consent.hasCategoryConsent('analytics');
consent.canTrackAnalytics();
consent.canPersonalize();
consent.canMarket();
consent.canCaptureWildcard();
consent.giveConsent({ analytics: true });
consent.acceptAll();
consent.rejectAll();
consent.withdrawConsent();

Events

Standard event types:

• page_view, scroll_depth
• click, hover, focus
• product_view, cart_add, purchase
• article_view, download, resource_access
• partnership_view, media_kit_download
• booking_start, booking_complete
• email_capture, exit_intent_shown
• wildcard_detected, wildcard_capture
• segment_change, cross_site_nav

Database Schema

See migrations/001_initial_schema.sql for Supabase schema.

Key tables:

• ecosystem_visitors: Core identity
• ecosystem_sessions: Cross-site sessions
• ecosystem_events: Raw event stream
• ecosystem_journeys: Journey attribution
• ecosystem_consent: GDPR consent records

Data Retention

Per GDPR best practices:

| Data | Retention | Notes | |------|-----------|-------| | Raw events | 26 months | Google Analytics standard | | Sessions | 26 months | Attribution analysis | | Visitors | 38 months | Facebook-style extended | | Consent | 7 years | Legal requirement | | Aggregates | Indefinite | Anonymized |

License

MIT