billdogeng-vue

billdogeng-vue

The BillDog engagement suite for Vue 3 — a thin, idiomatic, SSR-safe wrapper over the existing browser SDKs (@billdog.io/web, @billdog.io/analytics, @billdog.io/survey-core).

It surfaces, the Vue way (a plugin + composables + a component):

• init — createBilldog() plugin (or <BilldogProvider> / useProvideBilldog)
• analytics — capture / identify / group via useBilldog()
• surveys — fetch / list / submit + a render component (useSurvey, <Survey/>)
• in-app messaging — useBilldog().showInAppMessages()
• feature flags — remote / server-authoritative via useFeatureFlag()

Feature flags are remote. All targeting is evaluated on the BillDog backend. This package performs no local bucketing and contains no murmurhash — that is forbidden by the BillDog architecture. useFeatureFlag simply reads the value the backend already decided and cached.

Install

npm install billdogeng-vue @billdog.io/web @billdog.io/analytics @billdog.io/survey-core

The three @billdog.io/* packages are optional peer dependencies — install the ones whose features you use. vue (>=3.3) is a required peer.

Quick start (plugin)

import { createApp } from 'vue';
import { createBilldog } from 'billdogeng-vue';
import App from './App.vue';

const app = createApp(App);
app.use(
  createBilldog({
    apiKey: 'bd_live_xxx',
    projectId: 'proj_123',
    // anonymousId?, autoloadFeatureFlags? (default true)
  }),
);
app.mount('#app');

Scoped alternative — <BilldogProvider>

<script setup lang="ts">
import { BilldogProvider } from 'billdogeng-vue';
const config = { apiKey: 'bd_live_xxx', projectId: 'proj_123' };
</script>

<template>
  <BilldogProvider :config="config">
    <App />
  </BilldogProvider>
</template>

Analytics

<script setup lang="ts">
import { useBilldog } from 'billdogeng-vue';
const { capture, identify, group, showInAppMessages } = useBilldog();

identify('user_42', { plan: 'pro' });
group('company', 'acme', { seats: 5 });
capture('page_view', { path: '/home' });

// in-app messaging trigger
showInAppMessages('home_banner');
</script>

identify(userId, traits) logs the user in: @billdog.io/web switches to that customer (flags, surveys, purchases) and the traits go to the @billdog.io/analytics profile. reset() logs out: the SDK stays configured and continues as a new guest.

Feature flags (remote)

<script setup lang="ts">
import { useFeatureFlag } from 'billdogeng-vue';

// boolean on/off flag
const newCheckout = useFeatureFlag('new-checkout', false);
// multivariate (string variant)
const theme = useFeatureFlag('theme', 'classic');
</script>

<template>
  <CheckoutV2 v-if="newCheckout" />
  <CheckoutV1 v-else />
</template>

The returned ref re-evaluates automatically whenever the SDK re-fetches flags from the backend.

Surveys

Component

<script setup lang="ts">
import { Survey } from 'billdogeng-vue';
</script>

<template>
  <Survey
    survey-id="svy_nps"
    @submit="(result, answers) => console.log(result, answers)"
    @error="(e) => console.error(e)"
  />
</template>

Custom rendering (scoped slot)

<Survey survey-id="svy_nps" v-slot="{ survey, loading, setAnswer, submit }">
  <p v-if="loading">Loading…</p>
  <form v-else-if="survey" @submit.prevent="submit">
    <!-- drive the form yourself with `setAnswer(questionId, { ... })` -->
  </form>
</Survey>

Composable

import { useSurvey } from 'billdogeng-vue';

const { survey, loading, error, submit, refetch } = useSurvey('svy_nps');
await submit([{ question_id: 'q1', answer_choices: ['great'] }]);

SSR (Nuxt / Vite SSR)

The package is SSR-safe out of the box:

• The engagement client is only instantiated in the browser (onMounted, plus a typeof window guard in the plugin).
• Importing the package on the server never touches window/document; the underlying browser SDKs are loaded with dynamic import() only on the client.
• During server render, useBilldog().ready is false, useFeatureFlag returns its default, and surveys do not fetch — everything activates on the client after hydration.

For Nuxt, register the plugin in a client plugin file (plugins/billdog.client.ts) so it only runs in the browser:

// plugins/billdog.client.ts
import { createBilldog } from 'billdogeng-vue';

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(
    createBilldog({ apiKey: 'bd_live_xxx', projectId: 'proj_123' }),
  );
});

BillDog Auth

This package does not wrap BillDog Auth, and does not need to: @billdog.io/auth is framework-agnostic and runs alongside it. It holds the session token in memory, refreshes it for you, and exposes authHeaders() for your own API calls.

License

MIT