Skip to main content

billdog_flutter 1.1.2-beta.5 copy "billdog_flutter: ^1.1.2-beta.5" to clipboard
billdog_flutter: ^1.1.2-beta.5 copied to clipboard

BillDog SDK for Flutter — monetization, paywalls, subscriptions and BillDog Auth sign-in. Thin bridge over the native iOS/Android SDKs with inline native paywall rendering.

BillDog Flutter SDK #

Monetization, paywalls, and subscription management for Flutter apps. A thin bridge over the native BillDog iOS and Android SDKs: hosted paywalls render natively, and headless reads return the offering for your own UI.

Installation #

dependencies:
  billdog_flutter: ^1.1.2-beta.5
flutter pub get

iOS: set the deployment target to 15.0 #

The plugin requires iOS 15.0, but Flutter's default app template targets 13.0. Without this step the iOS build fails at pod install with:

Error: The plugin "billdog_flutter" requires a higher minimum iOS deployment
version than your application is targeting.

Uncomment (or add) the platform line at the top of ios/Podfile:

platform :ios, '15.0'

then run cd ios && pod install. Also set iOS Deployment Target to 15.0 for the Runner target in Xcode, so the app and the pods agree.

On Flutter 3.24+ with Swift Package Manager enabled (the default in recent versions), the plugin resolves through SPM and no Podfile is generated — but the 15.0 minimum still applies to the Runner target.

Quick Start #

import 'package:billdog_flutter/billdog_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await BillDog.configure(
    'bd_live_your_api_key',
    options: BillDogOptions(enableLogging: true),
  );

  runApp(MyApp());
}

Presenting a Paywall #

// Present a paywall configured for a placement
BillDog.shared.registerPlacement(
  'onboarding_end',
  handler: PaywallPresentationHandler(
    onPresent: (info) => print('Paywall shown: ${info.identifier}'),
    onDismiss: (info) => print('Paywall dismissed'),
    onSkipped: (reason) => print('Nothing shown: ${reason.name}'),
    // Keep the paywall open after a purchase (honoured on iOS; Android closes it).
    onPurchaseSuccess: (productId) => PostPurchaseBehavior.keepOpen,
  ),
);

The handler hears each callback as it happens. onPurchaseSuccess is answered within 2 seconds, or the paywall closes.

Inline Widget #

PaywallView(
  identifier: 'premium_offer',
  onPurchase: (productId, data) {
    print('Purchase requested: $productId');
  },
  onDismiss: () => Navigator.pop(context),
  loadingWidget: Center(child: CircularProgressIndicator()),
)

Headless: your own paywall UI #

Ask the server what to sell, draw it yourself, and buy through BillDog. No paywall is downloaded or presented.

final result = await BillDog.shared.getOffering('onboarding');

switch (result) {
  case OfferingAvailable(:final offering):
    showMyPaywall(offering);
  case OfferingHoldout():
    // This user is in the holdout group: show no paywall.
    continueWithoutPaywall();
  case OfferingWithheld(:final gated):
    // The placement's content was withheld from this user. If the placement
    // gates a feature (`gated`), keep the feature closed.
    gated ? keepFeatureClosed() : continueWithoutPaywall();
  case OfferingNotConfigured():
    continueWithoutPaywall();
  case OfferingFailed(:final error):
    report(error);
}

getOffering and getOfferings are instance methods (BillDog.shared). They never throw, and never hand you a different offering in place of an answer they did not get.

Every outcome carries what the server said about the placement: placementInfo (id, display name, description, metadata), presentation (gated, holdout, withheld, withheldReason), experiment (experimentId, variantId, variantName) and campaign (id, name, audience). A holdout still names its experiment, so you can log the arm you did not show.

if (result.experiment case final experiment?) {
  analytics.log('arm', experiment.variantName ?? experiment.variantId);
}

Typed failures #

