shopcircle-orbit

Lightweight analytics SDK for ShopCircle Orbit. Track events, identify users, record session replays, and measure engagement with zero external dependencies for core tracking.

Install

npm install shopcircle-orbit

Quick Start

import { ShopCircleOrbit } from 'shopcircle-orbit';

const orbit = new ShopCircleOrbit({
  clientId: 'your-client-id',
  apiUrl: 'https://analytics.yoursite.com',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
  enableReplay: true, // Enable session replay
});

// Track a custom event
orbit.track('button_clicked', { label: 'Sign Up', variant: 'primary' });

// Identify a user
orbit.identify('user_123', {
  firstName: 'John',
  email: '[email protected]',
});

// Reset identity (e.g. on logout)
orbit.reset();

// Control replay at runtime
await orbit.enableReplay();
orbit.disableReplay();
orbit.isReplayEnabled(); // true | false

Script Tag

No build step required:

<script type="module">
  import { ShopCircleOrbit } from 'https://esm.sh/shopcircle-orbit';

  const orbit = new ShopCircleOrbit({
    clientId: 'your-client-id',
    apiUrl: 'https://analytics.yoursite.com',
    trackScreenViews: true,
  });

  window.orbit = orbit;
</script>

React / Next.js

import { ShopCircleOrbit } from 'shopcircle-orbit';
import { createContext, useContext, useRef } from 'react';

const OrbitContext = createContext<ShopCircleOrbit | null>(null);

export function OrbitProvider({ children }: { children: React.ReactNode }) {
  const orbitRef = useRef(
    new ShopCircleOrbit({
      clientId: 'your-client-id',
      apiUrl: 'https://analytics.yoursite.com',
      trackScreenViews: true,
      trackOutgoingLinks: true,
    })
  );

  return (
    <OrbitContext.Provider value={orbitRef.current}>
      {children}
    </OrbitContext.Provider>
  );
}

export const useOrbit = () => {
  const ctx = useContext(OrbitContext);
  if (!ctx) throw new Error('Wrap your app with <OrbitProvider>');
  return ctx;
};

Options

| Option | Type | Default | Description | |---|---|---|---| | clientId | string | required | Your client ID from the Orbit dashboard | | apiUrl | string | "" | Base URL of your Orbit instance | | trackScreenViews | boolean | true | Auto-track page views and SPA navigations | | trackOutgoingLinks | boolean | false | Auto-track clicks on external links | | trackAttributes | boolean | false | Auto-track elements with data-orbit-* attributes | | enableReplay | boolean | false | Enable session replay recording (rrweb) |

Session Replay

Record DOM interactions (clicks, scrolls, inputs) for session analysis. Requires admin to enable the feature and client to opt-in.

const orbit = new ShopCircleOrbit({
  clientId: 'your-client-id',
  apiUrl: 'https://analytics.yoursite.com',
  enableReplay: true, // Enable on init
});

// Or enable at runtime
await orbit.enableReplay();

// Disable anytime
orbit.disableReplay();

// Check status
if (orbit.isReplayEnabled()) {
  console.log('Session ID:', orbit.getReplaySessionId());
}

Privacy & Masking

By default:

• All <input> elements are masked
• Elements with sc-block class are excluded from recording
• maskAllInputs: true masks all sensitive data

<!-- This input will be masked -->
<input type="password" />

<!-- This element won't be recorded -->
<div class="sc-block">
  Sensitive content
</div>

Admin Requirements

Replay requires two-level consent:

1. Admin enables feature in Settings → Replay
2. SDK client has opt-in enabled

If either is disabled, SDK won't record sessions and will stop gracefully (403 response).

Data Attributes

Track events declaratively with HTML attributes:

<button data-orbit-event="cta_clicked" data-orbit-variant="hero" data-orbit-plan="pro">
  Get Started
</button>

API

Tracking

| Method | Description | |---|---| | track(name, properties?) | Track a custom event | | identify(profileId, traits?) | Identify a user | | reset() | Clear current user identity | | setDeviceId(id) | Set custom device ID |

Session Replay

| Method | Description | |---|---| | enableReplay() | Start session replay recording (async) | | disableReplay() | Stop session replay recording | | isReplayEnabled() | Check if replay is currently recording | | getReplaySessionId() | Get current replay session ID |

Cleanup

| Method | Description | |---|---| | destroy() | Remove all event listeners and flush events |

License

MIT