PilotKit

Core container component, integrates Provider and Digital Human rendering, is the root component of all Widget components.

Basic Usage

import {PilotKit, ControlPanel} from '@bdky/aaas-pilot-kit-react-widget';
import '@bdky/aaas-pilot-kit-react-widget/styles.css';

function App() {
    return (
        <PilotKit
            token="your-token"
            figureId="your-figure-id"
            ttsPer="your-tts-per"
            agentConfig={{
                robotId: 'your-robot-id'
            }}
        >
            <ControlPanel />
        </PilotKit>
    );
}

Using Ref

Through ref you can access controller methods:

import {useRef} from 'react';
import {PilotKit, type IPilotKitRef} from '@bdky/aaas-pilot-kit-react-widget';
import '@bdky/aaas-pilot-kit-react-widget/styles.css';

function App() {
    const pilotKitRef = useRef<IPilotKitRef>(null);

    const handleSendMessage = () => {
        pilotKitRef.current?.input('Hello');
    };

    const handleInterrupt = () => {
        pilotKitRef.current?.interrupt();
    };

    return (
        <PilotKit ref={pilotKitRef} {...props}>
            <button onClick={handleSendMessage}>Send Message</button>
            <button onClick={handleInterrupt}>Interrupt</button>
        </PilotKit>
    );
}

Props

Required Properties

Property	Type	Description
token	string	Authentication Token
figureId	string	Digital Human image ID
ttsPer	string	TTS voice ID

Agent Configuration

Property	Type	Description
agentConfig	{robotId: string; token?: string}	Agent configuration, one of agentService
agentService	typeof BaseAgentService	Custom AgentService class

agentConfig vs agentService

• Use Baidu default Agent: Configure agentConfig
• Use private Agent API: Provide custom agentService, see Custom AgentService

Behavior Configuration

Property	Type	Default Value	Description
prologue	string	-	Opening remarks, automatically broadcast after SDK ready
interruptible	boolean	false	Whether to allow interruption of broadcasting
timeoutSec	number	120	No operation timeout (seconds)
typeDelay	number	100	Chinese typewriter effect delay (ms)
enTypeDelay	number	50	English typewriter effect delay (ms)
minSplitLen	number	10	Streaming text minimum split length

Rendering Configuration

Property	Type	Default Value	Description
rendererMode	'cloud-native' | 'standard'	'standard'	Rendering mode
scaleX	number	1	Horizontal scale
scaleY	number	1	Vertical scale
translateX	number	0	Horizontal offset
translateY	number	0	Vertical offset

Internationalization Configuration

Property	Type	Default Value	Description
locale	string	'zh'	UI interface language (v1.1.2+)
messages	Partial<I18nMessages>	-	Custom translation messages (v1.1.2+)

For detailed configuration, see Internationalization (i18n)

Style Properties

Property	Type	Description
className	string	Custom class name
style	CSSProperties	Custom style
backgroundUrl	string	Background image URL
autoMount	boolean	Whether to automatically mount, default true

Event Callbacks

Property	Type	Description
onReady	() => void	SDK ready
onNeedManualActivation	() => void	Needs manual activation (iOS iframe)
onAsrStart	() => void	ASR starts
onAsrMessage	(payload) => void	ASR recognition result
onRenderStart	(payload) => void	Start broadcasting
onInactivity	(payload) => void	User inactivity timeout
onBusy	(payload) => void	System busy
onInterrupt	(payload) => void	Broadcasting interrupted
onConversationChange	(payload) => void	Conversation content changes
onIsRenderingChange	(isRendering) => void	Broadcasting state changes
onReplyStart	(payload) => void	Reply starts
onTtft	(payload) => void	First character latency metric

Event Payload Types

Event callback Payload type definitions are in React SDK Hooks documentation.

Ref Methods

Through ref you can access the following methods:

Method	Type	Description
input	(text: string) => void	Send text input
mute	(muted: boolean) => void	Set mute state
interrupt	() => void	Interrupt current broadcasting
dispose	() => void	Destroy instance
playPrologue	() => void	Broadcast opening remarks
playFromFullText	(text: string) => void	Broadcast complete text
playFromStreamText	(text: string) => void	Stream broadcast text
keepAlive	() => void	Keep connection active
checkAudioDevice	() => Promise<Result>	Check audio device
activateManually	() => Promise<void>	Manual activation (iOS)
getIsReady	() => boolean	Get ready state
getIsMuted	() => boolean	Get mute state
getIsRendering	() => boolean	Get broadcasting state

Context

PilotKit creates PilotKitContext internally, child components can access via usePilotKitContext:

import {usePilotKitContext} from '@bdky/aaas-pilot-kit-react-widget';
import '@bdky/aaas-pilot-kit-react-widget/styles.css';

function ChildComponent() {
    const pilotKit = usePilotKitContext();

    return (
        <button onClick={() => pilotKit?.input('Hello')}>
            Send Message
        </button>
    );
}

Style Customization

CSS Class Names

Class Name	Description
.apk-pilot-kit	Root container
.apk-pilot-kit__mask	Mask layer (children rendering position)

Background Image

Use backgroundUrl to set background:

<PilotKit
    backgroundUrl="https://example.com/background.jpg"
    // ...
>

Related

• React SDK Provider - Underlying Provider documentation
• Configuration Options - Complete configuration options reference