Installation

Setup Guide

Complete platform-by-platform setup guide for Produck SDK. Choose your platform below and follow the step-by-step instructions.

📋 Quick Platform Selection

PlatformGuide
Next.jsJump to Next.js
ReactJump to React
Vue.jsJump to Vue
WordPressJump to WordPress
Vanilla JSJump to Vanilla JS

System Requirements

Before getting started, ensure you have:

RequirementVersion
Node.js16.x or higher
npm/yarn/pnpmLatest stable
React18.0.0+ (for React apps)
TypeScript5.0.0+ (optional)

Next.js Setup

Option 1: Next.js App Router (13.4+)

Step 1: Add Package

npm install @prodact.ai/sdk

Step 2: Create Environment File

Create .env.local in your project root:

NEXT_PUBLIC_SDK_KEY=your_sdk_key_here
NEXT_PUBLIC_API_URL=https://api.produck.io/api/v1

Step 3: Set Up Root Layout

Edit app/layout.tsx:

import { ProduckProvider, ProduckChat } from '@prodact.ai/sdk/react';
import type { Metadata } from 'next';
import './globals.css';
 
export const metadata: Metadata = {
  title: 'My App',
  description: 'My awesome app',
};
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ProduckProvider
          config={{
            sdkKey: process.env.NEXT_PUBLIC_SDK_KEY!,
            apiUrl: process.env.NEXT_PUBLIC_API_URL,
          }}
        >
          {children}
          <ProduckChat position="bottom-right" />
        </ProduckProvider>
      </body>
    </html>
  );
}

Step 4: Start Development Server

npm run dev

Visit http://localhost:3000 - you should see the chat widget!

Option 2: Next.js Pages Router

Step 1: Add Package

npm install @prodact.ai/sdk

Step 2: Create Environment File

NEXT_PUBLIC_SDK_KEY=your_sdk_key_here

Step 3: Set Up _app.tsx

Edit pages/_app.tsx:

import { ProduckProvider, ProduckChat } from '@prodact.ai/sdk/react';
import type { AppProps } from 'next/app';
import '@/styles/globals.css';
 
export default function App({ Component, pageProps }: AppProps) {
  return (
    <ProduckProvider
      config={{
        sdkKey: process.env.NEXT_PUBLIC_SDK_KEY!,
      }}
    >
      <Component {...pageProps} />
      <ProduckChat position="bottom-right" />
    </ProduckProvider>
  );
}

Step 4: Start Development

npm run dev

React Setup

For Create React App

Step 1: Add Package

npm install @prodact.ai/sdk

Step 2: Create Environment File

Create .env in project root:

REACT_APP_SDK_KEY=your_sdk_key_here

Step 3: Update src/index.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import { ProduckProvider, ProduckChat } from '@prodact.ai/sdk/react';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';
 
const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);
 
root.render(
  <React.StrictMode>
    <ProduckProvider
      config={{
        sdkKey: process.env.REACT_APP_SDK_KEY!,
      }}
    >
      <App />
      <ProduckChat position="bottom-right" />
    </ProduckProvider>
  </React.StrictMode>
);
 
reportWebVitals();

Step 4: Start App

npm start

For Vite + React

Step 1: Add Package

npm install @prodact.ai/sdk

Step 2: Environment Variables

Create .env:

VITE_SDK_KEY=your_sdk_key_here

Step 3: Update src/main.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import { ProduckProvider, ProduckChat } from '@prodact.ai/sdk/react';
import App from './App';
import './index.css';
 
ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ProduckProvider
      config={{
        sdkKey: import.meta.env.VITE_SDK_KEY,
      }}
    >
      <App />
      <ProduckChat position="bottom-right" />
    </ProduckProvider>
  </React.StrictMode>
);

Step 4: Run Dev Server

npm run dev

WordPress Setup

Step 1: Download Plugin

  1. Go to your Produck Dashboard (opens in a new tab)
  2. Navigate to Downloads or SDK Projects
  3. Download the WordPress Plugin ZIP

Step 2: Add Plugin

Method A: WordPress Admin Upload

  1. Log into WordPress Admin
  2. Go to Plugins → Add New
  3. Click Upload Plugin
  4. Choose the ZIP file you downloaded
  5. Click Install Now
  6. Click Activate

Method B: Manual FTP Upload

# Unzip the plugin
unzip prodact-sdk.zip
 
