BillDog is an all-in-one Monetization, Engagement, and Data platform built for mobile applications. It combines Paywalls & Billing, Product Analytics, Session Replay, In-App Messaging, Push, and Surveys into a single package.
Current release: 1.1.1-beta.5
This repository distributes the SDK as binary XCFrameworks. There are two products β pick exactly one per target:
| Product | Use when | Import |
|---|---|---|
BillDogFull |
You need paywalls, StoreKit purchases, offline caching, and the engagement suite. | import BillDogFull |
BillDogEng |
Engagement only β no StoreKit, no Lottie, no paywall rendering. | import BillDogEng |
Each product ships as ONE Swift module. Sub-module imports such as
import BillDogAnalyticsorimport BillDogPaywallare not available to binary consumers β every public type lives in the singleBillDogFull/BillDogEngmodule. A single import gives you the whole surface.
BillDogFullwas calledBillDogbefore1.0.0-beta.2. The product and module were renamed becauseBillDogPaywalldeclares apublic class BillDog, and a module of the same name made the binary unimportable (swiftlang/swift#56573). The class is unchanged βBillDog.shared.β¦still works everywhere. Only the import moved:- import BillDog + import BillDogFull
The two products cannot be linked into the same target β the SDK emits a compile-time
#errorif both compilation conditions are set.
| Capability | BillDogFull |
BillDogEng |
|---|---|---|
| Core β configuration, identity, consent, dynamic values | β | β |
| Auth β authentication, hosted auth cards, sessions, and token refresh | β | β |
| Paywall β SwiftUI native paywall rendering + StoreKit 2 purchases | β | β |
| Caching β offline-first paywall/survey/asset cache | β | β |
| WebView β HTML/CSS paywall renderer + preload pool | β | β |
| Survey β in-app surveys with branching logic | β | β |
| Analytics β events, autocapture, super properties, user properties | β | β |
| Session Replay β screenshot-based replay with privacy masking | β | β |
A/B Test & Feature Flags β BillDogABTestManager |
β | β |
| Notifications β push tokens, consent, deep links | β | β |
| In-App Messages β trigger-based modals and banners | β | β |
| Virtual Currency β server-synced wallet balances | β | β |
A/B Test & feature flags:
BillDogABTestManageris the single, canonical experiment / feature-flag surface, reachable through bothimport BillDogFullandimport BillDogEng(getVariant,allAssignments,getFeatureFlag,getFeatureFlagVariant,getFeatureFlagPayload,trackImpression,trackConversion).A redundant paywall-facade shim β
confirmAllAssignments()/getExperimentOverrides()/forceExperimentVariant()/clearExperimentOverrides()plus a duplicate paywallgetFeatureFlag/reloadFeatureFlagscache β was removed. UseBillDogABTestManagerfor all experiments and feature flags.
dependencies: [
.package(url: "https://github.com/billdogai/billdog-ios-spm.git", from: "1.1.1-beta.5")
]Then add one product to your target:
.target(name: "MyApp", dependencies: [
.product(name: "BillDogFull", package: "billdog-ios-spm") // or "BillDogEng"
])In Xcode:
- File β Add Package Dependenciesβ¦
- Enter
https://github.com/billdogai/billdog-ios-spm.git - Choose Exact Version
1.1.1-beta.5(pre-release versions are not picked up by "Up to Next Major"). - Add either
BillDogFullorBillDogEngto your app target.
BillDogFull transitively resolves lottie-ios 4.4.0+ for animated paywall content. BillDogEng has no third-party dependencies.
Not published yet. The beta is SPM-only.
Configure once at launch. That alone records analytics β your trackEvent calls and the SDK's own paywall, purchase and app-lifecycle events β because configure() registers the analytics module for you. Register the other optional modules you use.
import SwiftUI
import BillDogFull
@main
struct MyApp: App {
init() {
BillDog.shared.configure(
config: BillDogConfig(
apiKey: "your_api_key",
enableLogging: true,
environment: .production
)
)
// Analytics is registered by configure(). The rest are opt-in.
BillDog.shared.use(module: BillDogNotificationsManager.shared)
BillDog.shared.use(module: BillDogInAppMessagesManager.shared)
BillDog.shared.use(module: BillDogVirtualCurrencyManager.shared)
BillDog.shared.use(module: BillDogCachingManager())
BillDog.shared.use(module: BillDogWebViewManager.shared)
}
var body: some Scene {
WindowGroup { ContentView() }
}
}// Identify a user β links the anonymous session to an account.
Task {
let result = try await BillDog.shared.identify(userId: "user_uuid_123")
print("New user? \(result.isNewUser)")
print("Premium? \(result.customerInfo.hasEntitlement("premium"))")
}
// Read cached entitlement state at any time.
Task {
let customerInfo = try await BillDog.shared.getCustomerInfo()
if customerInfo.hasEntitlement("premium") {
// Unlock premium content
}
// Also available:
// customerInfo.hasActiveSubscription -> Bool
// customerInfo.entitlements -> [EntitlementInfo]
// customerInfo.activeSubscriptions -> [String]
}
// Reset identity on logout.
BillDog.shared.logOut()Consent is server-authoritative and lives on the core facade:
BillDog.shared.setConsentRequired(true)
BillDog.shared.setConsentGiven(true)Analytics opt-out is per-module:
let analytics = BillDog.shared.getModules()
.compactMap { $0 as? BillDogAnalyticsManager }
.first
analytics?.optOut() // stop collection
analytics?.optIn() // resumeoptOut() also stops session replay recording, not only its upload, and it
covers both recorders: the $snapshot recorder (BillDogReplayManager) and the
video recorder (BillDog.shared.replay). Frames, touches and chunks are
discarded, not sent, including those already waiting in an upload queue: replay
frames queued or dead-lettered in analytics (whatever the dashboard's "Clear on
Opt-Out" says) and video chunks waiting to upload, even when the video recorder
was not set up in that launch. Only a request already on the wire is out of
reach. The opt-out is persisted, so neither recorder starts on a later launch
while the user stays opted out. optIn() resumes whatever the host had
switched on as a new recording, under a new session id, with sampling rolled
again. Nothing captured before the opt-out comes back.
BillDogEng does not contain the BillDog facade class (it lives in the paywall module). Configure each manager directly:
import BillDogEng
let config = BillDogConfig(apiKey: "your_api_key", enableLogging: true, environment: .production)
let analytics = BillDogAnalyticsManager()
analytics.configure(config: config)
let abTest = BillDogABTestManager()
abTest.configure(config: config)
BillDogNotificationsManager.shared.configure(config: config)
BillDogInAppMessagesManager.shared.configure(config: config)Feature flags and experiments (available in both BillDogFull and BillDogEng). With BillDogFull, BillDog.shared.abTest is the manager β created on first use, evaluated for the SDK's current identity (no setUserId needed). It is not created at configure() because its fetch enrols the user in every running experiment.
let abTest = BillDog.shared.abTest // BillDogFull; with BillDogEng, the manager configured above
// Wait for this launch's flags (default timeout 5 s). false: timed out or
// failed, and the getters answer from the previous launch's cache.
await abTest.waitForFlags()
if abTest.getFeatureFlag(key: "new_onboarding") {
// flag is on
}
let variant = abTest.getFeatureFlagVariant(key: "checkout_copy") // String?
let payload = abTest.getFeatureFlagPayload(key: "checkout_copy") // Any?
let assignment = await abTest.getVariant(experimentId: "exp_123")
abTest.trackImpression(experimentId: "exp_123")
abTest.trackConversion(experimentId: "exp_123", value: 9.99)π³ Paywalls & Billing β BillDogFull only
import SwiftUI
import BillDogFull
struct ContentView: View {
@State private var showPaywall = false
@State private var paywallConfig: PaywallConfiguration?
var body: some View {
Button("Show Premium") {
Task {
paywallConfig = try? await BillDog.shared.fetchPaywall(identifier: "premium_offer")
showPaywall = paywallConfig != nil
}
}
.sheet(isPresented: $showPaywall) {
if let config = paywallConfig {
PaywallView(
configuration: config,
onButtonPress: { componentId, action in
if action == "dismiss" { showPaywall = false }
}
)
}
}
}
}PaywallView also accepts offering:, trialEligibility:, and enableLogging: β all optional.
Every PaywallPresentationHandler callback is a closure property; all are optional.
BillDog.shared.presentPaywall(
identifier: "premium_monthly",
from: self,
handler: PaywallPresentationHandler(
willAppear: { paywallId in print("about to show \(paywallId)") },
onPresent: { paywallId in print("presented \(paywallId)") },
onDismiss: { paywallId in print("dismissed \(paywallId)") },
onError: { error in print("failed: \(error)") },
onSkip: { reason in print("skipped: \(reason)") },
onPurchaseSuccess: { productId in
.dismiss // PostPurchaseBehavior
}
)
)// By product id
let result = try await BillDog.shared.purchase(productId: "pro_yearly")
// By package from an offering
let result = try await BillDog.shared.purchase(package: package)
// Advanced StoreKit 2 parameters
let params = PurchaseParams.Builder(productId: "pro_yearly")
.with(promoOfferId: "intro_2024")
.with(winBackOfferId: "winback_30off")
.with(appAccountToken: UUID())
.with(quantity: 1)
.with(isPersonalizedOffer: true) // EEA disclosure
.build()
let result = try await BillDog.shared.purchase(params: params)
switch result {
case .purchased(let transactionId, let productId, _): break
case .restored(let transactionId, let productId, _): break
case .cancelled: break // never surfaced as .failed
case .pending: break // Ask-to-Buy / deferred
case .failed(let error): break
}
// Restore
let restore = try await BillDog.shared.restorePurchases() // RestoreResultEvery BillDog purchase entry point β paywall buttons, purchase(productId:),
purchase(package:), purchase(params:), consumables β reaches your controller.
Your app runs StoreKit and finishes its own transactions; BillDog never does.
BillDog records the purchase by posting its store evidence, which the server
verifies with Apple. Return the evidence when you have it:
final class MyPurchaseController: PurchaseControllerProtocol {
func purchase(request: PurchaseRequest) async throws -> PurchaseOutcome {
let product = try await Product.products(for: [request.params.productId]).first!
var options: Set<Product.PurchaseOption> = []
// Optional: bind the purchase to the BillDog customer.
if let token = request.storeAccountToken { options.insert(.appAccountToken(token)) }
switch try await product.purchase(options: options) {
case .success(let verification):
if case .verified(let transaction) = verification { await transaction.finish() }
let evidence = StoreEvidence(verification)
return PurchaseOutcome(.purchased(transactionId: evidence.transactionId ?? "",
productId: product.id, originalTransactionId: nil),
evidence: [evidence])
case .userCancelled: return PurchaseOutcome(.cancelled) // never .failed
case .pending: return PurchaseOutcome(.pending) // Ask to Buy
@unknown default: return PurchaseOutcome(.cancelled)
}
}
// The two original requirements still apply; `purchase(request:)` defaults to them.
func purchase(productId: String) async throws -> PurchaseResult { .cancelled }
func restorePurchases() async throws -> RestoreResult { .restored(items: []) }
var storeKitVersion: HostStoreKitVersion { .storeKit2 } // .storeKit1 keeps BillDog's SK1 observer
}
BillDog.shared.configure(
config: BillDogConfig(apiKey: "your_api_key"),
purchaseController: MyPurchaseController()
)Without evidence, BillDog derives it from StoreKit by the result's transaction id.
A request needing quantity > 1 or a win-back offer is refused with a typed error
unless the controller declares that capability (capabilities). A purchase you
make outside a controller is recorded with BillDog.shared.recordPurchase(verification).
| Tier | Renderer | Best for |
|---|---|---|
| Native | SwiftUI | Best performance; JSON-to-native conversion |
| WebView | HTML/CSS | Complex CSS-only effects |
Supported component types: Text, Image, Button, Stack, Package, Price, Icon (SF Symbols), Video.
β‘ Offerings & Caching β BillDogFull only
let offerings: [Offering] = try await BillDog.shared.fetchOfferings()fetchOfferings() takes no arguments β it returns every offering configured for the project, resolved against the local cache. Use OfferingManager directly if you need forceRefresh.
Cache statistics come from the caching module instance you registered:
let caching = BillDogCachingManager()
BillDog.shared.use(module: caching)
let stats = caching.getCacheStats()
print("paywalls: \(stats.paywallCount), surveys: \(stats.surveyCount)")
print("assets: \(stats.assetCount), bytes: \(stats.totalSizeBytes)")
print("renderer cached: \(stats.rendererCached) @ \(stats.rendererVersion ?? "β")")Other cache controls: clearPaywallCaches(), clearSurveyCaches(), clear(), getCachedPaywallAgeMs(identifier:).
π Product Analytics β both products
The analytics class is BillDogAnalyticsManager. With BillDogFull you can also use the facade shortcut:
BillDog.shared.trackEvent("song_played", properties: [
"genre": "synthwave",
"duration_seconds": 240
])Everything else goes through the manager instance β with BillDogFull, the one configure() registered:
guard let analytics = BillDog.shared.analytics else { return } // nil only before configure()
// Super properties β attached to every outgoing event
analytics.registerSuperProperties(["app_version": "1.4.2"])
analytics.registerSuperPropertiesOnce(["initial_referrer": "google"])
analytics.unregisterSuperProperty("initial_referrer")
analytics.clearSuperProperties()
// User properties
analytics.setUserProperties(["tier": "vip"])
analytics.incrementUserProperty("songs_count", by: 1.0)
analytics.unionUserProperty("favorite_genres", values: ["rock", "jazz"])
// Identity
analytics.identify(userId: "user_uuid_123")
analytics.alias(newId: "user_uuid_123", previousId: analytics.getDistinctId())
let distinctId = analytics.getDistinctId()
// Queue control
analytics.flush()
await analytics.flushAsync()
// Timed events β emits a "$duration" property (seconds)
analytics.timeEvent("level_completed")
// β¦ later β¦
analytics.track(event: BillDogAnalyticsEvent(name: "level_completed", properties: ["level_number": 5]))To use an instance of your own (a custom store directory, or your own AnalyticsModuleInterface pipeline), pass it to BillDog.shared.use(module:) at launch: registered before configure(), the SDK registers none; registered after, it replaces the SDK's, which stops recording and leaves its queued events to yours.
All off by default.
analytics.enableSessionTracking()
analytics.enableScreenTracking()
analytics.enableAutocapture(AutocaptureConfig(enabled: true, maskAllText: true))
analytics.enableExceptionAutocapture()AutocaptureConfig(enabled:maskAllText:maskAllInputs:ignoreClasses:) β maskAllInputs defaults to true.
final class DataMaskingPlugin: AnalyticsPlugin {
func process(event: BillDogAnalyticsEvent) -> BillDogAnalyticsEvent? {
if event.name == "debug_event" { return nil } // drop
var properties = event.properties
if properties.keys.contains("email") {
properties["email"] = "[REDACTED]"
}
return BillDogAnalyticsEvent(name: event.name, properties: properties, timestamp: event.timestamp)
}
}
analytics.addPlugin(DataMaskingPlugin())πΉ Session Replay β both products
Screenshot-based replay with interaction capture. Off by default; every privacy knob defaults to masked.
With BillDogFull, use the facade handle:
var options = BillDogReplayOptions(projectId: "your_project_id")
options.triggerMode = .session // or .bufferUntilError
options.quality = .medium
options.maskAllText = true // default
options.maskAllImages = true // default
BillDog.shared.replay.configure(options)
BillDog.shared.replay.start()Handle API: start(), stop(), markCheckpoint(_:metadata:), linkIdentity(distinctId:), capture(reason:), skipCurrentScreen(), maskView(_:), unmaskView(_:), optIntoCapture(), openLocalViewer().
With BillDogEng, drive BillDogReplayManager directly.
- Mask a view programmatically:
BillDog.shared.replay.maskView(mySensitiveView) - Or set the view's
accessibilityIdentifiertobilldog-replay-mask(billdog-replay-unmaskopts back in). - Mask whole classes via
options.maskedClassNames/unmaskedClassNames. - Secure text entry fields are masked automatically.
π¬ In-App Messages β both products
let messages = BillDogInAppMessagesManager.shared
// Evaluate and display messages matching a trigger
messages.checkForMessages(trigger: "checkout_abandoned", properties: ["cart_value": 49.99])
// Suppress display during critical flows
messages.paused = trueπ Surveys β both products
With BillDogFull:
if let presenter = BillDog.getSurveyPresenter() {
presenter.present(
surveyId: "onboarding_survey",
from: self,
customerId: "user-123"
)
}Full signature: present(surveyId:from:handler:customerId:anonymousId:customVariables:interceptConfig:) β everything after from: is optional. Pass a SurveyPresentationHandler for onPresent / onDismiss / onComplete / onError / onAnswerChanged.
With BillDogEng, construct BillDogSurveyPresenter(surveyManager:) yourself.
π Push Notifications β both products
let notifications = BillDogNotificationsManager.shared
// Marketing consent
notifications.setConsentRequired(true)
notifications.setConsentGiven(true)
// Sync the APNs device token (String form)
notifications.pushSubscription.updateToken(tokenString)
// Opt out of push without clearing the token
notifications.pushSubscription.optOut()pushSubscription requires iOS 15+.
πͺ Virtual Currency β BillDogFull only
Server-backed wallet; local storage is a read-through cache only.
let wallet = BillDogVirtualCurrencyManager.shared
let balance: Double = try await wallet.getBalance(currencyId: "gems")
let newBalance: Double = try await wallet.grantCurrency(
currencyId: "gems",
amount: 50,
reason: "daily_reward"
)Sign-in, sessions and second factors, in the app. The refresh token is held in the Keychain; the session token stays in memory and is refreshed for you.
Available in
1.1.0-beta.3and later. PrecompiledBillDogFullandBillDogEngXCFramework binaries includeBillDogAuthout of the box with zero additional configuration.
BillDogAuth is re-exported by both umbrellas, so import BillDogFull or
import BillDogEng is enough. On BillDogEng it registers itself. On
BillDogFull, register it like any other optional module:
BillDog.shared.use(module: BillDogAuth.shared)import BillDogFull
do {
let session = try await BillDogAuth.shared.attempt(
identifier: "ada@example.com",
strategy: .password,
password: password
)
print(session)
} catch BillDogAuth.AuthError.mfaRequired(let token, _) {
// First factor accepted. Finish with the second, passing the token back β
// it is what proves the password was already verified.
let session = try await BillDogAuth.shared.attempt(
identifier: "ada@example.com",
strategy: .totp,
code: code,
mfaToken: token
)
print(session)
} catch BillDogAuth.AuthError.invalidCredentials {
// Deliberately identical whether the identifier exists or not.
}// A RETURNING user gets a fresh code from requestCode. Without it a code could
// only be obtained as a side effect of signing up.
try await BillDogAuth.shared.requestCode(identifier: "+15551234567", kind: "phone")
let session = try await BillDogAuth.shared.attempt(
identifier: "+15551234567",
kind: "phone", // REQUIRED β see below
strategy: .smsCode,
code: code
)kind selects the identity row and defaults to "email". A phone sign-in
that omits it looks up a phone number among email addresses and silently matches
nothing. Pass it on requestCode, attempt and signUp alike, and pass the
same value to all three.
if let session = await BillDogAuth.shared.restore() {
// signed in
} else if BillDogAuth.shared.hasStoredSession {
// signed in, not renewed yet (offline, or before the first unlock):
// stay in the signed-in experience; the SDK resumes the session itself
} else {
// nobody is signed in
}
BillDogAuth.shared.isSignedIn
BillDogAuth.shared.authHeaders // for your own API
await BillDogAuth.shared.signOut() // "this" | "others" | "all"restore() returns nil rather than throwing. nil alone does not mean "not
signed in": an offline launch, or one before the device's first unlock after a
reboot, also returns nil while the session is intact, and the SDK renews it by
itself once the network is back or the Keychain unlocks. hasStoredSession
(no network) tells the two apart, as Auth0's canRenew() does: show a sign-in
screen only when it is false.
BillDogOrganizations (create, list, members, roles, invitations, domains) and
BillDogPasskeys (register and sign in with Face ID / Touch ID), both in the
same module.
- Sign up into a project with bot protection or
invite_onlyaccess.signUptakes no captcha or invitation token, and there is noconfig()to discover that the project requires one β the server answers 400. Use hosted sign-in for those projects until the parameters ship. - Complete a password reset. Reachable only through a hosted sign-in page.
- Delete a user's own account. Erasure runs through the operator DSAR flow.
- iOS 15.0+ β the published XCFrameworks ship device and simulator slices only; there is no macOS slice.
- Xcode 15.0+
- Swift 5.7+
- π Documentation
- βοΈ support@billdog.io
- iOS SDK guide β install, configure and ship the full SDK
- iOS Eng SDK guide β analytics, flags, surveys and messaging without purchases
- Quickstart
- App Store Connect setup β shared secret, server notifications, StoreKit keys
- Paywall builder β design native paywalls without an app release
- A/B experiments β test prices, paywalls and offers
- Product analytics
- Session replay
- BillDog Auth
- Migrating from RevenueCat
- Support β questions, bugs and feature requests
| Platform | Package | Docs |
|---|---|---|
| iOS (Swift) | billdog-ios-spm | iOS guide |
| Android (Kotlin) | billdog-android-full Β· billdog-android-eng | Android guide |
| React Native Β· Flutter Β· Web | npm Β· pub.dev | React Native Β· Flutter Β· Web |
| Superwall bridge (iOS) | billdog-ios-superwall | Superwall integration |
| Server (Go, PHP, Node, Pythonβ¦) | billdogeng-go Β· billdogeng-php | Server SDKs |
| AI coding agents (MCP) | billdog-mcp | MCP server |
Not sure which one you need? See choosing an SDK.
BillDog iOS SDK is available under the MIT license. See LICENSE for details.
Made with β€οΈ by the BillDog team