Every server refusal reaches Dart as its own BillDogError, whatever the call: ProofRequiredError, ProofInvalidError, ReauthRequiredError, AccessDeniedError (isTargetMismatch), PurchaseOwnerConflictError, PlacementAccessWithheldError and PlacementNotFoundError, each with its wire code and the server's reason. Local native failures arrive by category (NetworkError, StoreError, ConfigurationError, ...). A paywall asked for while another is on screen or still opening is refused, and nothing on screen changes: register returns a PlacementError with PaywallAlreadyPresentedError (code PAYWALL_ALREADY_PRESENTED). OfferingFailed, Failed, RestoreFailed, PlacementError, PresentError and WebCheckoutResult.failure all carry one; getCustomerInfo, getPaywall, identify and hasAccessForPlacement throw one.

The delegate's onPurchaseFailed(productId, BillDogError error) is typed too, and onWebCheckoutRedeemed(RedemptionOutcome) reports what became of a web checkout's return link, including a RedemptionRefused the server would not credit until the caller has proof.

// The project's default offering, and every offering returned with it.
final result = await BillDog.shared.getOfferings();

// Buy a package (StoreKit / Play Billing through the native SDK).
final purchase = await BillDog.shared.purchasePackage(offering.packages.first);
switch (purchase) {
  case Purchased() || Restored(): unlock();
  case Cancelled() || Pending(): break;
  case Failed(:final error): report(error);
}

// Report your own paywall's impressions. No paywall id is sent.
await BillDog.shared.trackPaywallPresented(offering: offering, placement: 'onboarding');
await BillDog.shared.trackPaywallDismissed(offering: offering, placement: 'onboarding');

purchasePackage buys the native SDK's own copy of the package: the purchase is attributed to the package's offering and placement (Package.presentedOfferingContext), and the promotional or Play offer the dashboard pins on the package applies. On Android purchase buys the product's default offer. The Flutter bridge does not select a base plan or offer otherwise.

Server refusals #

A request the server refuses arrives as a typed error (OfferingFailed.error, Failed.error):

Error Wire code Meaning
ProofRequiredError PROOF_REQUIRED The request needed a session or device proof and carried none
ProofInvalidError PROOF_INVALID The proof was malformed, expired or unknown
ReauthRequiredError REAUTH_REQUIRED The sign-in is too old for a sensitive action; sign in again
AccessDeniedError ACCESS_DENIED isTargetMismatch: the request named another customer
PurchaseOwnerConflictError PURCHASE_OWNER_CONFLICT The store purchase belongs to another customer
PlacementNotFoundError PLACEMENT_NOT_FOUND No placement has this identifier (usually a typo)

The device proof is created, stored and sent by the native SDKs. Dart never sees the device key.

Web checkout #

final result = await BillDog.shared.purchaseViaWeb('com.app.pro.monthly');
// completed: redeemed already (iOS).
// opened:    checkout is open in the browser (Android); it finishes on the
//            return link.

// Give the app's incoming links to BillDog:
final redeemed = await BillDog.shared.completeWebCheckout(uri); // waits for redemption
// or, without waiting:
final handled = await BillDog.shared.handleDeepLink(uri);

<scheme>://checkout/success, <scheme>://checkout/cancel and <scheme>://redeem are BillDog's links. The scheme is the app's own, <bundle id>.billdog on iOS and <applicationId>.billdog on Android (BillDogOptions.customUrlScheme to choose another): register it in CFBundleURLTypes and on the main activity's intent filter. The old shared billdog:// let another BillDog-powered app on the phone receive the link; an app that still registers only billdog keeps working until it adds its own. The native SDK redeems the token, refreshes customer info and dismisses the paywall.

Superwall #

billdog_superwall is an optional package: Superwall presents paywalls, BillDog performs every purchase and restore. billdog_flutter itself does not depend on Superwall.

dependencies:
  billdog_flutter: 1.1.2-beta.5
  billdog_superwall: 1.1.2-beta.5   # the same version as billdog_flutter
  superwallkit_flutter: ^2.6.0
import 'package:billdog_superwall/billdog_superwall.dart';
import 'package:superwallkit_flutter/superwallkit_flutter.dart' as sw;

await BillDog.configure('bd_public_...');
final controller = SuperwallBillDogPurchaseController();
sw.Superwall.configure('pk_...', purchaseController: controller);
controller.startSyncingSubscriptionStatus();