# Upload to WordPress plugins directory
# Upload the 'prodact-sdk' folder to:
/wp-content/plugins/

Then activate in WordPress Admin → Plugins.

Step 3: Configure Plugin

  1. Go to Settings → Prodact SDK
  2. Enter your SDK Key (from dashboard)
  3. Choose chat widget position
  4. Enable widget on frontend
  5. Click Save Changes

Step 4: Verify Installation

Visit your site - the chat widget should appear!

For advanced WordPress features, see WordPress Guide.

Vanilla JavaScript Setup

Option 1: CDN (Recommended for Quick Start)

<!DOCTYPE html>
<html>
<head>
  <title>My Site</title>
</head>
<body>
  <h1>Welcome</h1>
  
  <script type="module">
    import { createProduck } from 'https://cdn.jsdelivr.net/npm/@prodact.ai/sdk@latest/+esm';
    
    const produck = createProduck({
      sdkKey: 'your_sdk_key_here',
    });
    
    await produck.init();
    
    // Register actions
    produck.register('open-contact', () => {
      document.getElementById('contact-modal').classList.add('open');
    });
  </script>
</body>
</html>

Option 2: NPM Package

Step 1: Add Package

npm install @prodact.ai/sdk

Step 2: Import and Use

import { createProduck } from '@prodact.ai/sdk';
 
const produck = createProduck({
  sdkKey: 'your_sdk_key_here',
});
 
await produck.init();
 
// Register actions
produck.register('show-pricing', () => {
  document.getElementById('pricing').scrollIntoView({ behavior: 'smooth' });
});

For complete vanilla JS documentation, see Vanilla JS Guide.

Vue.js Setup

Vue 3

Step 1: Add Package

npm install @prodact.ai/sdk

Step 2: Create Plugin

Create src/plugins/produck.ts:

import { createProduck } from '@prodact.ai/sdk';
import type { App } from 'vue';
 
export default {
  install(app: App) {
    const produck = createProduck({
      sdkKey: import.meta.env.VITE_SDK_KEY,
    });
    
    produck.init();
    
    app.config.globalProperties.$produck = produck;
    app.provide('produck', produck);
  }
};

Step 3: Register in main.ts

import { createApp } from 'vue';
import App from './App.vue';
import produckPlugin from './plugins/produck';
 
const app = createApp(App);
 
app.use(produckPlugin);
app.mount('#app');

Step 4: Use in Components

<template>
  <button @click="openContact">Contact Us</button>
</template>
 
<script setup lang="ts">
import { inject, onMounted } from 'vue';
 
const produck = inject('produck');
 
onMounted(() => {
  produck.register('open-contact', () => {
    console.log('Contact opened!');
  });
});
 
const openContact = () => {
  console.log('Contact clicked');
};
</script>

Other Frameworks

Angular, Svelte, etc.

Produck SDK core is framework-agnostic. Use the vanilla JS installation:

import { createProduck } from '@prodact.ai/sdk';
 
const produck = createProduck({
  sdkKey: 'your_sdk_key_here',
});
 
await produck.init();

Then integrate into your framework's lifecycle:

  • Angular: Use in service + inject into components
  • Svelte: Use in onMount lifecycle
  • Solid.js: Use in createEffect
  • Astro: Use in client-side islands

Verify Installation

After setup, verify everything works:

1. Check Chat Widget

  • Visit your application
  • Look for chat icon (bottom-right by default)
  • Click to open chat

2. Test SDK Connection

Open browser console and look for:

🚀 Produck SDK Initializing...
✅ Produck SDK initialized with User Flow tracking

No errors should appear.

3. Check Network Tab

  • Open DevTools → Network
  • Refresh page
  • Look for requests to your API
  • Should return 200 OK

What's Enabled by Default

The SDK automatically enables powerful features out of the box:

FeatureDefaultDescription
Smart Recording✅ Auto modeRecords all sessions; automatically discards bounces and bot visits (sessions under 3s with no traction)
User Flow Tracking✅ EnabledTracks clicks, navigation, and form submissions
Privacy Protection✅ EnabledMasks passwords and sensitive inputs
Event Batching✅ EnabledEfficiently batches events before sending
Bounce Filtering✅ EnabledSessions shorter than 5 seconds are automatically discarded

Smart Recording

The SDK uses a smart recording strategy. All sessions are recorded and sent to the backend. Sessions without meaningful user traction (bounces, bots, very short visits) are automatically discarded.

