Frequently Asked Questions

Common questions about Produck SDK.

General

What is Produck SDK?

Produck SDK enables AI-powered UI interactions in web applications. Users can control your interface through natural language instead of clicking buttons or navigating menus.

How is this different from a chatbot?

Traditional chatbots provide text responses. Produck SDK actually controls your UI - opening modals, scrolling to sections, filling forms, changing application state, etc.

Do I need AI/ML knowledge to use this?

No! The AI is handled by Produck. You just register JavaScript functions and we match them to user intent automatically.

What frameworks are supported?

✅ React (official support with hooks and components)
✅ Vanilla JavaScript (framework-agnostic core)
🔜 Vue, Angular, Svelte (coming soon)

You can use the vanilla JS core with any framework today.

Setup & Installation

How do I get an SDK key?

Create a Produck account
Create an organization
Go to SDK Projects
Create a new project
Copy your SDK key

Can I use one SDK key for multiple applications?

Yes, but we recommend separate projects for:

Development vs Production
Different products/applications
Different teams

Is the SDK key secret?

No, SDK keys are meant to be public (used in frontend code). They authenticate your project, not individual users. User authentication is separate.

What's the difference between SDK key and guider ID?

SDK Key: For programmatic UI control (new, recommended)
Guider ID: For conversational AI assistants (legacy)

They're separate systems. SDK projects are independent from guiders.

Operations

How many operations can I create?

There's no hard limit. Create as many as you need, but:

Start with core actions (5-10)
Add more based on usage patterns
Avoid overlapping trigger phrases

Can operations overlap?

Technically yes, but avoid it. Similar trigger phrases across operations can cause confusion. Be specific and distinct.

Can I change an operation ID after creation?

No, operation IDs are immutable. To change an ID:

Create a new operation with the new ID
Update your code to use the new ID
Delete the old operation

How many trigger phrases should I add?

Recommended: 3-10 phrases per operation

Minimum 3 for good coverage
Include variations (questions, commands, synonyms)
Don't go overboard (diminishing returns after ~10)

Do trigger phrases need to match exactly?

No! Our AI understands intent, not exact matches. "contact support", "get in touch", and "I need help with something" can all trigger the same operation.

React Integration

Do I need to wrap my entire app with ProduckProvider?

Yes, ProduckProvider should wrap your app at the root level (similar to Redux Provider or React Query Provider).

Can I have multiple ProduckProvider instances?

Not recommended in the same app. Use one provider at the root. For multiple SDK projects, switch the sdkKey prop.

Why isn't my action handler firing?

Common issues:

Not registered - Make sure useProduckAction() is called
Wrong operation ID - Check spelling matches dashboard
Component unmounted - Handler unregisters when component unmounts
SDK not initialized - Check useProduckReady() returns true

Can I use hooks outside ProduckProvider?

No, all Produck hooks require ProduckProvider as an ancestor. You'll get a context error otherwise.

// ❌ Won't work
function App() {
  useProduckAction('test', handler); // Error!
  return <div>App</div>;
}
 
// ✅ Correct
function App() {
  return (
    <ProduckProvider config={{sdkKey: 'key'}}>
      <MyComponent />
    </ProduckProvider>
  );
}
 
function MyComponent() {
  useProduckAction('test', handler); // Works!
  return <div>Component</div>;
}

Vanilla JS

Can I use this without React?

Absolutely! The core SDK (@produck/sdk) works with vanilla JavaScript or any framework.

import { createProduck } from '@produck/sdk';
 
const produck = createProduck({ sdkKey: 'your-key' });
await produck.init();
produck.register('action', handler);

How do I use it with Vue/Angular/Svelte?

Use the vanilla JS core:

// Vue 3 Composition API
import { createProduck } from '@produck/sdk';
import { onMounted, onUnmounted } from 'vue';
 
const produck = createProduck({ sdkKey: 'key' });
 
onMounted(async () => {
  await produck.init();
  produck.register('my-action', handler);
});
 
onUnmounted(() => {
  produck.destroy();
});

Performance

What's the bundle size impact?

Core SDK: ~8KB gzipped
React bindings: ~4KB gzipped
Total: ~12KB gzipped

Tree-shaking removes unused code.

Does it slow down my app?

No significant performance impact:

Initialization is async (non-blocking)
Message handling is optimized
Event system is lightweight

How many operations can I register without performance issues?

Hundreds. Operation registration is O(1) and uses a Map internally.

Does the chat widget affect page load time?

Minimal impact. The widget:

Loads asynchronously
Doesn't block rendering
Uses lazy loading for messages

Security

Is it safe to expose the SDK key?

Yes, SDK keys are designed to be public. They authenticate your project but don't grant admin access. Think of them like Stripe publishable keys.

How do I secure user-specific actions?

Actions run in the user's browser with their session. Use your existing authentication:

useProduckAction('delete-account', async () => {
  // This runs with user's auth token
  await api.deleteAccount(userToken);
});

Can users trigger actions they shouldn't have access to?

No, because:

Actions run client-side with user's permissions
Your backend validates permissions
RLS policies protect organization data

What about XSS attacks?

The SDK sanitizes all user input before rendering. Chat messages are rendered as text, not HTML.

Billing

How is pricing calculated?

Check current pricing at produck.io/pricing (opens in a new tab). Typical factors:

Number of operations
API requests
Active sessions

Is there a free tier?

Yes! Check our pricing page for current free tier limits.

What happens if I exceed my plan limits?

Operations continue to work
You'll be notified via email
Graceful degradation (no sudden outages)
Upgrade prompts in dashboard

Troubleshooting

"SDK not initialized" error

Call await produck.init() before using SDK methods:

const produck = createProduck({ sdkKey: 'key' });
await produck.init(); // Don't forget this!
produck.register('action', handler);

Actions not triggering

Check operation ID spelling
Verify SDK key is correct
Check browser console for errors
Test trigger phrases in dashboard
Ensure handler is registered before testing

Chat widget not showing

Check ProduckProvider wraps your app
Verify ProduckChat component is rendered
Check z-index conflicts with your CSS
Look for console errors

TypeScript errors

Make sure you're importing types correctly:

import type { ActionPayload, ChatMessage } from '@produck/sdk';

Advanced

Can I customize the chat UI completely?

Yes! Use useProduckMessages() to build your own chat:

const { messages, sendMessage } = useProduckMessages();
// Build custom UI with messages and sendMessage

Can I trigger operations programmatically?

Not directly. Operations are matched through natural language. To programmatically execute code, just call your function directly:

// Instead of triggering operation programmatically
const openModal = () => {
  setModalOpen(true);
};
 
// Use it in both places
button.onclick = openModal; // Manual
useProduckAction('open-modal', openModal); // AI-triggered

Can I have conditional operations?

Yes! Register/unregister based on state:

useEffect(() => {
  if (userIsLoggedIn) {
    produck.register('view-dashboard', handler);
  } else {
    produck.unregister('view-dashboard');
  }
}, [userIsLoggedIn]);

Can operations pass parameters?

Yes, via actionConfig:

// In dashboard, configure operation with:
// actionConfig: { productId: "123" }
 
useProduckAction('show-product', (payload) => {
  const productId = payload.actionConfig.productId;
  showProduct(productId);
});

Can I use multiple SDK instances?

Yes, but rarely needed:

const produck1 = createProduck({ sdkKey: 'key1' });
const produck2 = createProduck({ sdkKey: 'key2' });
 
await produck1.init();
await produck2.init();

Still Have Questions?

Advanced Troubleshooting