Forward SuperwallDelegate.handleCustomPaywallAction(name) to controller.handleCustomPaywallAction(name) to start BillDog web checkout from a billdog_web_checkout:<productId> paywall action, and the app's incoming links to controller.handleDeepLink(uri).

RevenueCat #

integrations/billdog_revenuecat is an optional package for apps that keep RevenueCat for purchases and use BillDog for paywalls and analytics. RevenueCat makes, finishes and acknowledges every purchase; BillDog records each one from the store's evidence and grants access from its own ledger (it never reads RevenueCat's entitlements). Same behaviour as the native BillDogRevenueCatIntegration (iOS) and billdog-integration-revenuecat (Android). billdog_flutter itself does not depend on purchases_flutter.

billdog_revenuecat isn't on pub.dev yet. It will be published at the same version as billdog_flutter once its device testing is done; the API below is the one it will ship with.

dependencies:
  billdog_flutter: 1.1.2-beta.5
  billdog_revenuecat: 1.1.2-beta.5        # once published
  purchases_flutter: '>=10.1.0 <12.0.0'
import 'package:billdog_revenuecat/billdog_revenuecat.dart';
import 'package:purchases_flutter/purchases_flutter.dart';

await Purchases.configure(PurchasesConfiguration('appl_...'));
// INSTEAD of BillDog.configure:
final connection = await BillDogRevenueCat.configure(
  'bd_public_...',
  // storeKitVersion: HostStoreKitVersion.storeKit1,  // only if RevenueCat uses StoreKit 1
  // restoreOnLaunch: true,                           // record RevenueCat customer info at launch
);
  • Paywall purchases and restores run through RevenueCat. iOS: BillDog records StoreKit's transaction id. Android: purchases_flutter exposes no Play purchase token, so BillDog finds the purchase in Play by its order id (or records it from its Play listener or next sweep).
  • Consumables: with RevenueCat's default completion mode, RevenueCat finishes (iOS) or consumes (Android) each purchase at once, and a finished consumable is gone from the device's store history, so BillDog may not record it. Configure RevenueCat with purchasesAreCompletedBy: myApp (before BillDogRevenueCat.configure): BillDog's native SDK then records each purchase while it is unfinished and finishes, acknowledges or consumes it itself, on both platforms and every iOS version. BillDog finishes only the bridge's purchases.
  • Every RevenueCat customer-info update asks BillDog to sweep the store. restoreOnLaunch only reads RevenueCat's customer info: it never restores (an App Store sign-in prompt) or syncs (which can alias app user ids).
  • identify / logIn and reset / logOut log RevenueCat in and out (a controller's setIdentity, called after native accepts).
  • Capabilities: Apple's 12-month commitment plans on iOS (purchases_flutter 10.16 or later, iOS 26.4 or later); Play upgrades on Android. A promotional offer is dropped on iOS, and quantity and win-back offers fail.

Identity Management #

// After login
BillDog.shared.identify('user_123');

// Set attributes for targeting
BillDog.shared.setUserAttributes({
  'plan': 'free',
  'signup_date': '2024-01-15',
});

// On logout
BillDog.shared.reset();

Custom Purchase Handling #

If your app buys through its own code (in_app_purchase, RevenueCat, …), register a PurchaseController. BillDog's paywalls then call it, and BillDog never finishes or acknowledges a transaction: your code does.

Return the purchase's store evidence from purchase so BillDog records it at once. Without evidence BillDog derives it from the store, or records the purchase at its next sweep.

class MyPurchaseController extends PurchaseController {
  @override
  Set<PurchaseCapability> get capabilities => {PurchaseCapability.upgrades};

  // in_app_purchase uses StoreKit 1 unless you opted into StoreKit 2.
  @override
  HostStoreKitVersion get storeKitVersion => HostStoreKitVersion.storeKit1;

  @override
  Future<PurchaseOutcome> purchase(PurchaseRequest request) async {
    final details = await myStore.buy(
      request.productId,
      // Optional: binds the store purchase to this customer.
      accountToken: request.storeAccountToken,
    );
    final evidence = StoreEvidence.fromInAppPurchase(details);
    return PurchaseOutcome(
      Purchased(transactionId: details.purchaseID ?? '', productId: request.productId),
      evidence: [if (evidence != null) evidence],
    );
  }

  @override
  Future<RestoreOutcome> restore() async {
    final restored = await myStore.restore();
    return RestoreOutcome(
      RestoredItems(restored.map((d) => RestoredItem(productId: d.productID, transactionId: d.purchaseID ?? '')).toList()),
      evidence: restored.map(StoreEvidence.fromInAppPurchase).whereType<StoreEvidence>().toList(),
    );
  }

  // The per-store methods are only used when `purchase`/`restore` are not overridden.
  @override
  Future<PurchaseResult> purchaseFromAppStore(String productId) => throw UnimplementedError();
  @override
  Future<PurchaseResult> purchaseFromGooglePlay(String productId, {String? basePlanId, String? offerId}) =>
      throw UnimplementedError();
  @override
  Future<RestoreResult> restorePurchases() => throw UnimplementedError();
}

await BillDog.configure(
  'bd_live_your_api_key',
  purchaseController: MyPurchaseController(),
);

A paywall purchase that needs a capability your controller does not declare (a quantity above 1, a win-back offer, a Google Play upgrade) fails with a configuration error instead of buying something else. A purchase your controller does not answer within five minutes, or one in flight when the Flutter engine goes away, is reported Pending, never failed: BillDog records it when the store reports it.

Recording purchases your code makes outside a paywall #

// Record it and read what the server did:
final recording = await BillDog.shared.recordPurchase(StoreEvidence.fromInAppPurchase(details)!);
if (recording.status == PurchaseRecordingStatus.rejected) { /* never shown as success */ }

// Or observe it (analytics + recording):
await BillDog.shared.observePurchaseResult(details.productID, evidence: StoreEvidence.fromInAppPurchase(details));

// Backstop sweep, never prompts:
final held = await BillDog.shared.syncStorePurchases();

// Purchases BillDog could not record:
final issues = await BillDog.shared.purchaseRecordingIssues();

StoreEvidence.fromInAppPurchase maps a StoreKit 1 restored transaction to the original transaction's id, which is the id that names the purchase. You can also build evidence directly with StoreEvidence.appStore(transactionId: …) or StoreEvidence.googlePlay(purchaseToken: …, productIds: […]). A Google Play order id alone is never evidence: pass the purchase token.

Subscription Status #

// Check status
if (BillDog.shared.subscriptionStatus.hasAccess) {
  // User is subscribed
}

// Manually set (when using custom purchase controller)
BillDog.shared.subscriptionStatus = SubscriptionStatus.active({});

Customer Info #

final info = await BillDog.shared.getCustomerInfo();

if (info.hasEntitlement('premium')) {
  // Unlock premium features
}

Analytics #

BillDog.shared.trackEvent('level_completed', properties: {
  'level': 5,
  'score': 1200,
});

BillDog Auth #

Sign-in, sessions and second factors. The plugin delegates to the native SDKs rather than reimplementing them, so the refresh token lives in the iOS Keychain and Android EncryptedSharedPreferences — never in shared_preferences, which is plain text on disk.

Requires native binaries 1.1.2-beta.5. Auth is absent from the published beta.2 iOS XCFramework (released 2026-08-08, before the module was written), and io.billdog:billdog-auth does not exist on Maven Central before beta.3.

import 'package:billdog_flutter/billdog_flutter.dart';

final auth = BillDogAuth.instance;

await auth.restore();   // AuthRestoreResult(signedIn: false) on first launch

final r = await auth.attempt(
  identifier: 'ada@example.com',
  strategy: 'password',
  password: password,
);

// Check this BEFORE treating it as a sign-in: against an enrolled account a
// correct password issues no session.
if (r.mfaRequired) {
  await auth.attempt(
    identifier: 'ada@example.com',
    strategy: 'totp',
    code: code,
    mfaToken: r.mfaToken,   // proves the first factor was accepted
  );
  // The token is single-use, and a WRONG code spends it too: on a failure,
  // start again from the first factor rather than re-prompting on it.
}

Passwordless, and phone numbers #

// A RETURNING user gets a fresh code from requestCode. Without it a code could
// only be obtained as a side effect of signing up.
await auth.requestCode(identifier: '+15551234567', kind: 'phone');

await auth.attempt(
  identifier: '+15551234567',
  kind: 'phone',          // REQUIRED — selects the identity row
  strategy: 'sms_code',
  code: code,
);

kind defaults to 'email'. A phone sign-in that leaves it at the default looks a phone number up among email addresses and silently matches nothing.

Sessions, account and second factors #

final sessions = await auth.activeSessions();   // this device's has isCurrent
await auth.signOut(scope: 'others');            // end the rest

final account = await auth.account();           // identifiers, mfaEnabled, org

final e = await auth.enrolTotp(issuer: 'My App'); // secret + otpauth:// URI, ONCE
final backupCodes = await auth.confirmFactor(factorId: e.factorId, code: code);

listFactors() · removeFactor(id) · regenerateBackupCodes() — the last two are refused unless the second factor was proved in the last five minutes.

The rest of the surface #

isSignedIn() · hasStoredSession() (launch check: isSignedIn() stays false until restore()) · config() · signUp(...) (with invitationToken / captchaToken when config() says they are required) · signOut(scope: 'this' | 'others' | 'all') · requestPasswordReset(...) · resetPassword(...) · changePassword(...) · deleteAccount() · passkeysAvailable() · registerPasskey() · signInWithPasskey() · BillDogOrganizations — create, list, members, roles, invitations, domains.

Strategies are password, email_code, sms_code, totp, backup_code.

Routing through a proxy #

await BillDog.setProxyURL('https://api.example.com/billdog'); // before configure
await BillDog.configure('bd_public_…');

/v1 is added unless the URL already ends in it; null clears it.

By default the proxy gets no customer proof (the BillDog Auth session, the device key), so customer-scoped calls — deleteAccount() among them — answer ProofRequiredError behind it. For a proxy you run that forwards to BillDog:

await BillDog.setProxyURL('https://api.example.com/billdog', trustedForProofs: true);

The proofs then go to exactly that scheme, host and port. https only (plain http just for a loopback/private host in a debug build); setting the proxy again without the flag, or clearing it, withdraws the trust.

Deleting an account #

try {
  final deleted = await BillDogAuth.instance.deleteAccount();
} on ReauthRequiredError {
  // The sign-in is too old for this. Sign the user in again, then retry.
} on ProofRequiredError {
  // Nobody is signed in.
}

Architecture #

The Flutter SDK follows a thin bridge architecture. The bridge is one hand-written MethodChannel (io.billdog.flutter/sdk, plus billdog for analytics and a per-view channel for PaywallView); nothing is generated. Both plugins answer every method with the same map shapes, and a test (billdog_channel_parity_test.dart) fails when Dart invokes a method either plugin does not handle.

┌─────────────────────────────────┐
│         Flutter (Dart)          │
│  BillDog.shared / PaywallView   │
│         MethodChannel           │
├─────────────────────────────────┤
│    iOS: BillDogFlutterPlugin    │
│    → Delegates to BillDog SDK   │
├─────────────────────────────────┤
│  Android: BillDogFlutterPlugin  │
│    → Delegates to BillDog SDK   │
└─────────────────────────────────┘

Hosted paywalls are rendered by the native SDK (full-screen through registerPlacement, inline through PaywallView). Journey actions are fetched and executed by the native SDK; Dart does not poll for them.

Requirements #

  • Flutter >= 3.10.0
  • Dart >= 3.0.0
  • iOS >= 15.0 — set as the app's deployment target; see Installation above
  • Android API >= 21

License #

MIT

0
likes
0
points
891
downloads

Documentation

Documentation

Publisher

verified publisherbilldog.io

Weekly Downloads

BillDog SDK for Flutter — monetization, paywalls, subscriptions and BillDog Auth sign-in. Thin bridge over the native iOS/Android SDKs with inline native paywall rendering.

Homepage
View/report issues

Topics

#in-app-purchase #subscriptions #paywall #monetization #analytics

License

unknown (license)

Dependencies

flutter, shared_preferences

More

Packages that depend on billdog_flutter

Packages that implement billdog_flutter