ModeDescription
'auto' (default)rrweb records immediately and all events are sent. The controller tracks traction signals (clicks, navigation, input, scroll). Sessions without traction or shorter than 3s are discarded.
'off'No recording at all.

Traction signals the controller watches for:

  • 'click' — User clicks on the page
  • 'navigation' — User navigates between pages
  • 'input' — User interacts with form fields
  • 'scroll' — User scrolls the page
  • 'rage_click' — 3+ rapid clicks on the same area (user frustration)
  • 'error' — JavaScript error or unhandled promise rejection
  • 'custom' — Your code calls sdk.triggerRecording()

For more details, see Smart Recording.

Disable Features (if needed)

<ProduckProvider
  config={{
    sdkKey: 'your_key',
    apiUrl: 'https://your-api.com/api/v1',
    // Disable session recording
    recording: { enabled: false },
    // Disable user flow tracking
    userFlows: { enabled: false },
  }}
>

Advanced Configuration

Full Configuration Example

<ProduckProvider
  config={{
    sdkKey: process.env.NEXT_PUBLIC_SDK_KEY!,
    apiUrl: process.env.NEXT_PUBLIC_API_URL,
    
    // Smart recording (auto mode by default)
    // Records all sessions, auto-discards bounces
    smartRecording: {
      minimumSessionDuration: 3000,    // Discard bounce sessions (<3s)
      maxEventsPerSession: 10000,      // Hard cap to prevent runaway recording
      fetchServerConfig: true,         // Fetch recording rules from your API
    },
    
    // Session recording settings (rrweb options)
    recording: {
      enabled: true,
      samplingRate: 1.0,  // 100% of sessions (sampling applied before smart logic)
      privacy: {
        maskAllInputs: true,
        maskSelectors: ['.sensitive', '[data-pii]'],
      },
    },
    
    // User flow tracking (enabled by default)
    userFlows: {
      enabled: true,
      samplingRate: 1.0,
      events: {
        clicks: true,
        navigation: true,
        formSubmit: true,
      },
      performance: {
        batchEvents: true,
        batchSize: 10,
        batchTimeout: 5000,
      },
    },
  }}
>

Identify Users

After authentication, identify your users for personalized AI responses:

import { useProduck } from '@prodact.ai/sdk/react';
 
function UserProfile() {
  const { sdk } = useProduck();
  
  useEffect(() => {
    if (sdk && user) {
      sdk.identify({
        identifier: user.id,
        email: user.email,
        name: user.name,
        tags: {
          plan: user.plan,
          role: user.role,
        },
      });
    }
  }, [sdk, user]);
}

Customize Installation

Custom API URL (Self-Hosted)

<ProduckProvider
  config={{
    sdkKey: 'your_key',
    apiUrl: 'https://your-api.com/api/v1',
  }}
>
  {/* Your app */}
</ProduckProvider>

Custom Chat Position

{/* Left side */}
<ProduckChat position="bottom-left" />
 
{/* Right side (default) */}
<ProduckChat position="bottom-right" />

Custom Colors

<ProduckChat
  position="bottom-right"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask me anything!"
/>

TypeScript Support

The SDK includes built-in TypeScript definitions!

Import Types

import type {
  ProduckConfig,
  ProduckSDK,
  ActionPayload,
  ChatMessage,
  MessageRole
} from '@prodact.ai/sdk';

Troubleshooting

Chat widget doesn't appear

  1. Check SDK key is correct
  2. Verify ProduckProvider wraps your app
  3. Check browser console for errors
  4. Restart dev server after adding environment variables

Invalid SDK Key error

  1. Verify key from Produck Dashboard (opens in a new tab)
  2. Check for typos or extra spaces
  3. Ensure correct environment variable name
    • Next.js: NEXT_PUBLIC_SDK_KEY
    • CRA: REACT_APP_SDK_KEY
    • Vite: VITE_SDK_KEY

CORS errors

  • Make sure you're using the correct apiUrl
  • Check if your domain is allowlisted (for production)
  • Contact support if issues persist

Module not found errors

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

Next Steps

Now that installation is complete:

  1. Create Your First Operation - Make the AI do something
  2. Learn Core Concepts - Understand how it works
  3. Explore Examples - See real-world implementations
  4. Read API Reference - Full API documentation

Need help? Visit Troubleshooting or contact [email protected].

Related Documentation

Quick ReferenceCore Concepts