Skip to main content

Common Questions

Installation & Configuration​

What's the difference between Widget and SDK?​

Comparison ItemVue 3 WidgetVue 3 SDK
Package Name@bdky/aaas-pilot-kit-vue3-widget@bdky/aaas-pilot-kit-vue3
PositioningReady-to-use UI component libraryUnderlying capability wrapper
UIBuilt-in complete UINo UI, needs self-implementation
FlexibilityStyle customizableCompletely free
Use CaseQuick integrationDeep customization

See Introduction Page for details.

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

No need. Widget already includes SDK dependencies and will install them automatically.

# Only need to install Widget
npm install @bdky/aaas-pilot-kit-vue3-widget

Which Vue versions are supported?​

Supports Vue 3.3+. Need to use Composition API.

Does it support SSR?​

Supports Nuxt and other SSR frameworks, but you need to note:

<script setup lang="ts">
import {defineAsyncComponent} from 'vue';

const PilotKit = defineAsyncComponent(() =>
    import('@bdky/aaas-pilot-kit-vue3-widget').then(mod => mod.PilotKit)
);
</script>

<template>
    <ClientOnly>
        <PilotKit v-bind="props" />
    </ClientOnly>
</template>

Initialization Issues​

Why does iOS Safari require manual activation?​

iOS Safari's security policy restricts automatically playing audio and using microphone in iframes. When this situation is detected, it triggers @needManualActivation event.

cloud-native mode doesn't need handling

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

Solution (standard mode): Use StartupScreen component:

<script setup lang="ts">
import {ref} from 'vue';
import {PilotKit, StartupScreen} from '@bdky/aaas-pilot-kit-vue3-widget';

const showStartup = ref(false);
</script>

<template>
    <PilotKit
        @needManualActivation="showStartup = true"
        v-bind="props"
    >
        <StartupScreen
            :show="showStartup"
            title="Start Conversation"
            buttonText="Activate"
            hintText="For better recognition results, please experience in a quiet environment"
            @ready="showStartup = false"
        />
    </PilotKit>
</template>

Why don't components display?​

Check the following points:

  1. PilotKit wrapper: All components must be used inside PilotKit
  2. Container height: Ensure parent container has explicit height
  3. Correct configuration: Check if token, figureId, ttsPer are correct
<template>
    <!-- ✅ Correct -->
    <div style="height: 100vh">
        <PilotKit token="..." figureId="..." ttsPer="...">
            <ConversationList />
        </PilotKit>
    </div>

    <!-- ❌ Error: Missing height -->
    <div>
        <PilotKit v-bind="props">
            <ConversationList />
        </PilotKit>
    </div>
</template>

When does @ready trigger?​

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

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

Interaction Issues​

How to send text messages?​

Method 1: Use ControlPanel's built-in input

<template>
    <ControlPanel defaultMode="text" />
</template>

Method 2: Use ref call

<script setup lang="ts">
import {ref} from 'vue';
import {PilotKit, type IPilotKitRef} from '@bdky/aaas-pilot-kit-vue3-widget';

const pilotKitRef = ref<IPilotKitRef | null>(null);

function sendMessage() {
    pilotKitRef.value?.input('Hello');
}
</script>

<template>
    <button @click="sendMessage">Send</button>
    <PilotKit ref="pilotKitRef" v-bind="props" />
</template>

Method 3: Use usePilotKitContext

<script setup lang="ts">
import {usePilotKitContext} from '@bdky/aaas-pilot-kit-vue3-widget';

const pilotKit = usePilotKitContext();

function sendMessage() {
    pilotKit?.input('Hello');
}
</script>

<template>
    <button @click="sendMessage">Send</button>
</template>

How to interrupt AI broadcasting?​

<script setup lang="ts">
import {ref} from 'vue';
import {usePilotKitContext, type IPilotKitRef} from '@bdky/aaas-pilot-kit-vue3-widget';

// Method 1: User speaks automatically interrupts (default on)

// Method 2: Use ref
const pilotKitRef = ref<IPilotKitRef | null>(null);
pilotKitRef.value?.interrupt();

// Method 3: Use usePilotKitContext
const pilotKit = usePilotKitContext();
pilotKit?.interrupt();
</script>

How to implement mute/unmute?​

