billdogeng-svelte

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

It surfaces everything the engagement suite offers the Svelte way — context + stores + components:

• Analytics — capture, identify, group
• Surveys — fetch, render (<Survey/>), and submit (survey() store)
• In-app messaging — trigger placements
• Feature flags — remote / server-authoritative (featureFlag() store)

Feature flags are evaluated on the BillDog backend. This package does no local bucketing and contains no murmurhash — targeting is server-side only.

Install

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

svelte is a peer dependency (Svelte 4 or 5). The three BillDog browser SDKs are optional peers — install the ones whose features you use.

Quickstart

Wrap your app in +layout.svelte:

<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import { BilldogProvider } from 'billdogeng-svelte';
  import { PUBLIC_BILLDOG_API_KEY, PUBLIC_BILLDOG_PROJECT_ID } from '$env/static/public';

  let { children } = $props();
</script>

<BilldogProvider
  config={{
    apiKey: PUBLIC_BILLDOG_API_KEY,
    projectId: PUBLIC_BILLDOG_PROJECT_ID,
    customerId: 'user_42' // optional; or call identify() later
  }}
>
  {@render children()}
</BilldogProvider>

BilldogProvider is SSR-safe: the engagement client is created inside onMount, so it never runs during server render and never touches window/document on the server. You can safely import this package in server-rendered routes — nothing initialises until the browser.

Analytics

<script lang="ts">
  import { useBilldog } from 'billdogeng-svelte';

  const bd = useBilldog();

  function buy() {
    bd.identify('user_42', { plan: 'pro' });
    bd.group('company', 'acme', { seats: 12 });
    bd.capture('checkout_started', { value: 49.0 });
  }
</script>

<button onclick={buy}>Buy</button>

Feature flags (remote)

<script lang="ts">
  import { featureFlag } from 'billdogeng-svelte';

  const newBanner = featureFlag('new-banner', false); // boolean store
  const theme = featureFlag('home-theme', 'classic');  // string variant store
</script>

{#if $newBanner}
  <div class="banner banner--{$theme}">Welcome!</div>
{/if}

featureFlag() returns a Svelte readable store holding the value cached from the backend's flag-evaluation response. It re-emits automatically whenever the SDK re-evaluates flags.

Surveys

Drop-in component:

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

<Survey
  surveyId="svy_nps"
  onsubmit={(result) => console.log('submitted', result.responseId)}
/>

Or build your own UI with the store + render snippet:

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

<Survey surveyId="svy_nps">
  {#snippet children(state)}
    {#if state.survey}
      <button onclick={() => state.submit()}>Rate — {state.survey.name}</button>
    {/if}
  {/snippet}
</Survey>

Or use the bare store directly:

<script lang="ts">
  import { survey } from 'billdogeng-svelte';

  const nps = survey('svy_nps');

  function rate9() {
    nps.submit([{ question_id: 'q1', answer_number: 9 }]);
  }
</script>

{#if $nps.survey}
  <button onclick={rate9}>Rate 9 — {$nps.survey.name}</button>
{/if}

In-app messaging

<script lang="ts">
  import { useBilldog } from 'billdogeng-svelte';
  const bd = useBilldog();
</script>

<button onclick={() => bd.showInAppMessages('help-center')}>Help</button>

API

| Export | Kind | Purpose | | --- | --- | --- | | BilldogProvider | component | Init + context root (SSR-safe). | | useBilldog() | fn → object | { client, ready, capture, identify, group, reset, showInAppMessages, reloadFeatureFlags }. | | featureFlag(key, default) | fn → store | Remote flag value (boolean or string variant) as a readable store. | | survey(surveyId) | fn → store | { survey, loading, error } store + submit / refetch. | | <Survey surveyId /> | component | Fetch + render + submit a survey. | | createBilldogClient(config, deps?) | fn | Low-level client builder (advanced). | | getBilldogContext() | fn | Raw context stores (advanced). |

useBilldog, featureFlag, and survey read Svelte context — call them during component initialisation (top of <script>), under a BilldogProvider.

License

MIT