Installation

This guide walks through installing and configuring the Pishoniq SDK. Most teams complete setup in under five minutes.

Prerequisites

• A Pishoniq account (sign up at /signup)
• A created project in the dashboard
• An SDK key from Settings → API Keys (it starts with pk_live_ or pk_test_)

1. Install the package

npm install pishoniq

Alternative package managers:

yarn add pishoniq
# or
pnpm add pishoniq

2. Initialize the SDK

The SDK requires two values: an apiKey and a host (your Pishoniq backend URL).

Vanilla JavaScript (any framework)

import PishonIQ from 'pishoniq'

PishonIQ.init({
  apiKey: 'pk_live_your_key_here',
  host: 'https://your-pishoniq-backend.com',
})

React (Provider + Hooks)

import { PishonIQProvider, usePishonIQ } from 'pishoniq/react'

function App() {
  return (
    <PishonIQProvider
      apiKey={process.env.NEXT_PUBLIC_PISHONIQ_KEY!}
      host={process.env.NEXT_PUBLIC_PISHONIQ_HOST!}
    >
      <YourApp />
    </PishonIQProvider>
  )
}

Then in any component:

function SignupButton() {
  const { track } = usePishonIQ()

  return (
    <button
      onClick={() => {
        track('signup_cta_clicked', { source: 'hero' })
        // ... rest of signup flow
      }}
    >
      Get started
    </button>
  )
}

3. Next.js integration

The React provider requires a router context. If you use react-router-dom, wrap the app in BrowserRouter. If you use Inertia.js, use the vanilla SDK instead (see the snippet below).

'use client'

import { useEffect } from 'react'
import PishonIQ from 'pishoniq'

export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    PishonIQ.init({
      apiKey: process.env.NEXT_PUBLIC_PISHONIQ_KEY!,
      host: process.env.NEXT_PUBLIC_PISHONIQ_HOST!,
    })
  }, [])

  return <>{children}</>
}

Store your credentials in .env.local:

NEXT_PUBLIC_PISHONIQ_KEY=pk_live_xxxxxxxx
NEXT_PUBLIC_PISHONIQ_HOST=https://your-pishoniq-backend.com

4. Verify the installation

Confirm the integration by sending a test event:

PishonIQ.track('sdk_installed')

Then open your Pishoniq dashboard. The event should appear in the Events view within a few seconds.

Auto-captured events

The SDK automatically captures these events — no extra code required:

| Event | When it fires | |---|---| | page_view | On initial load and route change | | click | On button/link clicks (and elements with data-pishon attribute) | | scroll_depth | At 25%, 50%, 75%, 100% scroll milestones | | session_start | When a new session begins (30 min inactivity timeout) | | session_end | When the user leaves the page (via sendBeacon) | | identify | When PishonIQ.identify() is called |

Next steps

• Event Tracking — Custom events, user identification, page views
• AI Insights — Natural language queries and anomaly detection