<script setup lang="ts">
import {ref} from 'vue';
import {type IPilotKitRef} from '@bdky/aaas-pilot-kit-vue3-widget';

const pilotKitRef = ref<IPilotKitRef | null>(null);

// Mute
pilotKitRef.value?.mute(true);

// Unmute
pilotKitRef.value?.mute(false);

// Or use ControlPanel's built-in mute button
</script>

<template>
    <ControlPanel />
</template>

How to get conversation history?​

<script setup lang="ts">
import {usePilotKitContext} from '@bdky/aaas-pilot-kit-vue3-widget';

const {conversations} = usePilotKitContext() ?? {};
</script>

<template>
    <div>
        <div v-for="conv in conversations" :key="conv.id">
            {{ conv.text }}
        </div>
    </div>
</template>

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: class attribute

<template>
    <ControlPanel class="my-control-panel" />
</template>

<style>
.my-control-panel {
    margin-bottom: 20px;
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}
</style>

Method 3: style attribute

<template>
    <ControlPanel :style="{marginBottom: '20px'}" />
</template>

Method 4: default slot custom rendering

<template>
    <ControlPanel>
        <div class="my-control-panel">...</div>
    </ControlPanel>
</template>

See Style Customization for details.

How to adapt for mobile?​

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

<template>
    <!-- Force mobile style -->
    <ControlPanel variant="mobile" />

    <!-- Force desktop style -->
    <ConversationList variant="desktop" />
</template>

See Responsive Adaptation for details.

What if styles are overridden?​

Increase selector specificity:

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

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

/* Method 3: Vue scoped deep selector */
:deep(.apk-control-panel) {
    background: red;
}

Events & Callbacks​

Where are the event payload types defined?​

Event payload type definitions are in Vue 3 SDK, see Vue 3 SDK Composables.

How to listen to ASR recognition results?​

<script setup lang="ts">
function handleAsrMessage(payload: any) {
    console.log('Recognition result:', payload.text);
    console.log('Is final result:', payload.isFinal);
}
</script>

<template>
    <PilotKit
        @asrMessage="handleAsrMessage"
        v-bind="props"
    />
</template>

How to listen to conversation changes?​

<script setup lang="ts">
function handleConversationChange(payload: any) {
    console.log('Conversation list:', payload.conversations);
    console.log('Latest conversation:', payload.latestConversation);
}
</script>

<template>
    <PilotKit
        @conversationChange="handleConversationChange"
        v-bind="props"
    />
</template>

Performance Issues​

Does DebugPanel affect performance?​

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

<script setup lang="ts">
const isDev = import.meta.env.DEV;
</script>

<template>
    <DebugPanel :show="isDev" />
</template>

How to optimize performance of many conversations?​

  1. Limit display count:
<template>
    <ConversationList v-slot="{conversations}">
        <div>
            <Conversation
                v-for="conv in conversations.slice(-50)"
                :key="conv.id"
                :conversation="conv"
            />
        </div>
    </ConversationList>
</template>
  1. Use virtual scrolling (such as vue-virtual-scroller)

Other Issues​

How to integrate with Pinia?​

Sync state through event callbacks:

<script setup lang="ts">
import {useConversationStore} from '@/stores/conversation';

const store = useConversationStore();

function handleConversationChange(payload: any) {
    store.setConversations(payload.conversations);
}
</script>

<template>
    <PilotKit
        @conversationChange="handleConversationChange"
        v-bind="props"
    />
</template>

How to call methods outside component?​

Use ref:

// composables/usePilotKit.ts
import {ref} from 'vue';
import type {IPilotKitRef} from '@bdky/aaas-pilot-kit-vue3-widget';

export const pilotKitRef = ref<IPilotKitRef | null>(null);

export function sendMessage(text: string) {
    pilotKitRef.value?.input(text);
}
<script setup lang="ts">
import {pilotKitRef} from '@/composables/usePilotKit';
</script>

<template>
    <PilotKit ref="pilotKitRef" v-bind="props" />
</template>

Does Widget support TypeScript?​

Fully supported. Includes complete type definitions:

import type {
    IPilotKitProps,
    IPilotKitRef,
    VariantType
} from '@bdky/aaas-pilot-kit-vue3-widget';

How to report issues?​

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