Skip to main content

Frequently Asked Questions

Installation and Configuration​

What's the difference between Widget and SDK?​

Comparison ItemReact WidgetReact SDK
Package Name@bdky/aaas-pilot-kit-react-widget@bdky/aaas-pilot-kit-react
PositioningOut-of-the-box UI component libraryUnderlying capability encapsulation
UIBuilt-in complete UINo UI, implement yourself
FlexibilityStyle customizableCompletely free
Use CaseQuick integrationDeep customization

See introduction page for details.

Do I need to install SDK at the same time?​

No. Widget already includes SDK as a dependency and will install automatically.

# Just need to install Widget
npm install @bdky/aaas-pilot-kit-react-widget

Which React versions are supported?​

Supports React 16.8+ and React 19. Requires a version supporting Hooks.

Is SSR supported?​

Supports SSR frameworks like Next.js, but note:

// Use dynamic import to avoid SSR issues
import dynamic from 'next/dynamic';

const PilotKit = dynamic(
    () => import('@bdky/aaas-pilot-kit-react-widget').then(mod => mod.PilotKit),
    {ssr: false}
);

Initialization Issues​

Why does iOS Safari need manual activation?​

iOS Safari's security policy restricts automatic audio playback and microphone usage in iframes. When this is detected, the onNeedManualActivation event is triggered.

cloud-native mode doesn't require handling

If rendererMode is configured to 'cloud-native', you don't need to handle manual activation and can ignore this issue.

Solution (standard mode): Use StartupScreen component:

const [showStartup, setShowStartup] = useState(false);

<PilotKit
    onNeedManualActivation={() => setShowStartup(true)}
    {...props}
>
    <StartupScreen
        show={showStartup}
        onReady={() => setShowStartup(false)}
    />
</PilotKit>

Why isn't the component displaying?​

Check the following:

  1. PilotKit wrapper: All components must be used inside PilotKit
  2. Container height: Ensure parent container has explicit height
  3. Correct configuration: Check if appKey, appSecret, agentId are correct
// ✅ Correct
<div style={{height: '100vh'}}>
    <PilotKit appKey="..." appSecret="..." agentId="...">
        <ConversationList />
    </PilotKit>
</div>

// ❌ Error: Missing height
<div>
    <PilotKit {...props}>
        <ConversationList />
    </PilotKit>
</div>

When does onReady trigger?​

Triggers when SDK initialization completes and WebSocket connection succeeds. At this point you can:

  • Hide loading page
  • Start voice interaction
  • Call ref methods

Interaction Issues​

How to send text messages?​

Method 1: Use built-in input box in ControlPanel

<ControlPanel defaultMode="text" />

Method 2: Use ref call

const pilotKitRef = useRef(null);

<button onClick={() => pilotKitRef.current?.input('Hello')}>
    Send
</button>

<PilotKit ref={pilotKitRef} {...props} />

Method 3: Use usePilotKitContext

function SendButton() {
    const {input} = usePilotKitContext();
    return <button onClick={() => input('Hello')}>Send</button>;
}

How to interrupt AI broadcasting?​

// Method 1: User speaking automatically interrupts (default enabled)

// Method 2: Call interrupt method
pilotKitRef.current?.interrupt();

// Method 3: Use usePilotKitContext
const {interrupt} = usePilotKitContext();
interrupt();

How to implement mute/unmute?​

// Use ref
pilotKitRef.current?.setMuted(true);  // Mute
pilotKitRef.current?.setMuted(false); // Unmute

// Or use built-in mute button in ControlPanel
<ControlPanel />

How to get conversation history?​

function ConversationHistory() {
    const {conversations} = usePilotKitContext();

    return (
        <div>
            {conversations.map(conv => (
                <div key={conv.id}>{conv.text}</div>
            ))}
        </div>
    );
}

Style Issues​

How to modify component styles?​

Method 1: CSS class name override

.apk-control-panel {
    background: rgba(0, 0, 0, 0.8);
}

Method 2: className attribute

<ControlPanel className="my-control-panel" />

Method 3: style attribute

<ControlPanel style={{marginBottom: 20}} />

Method 4: children custom rendering

<ControlPanel>
    <div className="my-custom-panel">...</div>
</ControlPanel>

See Style Customization for details.

How to adapt for mobile?​

Components automatically adapt by default. If you need to force a specific mode:

// Force mobile styles
<ControlPanel variant="mobile" />

// Force desktop styles
<ConversationList variant="desktop" />

See Responsive Adaptation for details.

What if styles are being overridden?​

Increase selector priority:

/* Method 1: More specific selector */
.my-app .apk-control-panel {
    background: red;
}

/* Method 2: Use !important (use with caution) */
.apk-control-panel {
    background: red !important;
}

Events and Callbacks​

Where are event callback parameter types?​

Event payload type definitions are in React SDK, see React SDK Hooks for details.

How to listen to ASR recognition results?​

<PilotKit
    onAsrMessage={(payload) => {
        console.log('Recognition result:', payload.text);
        console.log('Is final result:', payload.isFinal);
    }}
    {...props}
/>

How to listen to conversation changes?​

<PilotKit
    onConversationChange={(payload) => {
        console.log('Conversation list:', payload.conversations);
        console.log('Latest conversation:', payload.latestConversation);
    }}
    {...props}
/>

Performance Issues​

Does DebugPanel affect performance?​

Yes, DebugPanel continuously monitors events. Recommend using only in development environment:

<DebugPanel show={process.env.NODE_ENV === 'development'} />

How to optimize performance with many conversations?​

  1. Limit display count:
<ConversationList>
    {({conversations}) => (
        <div>
            {conversations.slice(-50).map(conv => (
                <Conversation key={conv.id} conversation={conv} />
            ))}
        </div>
    )}
</ConversationList>
  1. Use virtual scrolling (like react-window)

Other Questions​

How to integrate with Redux/Zustand?​

Sync state through event callbacks:

import {useDispatch} from 'react-redux';

function App() {
    const dispatch = useDispatch();

    return (
        <PilotKit
            onConversationChange={(payload) => {
                dispatch(setConversations(payload.conversations));
            }}
            {...props}
        />
    );
}

How to call methods outside component?​

Use ref:

// Global ref
const pilotKitRef = createRef();

// Call from anywhere
function sendMessage(text) {
    pilotKitRef.current?.input(text);
}

Does Widget support TypeScript?​

Fully supports. Includes complete type definitions:

import type {
    PilotKitProps,
    PilotKitRef,
    Variant
} from '@bdky/aaas-pilot-kit-react-widget';

How to report issues?​

  1. Check console error information
  2. Use DebugPanel to view event logs
  3. Provide minimal reproducible example
  4. Contact technical support