billdogeng-capacitor

Capacitor engagement plugin for BillDog — analytics, surveys, in-app messaging, and remote feature flags for hybrid (Capacitor) apps.

It is a thin, idiomatic wrapper over the browser SDK @billdog.io/web. Engagement runs entirely inside the WebView, so there is no native iOS/Android bridge code to maintain — the same implementation serves iOS, Android, and the web.

This is the engagement sibling to @billdog.io/capacitor-in-app-billing (paywalls / in-app billing). The two are independent packages and can be installed side by side.

Install

npm install billdogeng-capacitor @billdog.io/web
npx cap sync

@billdog.io/web is a peer dependency — install it alongside this plugin.

Quick start

import { BillDogEngagement } from 'billdogeng-capacitor';

// Call once, client-side (e.g. in your app's bootstrap):
await BillDogEngagement.initialize({
  apiKey: 'bd_test_…',
  projectId: 'proj_123',
  environment: 'sandbox',
});

// Identity
await BillDogEngagement.identify('user_123', { email: '[email protected]' });
await BillDogEngagement.group('company', 'acme', { plan: 'pro' });

// Analytics
await BillDogEngagement.capture('level_completed', { level: 7 });

// Surveys
const survey = await BillDogEngagement.fetchSurvey('post_purchase_nps');
const available = await BillDogEngagement.listSurveys();
await BillDogEngagement.submitSurvey({
  surveyId: 'post_purchase_nps',
  answers: [{ question_id: 'q1', answer_number: 9 }],
});

// In-app messaging (server decides what to show for the placement)
await BillDogEngagement.presentMessage({ placementId: 'home_promo' });

// Feature flags — REMOTE / server-authoritative
await BillDogEngagement.reloadFeatureFlags();
const variant = BillDogEngagement.getFeatureFlag('new_onboarding'); // string | boolean
if (BillDogEngagement.isFeatureEnabled('new_onboarding')) {
  const payload = BillDogEngagement.getFeatureFlagPayload('new_onboarding');
}

API

| Method | Description | | --- | --- | | initialize(config) | Configure the underlying @billdog.io/web client. Call once, client-side. | | isInitialized() | Whether initialize() has completed. | | identify(userId, options?) | Associate the session with an app user id (+ attributes/email/phone). | | group(type, key, props?) | Associate the user/session with a group. | | capture(event, props?) | Capture a custom analytics event. | | fetchSurvey(id) | Fetch a single survey configuration. | | listSurveys() | List surveys available to the current respondent. | | submitSurvey({ surveyId, answers, context?, respondentId? }) | Submit survey answers. | | presentMessage({ placementId }) | Trigger an in-app message for a placement. | | reloadFeatureFlags() | Reload remote feature flags for the current identity. | | getFeatureFlag(key) | Read a remote flag value (string variant or boolean). | | isFeatureEnabled(key) | Convenience boolean read. | | getFeatureFlagPayload(key) | Read the JSON payload attached to a flag variant. |

Feature flags are remote

This plugin never evaluates flags locally — no bucketing, no hashing, no audience evaluation. It only reads values the BillDog backend has already evaluated for the current identity. Call reloadFeatureFlags() after identity changes to refresh.

SSR / registration safety

Importing the package and constructing the BillDogEngagement singleton does not touch window/document. The first browser access happens inside initialize(), which throws if no browser environment is present. This makes the package safe to import during SSR or Capacitor plugin registration.

Development

npm install
npm run build       # tsc + rollup
npm run typecheck   # tsc --noEmit
npm test            # vitest

License

MIT