ribby-sdk

v0.1.2

Published

21 days ago

Analytics, Web Vitals tracking, and QA tools for React, Next.js, and Vite apps

0High
0Medium
0Low

niledex

analytics web-vitals react nextjs ribby tracking qa

ribby

Lightweight analytics and Web Vitals tracking for React, Next.js, Vite, and any JavaScript app.

Installation

npm install ribby-sdk
# or
yarn add ribby
# or
pnpm add ribby

React / Vite

// src/main.tsx or src/App.tsx
import { RibbyAnalytics } from 'ribby-sdk/react'

function App() {
  return (
    <>
      <RibbyAnalytics siteKey="YOUR_SITE_KEY" />
      {/* rest of your app */}
    </>
  )
}

Next.js (App Router)

// app/layout.tsx
import { RibbyAnalytics } from 'ribby-sdk/next'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <RibbyAnalytics siteKey="YOUR_SITE_KEY" />
        {children}
      </body>
    </html>
  )
}

Next.js (Pages Router)

// pages/_app.tsx
import { RibbyAnalytics } from 'ribby-sdk/next'
import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <RibbyAnalytics siteKey="YOUR_SITE_KEY" />
      <Component {...pageProps} />
    </>
  )
}

Vanilla JS / HTML (no bundler)

<script>
  window.ribby = { q: [] };
  window.ribby.init = (c) => window.ribby.q.push(['init', c]);
  window.ribby.track = (e, p) => window.ribby.q.push(['track', e, p]);
</script>
<script defer src="https://cdn.ribby.app/analytics.js" data-site-key="YOUR_SITE_KEY"></script>

Tracking custom events

import { track } from 'ribby-sdk/react'
// or from 'ribby-sdk/next'
// or from 'ribby'

// Track a button click
track('signup_click', { plan: 'pro' })

// Track a purchase
track('purchase', { value: 49.99, currency: 'USD' })

Or use the hook:

import { useRibby } from 'ribby-sdk/react'

function SignUpButton() {
  const { track } = useRibby()

  return (
    <button onClick={() => track('signup_click', { plan: 'pro' })}>
      Sign up
    </button>
  )
}

Configuration

<RibbyAnalytics
  siteKey="YOUR_SITE_KEY"  // required — from your Ribby dashboard
  vitals={true}             // collect Web Vitals (LCP, FID, CLS, TTFB, FCP). default: true
  disabled={false}          // disable tracking entirely. default: false
  trackHashChanges={true}   // track hash-based SPA navigation. default: true
/>

What gets tracked

| Data | Description | |---|---| | Page URL | Current page path (no query strings with sensitive data) | | Referrer | Where the visitor came from | | Device type | Desktop / Mobile / Tablet | | Browser | Chrome / Safari / Firefox / Edge | | Session ID | Random ID per browser session (not stored server-side between sessions) | | Web Vitals | LCP, FID, CLS, TTFB, FCP — only if vitals={true} |

No cookies are set. Sessions use sessionStorage which clears when the tab closes.
Do Not Track is respected. If the visitor has DNT enabled, no data is sent.

Privacy

No cookies
No cross-site tracking
Respects Do Not Track
No personal data collected (no IPs stored, no fingerprinting)
GDPR-friendly by design

Your site key

Find your site key in the Ribby dashboard → Analytics → Setup.