@virex-tech/paywallo-sdk 2.5.3 → 2.6.2

package/README.md

@@ -25,6 +25,17 @@ npm install expo-tracking-transparency
 
 This enables the ATT prompt ("Allow this app to track your activity?"). Without it, the SDK skips IDFA collection — everything else works normally.
 
+### Optional: Facebook `_fbp` on Android
+
+For `fb_anon_id` (the `_fbp` cookie proxy used by Meta attribution) to work correctly on Android, the host app must declare the Facebook Android SDK as a runtime dependency:
+
+```gradle
+// android/app/build.gradle
+implementation 'com.facebook.android:facebook-android-sdk:latest.release'
+```
+
+The SDK references the Facebook Android SDK as `compileOnly` (to avoid forcing it on all apps). If the host does **not** include it as `implementation`, `metaBridge.getAnonymousID()` returns `null` and the SDK falls back to a locally-generated `PW_<uuid>`. This local ID is **not recognised by Meta** as a `_fbp` value, so Facebook attribution will not benefit from cookie matching on Android. When debug mode is enabled, the SDK logs a warning when this fallback is triggered.
+
 ## Quick start
 
 ### 1. Wrap your app

package/android/build.gradle

@@ -49,7 +49,7 @@ repositories {
 dependencies {
     implementation "com.facebook.react:react-native:+"
     implementation "org.jetbrains.kotlin:kotlin-stdlib:${safeExtGet('kotlinVersion', '2.0.21')}"
-    implementation "com.android.billingclient:billing-ktx:7.0.0"
+    implementation "com.android.billingclient:billing-ktx:8.0.0"
     implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3"
     implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
     compileOnly "com.facebook.android:facebook-android-sdk:17.+"
@@ -57,4 +57,5 @@ dependencies {
     // 1.1.0+ required for MasterKey.Builder API used in PaywalloStorageModule.
     // 1.0.0 only ships the deprecated MasterKeys.getOrCreate(...) static helper.
     implementation "androidx.security:security-crypto:1.1.0"
+    implementation "com.google.android.gms:play-services-ads-identifier:18.0.1"
 }

package/android/src/main/AndroidManifest.xml

@@ -16,6 +16,13 @@
     -->
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 
+    <!--
+        AD_ID (Android 13+) — sem essa permissão o Google Play Services devolve
+        o GAID como all-zeros, quebrando o madid do Meta CAPI. O merge de manifest
+        propaga pro app host automaticamente.
+    -->
+    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
+
     <application>
         <!--
             PaywalloFirebaseMessagingService handles FCM token refresh and message delivery.

package/android/src/main/java/com/paywallo/sdk/PaywalloAdvertisingIdModule.kt

@@ -0,0 +1,55 @@
+package com.paywallo.sdk
+
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import java.util.concurrent.Executors
+
+private val ALL_ZEROS = "00000000-0000-0000-0000-000000000000"
+
+class PaywalloAdvertisingIdModule(private val reactContext: ReactApplicationContext) :
+    ReactContextBaseJavaModule(reactContext) {
+
+    private val executor = Executors.newSingleThreadExecutor()
+
+    override fun getName() = "PaywalloAdvertisingId"
+
+    // invalidate() is the post-TurboModule replacement for onCatalystInstanceDestroy.
+    // Shuts down the background executor to avoid thread leak on bridge reload.
+    override fun invalidate() {
+        executor.shutdown()
+        super.invalidate()
+    }
+
+    @ReactMethod
+    fun getAdvertisingId(promise: Promise) {
+        // AdvertisingIdClient.getAdvertisingIdInfo() is blocking and must NOT run
+        // on the main thread — run on a background executor instead.
+        executor.execute {
+            try {
+                val info = com.google.android.gms.ads.identifier.AdvertisingIdClient
+                    .getAdvertisingIdInfo(reactApplicationContext)
+
+                if (info.isLimitAdTrackingEnabled) {
+                    // User opted out of ad tracking — honour their choice.
+                    promise.resolve(null)
+                    return@execute
+                }
+
+                val id = info.id
+                if (id == null || id == ALL_ZEROS) {
+                    promise.resolve(null)
+                } else {
+                    promise.resolve(id)
+                }
+            } catch (t: Throwable) {
+                // Catches GooglePlayServicesNotAvailableException,
+                // GooglePlayServicesRepairableException, NoClassDefFoundError,
+                // IOException, and any other runtime failure.
+                // Never reject/crash — gracefully return null.
+                promise.resolve(null)
+            }
+        }
+    }
+}

package/android/src/main/java/com/paywallo/sdk/PaywalloSdkPackage.kt

@@ -11,8 +11,9 @@ class PaywalloSdkPackage : ReactPackage {
             PaywalloStoreKitModule(reactContext),
             PaywalloFBBridgeModule(reactContext),
             PaywalloStorageModule(reactContext),
-PaywalloNotificationsModule(reactContext),
-            PaywalloEnvModule(reactContext)
+            PaywalloNotificationsModule(reactContext),
+            PaywalloEnvModule(reactContext),
+            PaywalloAdvertisingIdModule(reactContext)
         )
     }
 

package/android/src/main/java/com/paywallo/sdk/PaywalloStoreKitModule.kt

@@ -56,7 +56,12 @@ class PaywalloStoreKitModule(private val reactContext: ReactApplicationContext)
         if (billingClient == null || billingClient?.isReady != true) {
             billingClient = BillingClient.newBuilder(reactContext)
                 .setListener(this)
-                .enablePendingPurchases()
+                // A Billing 7 depreciou e a 8 REMOVEU o enablePendingPurchases() sem argumento.
+                // Um app que traz a billing 8 por outra dependência (ex.: Superwall) resolve a
+                // versão mais alta no Gradle e a chamada antiga vira NoSuchMethodError em runtime.
+                .enablePendingPurchases(
+                    PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()
+                )
                 .build()
         }
         return billingClient!!
@@ -173,10 +178,12 @@ class PaywalloStoreKitModule(private val reactContext: ReactApplicationContext)
             .build()
 
         return suspendCancellableCoroutine { cont ->
-            client.queryProductDetailsAsync(params) { result, detailsList ->
+            // Na Billing 8 o callback passou a receber QueryProductDetailsResult em vez da
+            // lista direta — a assinatura antiga não existe mais em runtime.
+            client.queryProductDetailsAsync(params) { result, detailsResult ->
                 if (cont.isActive) {
                     if (result.responseCode == BillingClient.BillingResponseCode.OK) {
-                        cont.resume(detailsList ?: emptyList()) {}
+                        cont.resume(detailsResult.productDetailsList) {}
                     } else {
                         cont.resume(emptyList()) {}
                     }

package/dist/index.d.mts

@@ -346,6 +346,7 @@ interface IdentifyOptions {
     lastName?: string;
     dateOfBirth?: string;
     gender?: "m" | "f";
+    zipCode?: string;
 }
 interface TrackEventOptions {
     properties?: UserProperties;
@@ -407,9 +408,12 @@ interface EventContext {
 /**
  * Event priority controls flush semantics:
  *
- * - `"critical"` → flushed as a batch-of-1 on the next microtask (via
- *   `queueMicrotask`). Used for events where loss is unacceptable:
- *   `transaction`, `identify`, `lifecycle {type: "install"}`,
+ * - `"critical"` → posted as a batch-of-1 immediately, and `track()` awaits
+ *   the post before resolving. `PostFn` (`ApiClient.postWithQueue`) performs
+ *   a write-ahead journal to `OfflineQueue` for critical events before any
+ *   network attempt, so by the time `track()` resolves the event is durable
+ *   on disk — not just handed off to a microtask. Used for events where loss
+ *   is unacceptable: `transaction`, `identify`, `lifecycle {type: "install"}`,
  *   `subscription_*`, `refund`, `checkout_started`.
  * - `"normal"` → buffered and flushed on a rolling window (whichever fires
  *   first): `BATCH_MAX_SIZE` events OR `BATCH_FLUSH_MS`. Used for events
@@ -535,6 +539,7 @@ declare class ApiClient {
         lastName?: string;
         dateOfBirth?: string;
         gender?: string;
+        zipCode?: string;
     }): Promise<void>;
     getVariant(flagKey: string, distinctId: string): Promise<FlagVariant>;
     getPaywall(placement: string): Promise<PaywallConfig | null>;
@@ -559,6 +564,7 @@ interface IdentityState {
     lastName: string | null;
     dateOfBirth: string | null;
     gender: string | null;
+    zipCode: string | null;
 }
 declare class IdentityManager {
     private deviceId;
@@ -570,6 +576,7 @@ declare class IdentityManager {
     private lastName;
     private dateOfBirth;
     private gender;
+    private zipCode;
     private apiClient;
     private secureStorage;
     private debug;
@@ -641,7 +648,6 @@ type NotificationsEnvironment = "sandbox" | "production";
 interface NotificationsConfig {
     debug?: boolean;
     environment?: NotificationsEnvironment;
-    apiBaseUrl?: string;
 }
 
 declare const NOTIFICATIONS_ERROR_CODES: {
@@ -748,7 +754,6 @@ interface HandlersConfig {
 }
 interface NotificationsManagerConfig {
     appKey: string;
-    apiBaseUrl?: string;
     debug?: boolean;
     environment?: NotificationsConfig["environment"];
 }
@@ -1632,8 +1637,25 @@ declare class OnboardingError extends PaywalloError {
 declare const ONBOARDING_ERROR_CODES: {
     readonly NOT_INITIALIZED: "ONBOARDING_NOT_INITIALIZED";
     readonly INVALID_STEP_NAME: "ONBOARDING_INVALID_STEP_NAME";
+    readonly INVALID_ORDER: "ONBOARDING_INVALID_ORDER";
 };
 
+/** Payload sent with onboarding.step events. */
+interface OnboardingStepPayload {
+    step_name: string;
+    /** Ordem de exibição do step (aceita decimais, ex: 2.1 para variantes A/B). Obrigatório. */
+    order: number;
+    variant_key?: string;
+    time_on_prev_s?: number;
+}
+interface OnboardingStepOptions {
+    variantKey?: string;
+    timeOnPrevS?: number;
+}
+interface OnboardingCompleteOptions {
+    variantKey?: string;
+}
+
 /**
  * Minimal surface the OnboardingManager needs from the unified event pipeline.
  * `PaywalloClient` satisfies this interface (forwarding to
@@ -1661,42 +1683,26 @@ declare class OnboardingManager {
      * Saves the step name internally for implicit drop detection on the backend.
      *
      * @param stepName - Unique name for this onboarding step.
-     * @param order - Optional explicit display order (accepts decimals, e.g. 2.1 for A/B variants).
+     * @param order - Ordem de exibição do step. Obrigatório. Aceita decimais (ex: 2.1 para variantes A/B).
+     *   Deve ser um número finito e não-negativo. O servidor faz o floor — não arredondar aqui.
      */
-    step(stepName: string, order?: number): Promise<void>;
+    step(stepName: string, order: number, options?: OnboardingStepOptions): Promise<void>;
     /**
      * Tracks successful completion of the onboarding flow.
      * Marks the flow as finished.
      */
-    complete(): Promise<void>;
-    /**
-     * Tracks an explicit drop (abandonment) at the given step.
-     * Marks the flow as finished.
-     *
-     * @param stepName - The step name where the user dropped off.
-     */
-    drop(stepName: string): Promise<void>;
+    complete(options?: OnboardingCompleteOptions): Promise<void>;
     /** Returns the last step name seen, or null if no step was tracked yet. */
     getLastStep(): string | null;
-    /** Returns whether the flow has been marked as finished (complete or drop). */
+    /** Returns whether the flow has been marked as finished (complete). */
     isFinished(): boolean;
     private emit;
     private assertConfig;
     private validateStepName;
+    private validateOrder;
 }
 declare const onboardingManager: OnboardingManager;
 
-/** Payload sent with onboarding.step events. */
-interface OnboardingStepPayload {
-    step_name: string;
-    /** Optional explicit order (accepts decimals, e.g. 2.1 for A/B variants). */
-    order?: number;
-}
-/** Payload sent with onboarding.drop events. */
-interface OnboardingDropPayload {
-    step_name: string;
-}
-
 interface PaywallContextValue {
     nodes: Record<string, PaywallNode>;
     rootId: string;
@@ -1863,9 +1869,8 @@ interface UseOfferingsResult {
 declare function useOfferings(ids?: string[]): UseOfferingsResult;
 
 interface UseOnboardingResult {
-    step: (stepName: string, order?: number) => Promise<void>;
-    complete: () => Promise<void>;
-    drop: (stepName: string) => Promise<void>;
+    step: (stepName: string, order: number, options?: OnboardingStepOptions) => Promise<void>;
+    complete: (options?: OnboardingCompleteOptions) => Promise<void>;
 }
 /**
  * React hook that exposes bound onboarding tracking methods.
@@ -2017,4 +2022,4 @@ declare function hasVariables(text: string): boolean;
 
 declare const Paywallo: IPaywalloClient;
 
-export { type AllPlansResponse, ApiClient, type ApiClientConfig, type AttributionCapture, AttributionTracker, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedOfferings, type CachedPlans, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, type DeviceTokenRegistration, PURCHASE_ERROR_CODES as ERROR_CODES, type EmergencyPaywallResponse, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IPushBridge, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, MetaBridge, NOTIFICATIONS_ERROR_CODES, NativePushBridge, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type NotificationEventType, type NotificationListener, type NotificationPayload, NotificationsError, NotificationsManager, ONBOARDING_ERROR_CODES, type Offering, type OfferingProduct, OfferingService, type OfferingServiceConfig, type OfflineQueueConfig, type OnboardingDropPayload, OnboardingError, OnboardingManager, type OnboardingStepPayload, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type Plan, PlanCache, type PlanProduct, PlanService, type PlanServiceConfig, type PlansResponse, type PrePromptHandle, type PrePromptOptions, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type PushPermissionStatus, type PushPlatform, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult$1 as RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, attributionTracker, createPurchaseError, Paywallo as default, detectDeviceLanguage, getActiveRouteName, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, metaBridge, nativeStoreKit, networkMonitor, notificationsManager, offeringService, offlineQueue, onboardingManager, parseVariables, planCache, planService, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, useOfferingPurchase, useOfferings, useOnboarding, usePaywallContext, usePaywallo, usePaywalloScreenTracking, usePlanPurchase, usePlans, useProducts, usePurchase, useSubscription };
+export { type AllPlansResponse, ApiClient, type ApiClientConfig, type AttributionCapture, AttributionTracker, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedOfferings, type CachedPlans, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, type DeviceTokenRegistration, PURCHASE_ERROR_CODES as ERROR_CODES, type EmergencyPaywallResponse, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IPushBridge, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, MetaBridge, NOTIFICATIONS_ERROR_CODES, NativePushBridge, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type NotificationEventType, type NotificationListener, type NotificationPayload, NotificationsError, NotificationsManager, ONBOARDING_ERROR_CODES, type Offering, type OfferingProduct, OfferingService, type OfferingServiceConfig, type OfflineQueueConfig, OnboardingError, OnboardingManager, type OnboardingStepPayload, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type Plan, PlanCache, type PlanProduct, PlanService, type PlanServiceConfig, type PlansResponse, type PrePromptHandle, type PrePromptOptions, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type PushPermissionStatus, type PushPlatform, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult$1 as RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, attributionTracker, createPurchaseError, Paywallo as default, detectDeviceLanguage, getActiveRouteName, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, metaBridge, nativeStoreKit, networkMonitor, notificationsManager, offeringService, offlineQueue, onboardingManager, parseVariables, planCache, planService, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, useOfferingPurchase, useOfferings, useOnboarding, usePaywallContext, usePaywallo, usePaywalloScreenTracking, usePlanPurchase, usePlans, useProducts, usePurchase, useSubscription };

package/dist/index.d.ts

@@ -346,6 +346,7 @@ interface IdentifyOptions {
     lastName?: string;
     dateOfBirth?: string;
     gender?: "m" | "f";
+    zipCode?: string;
 }
 interface TrackEventOptions {
     properties?: UserProperties;
@@ -407,9 +408,12 @@ interface EventContext {
 /**
  * Event priority controls flush semantics:
  *
- * - `"critical"` → flushed as a batch-of-1 on the next microtask (via
- *   `queueMicrotask`). Used for events where loss is unacceptable:
- *   `transaction`, `identify`, `lifecycle {type: "install"}`,
+ * - `"critical"` → posted as a batch-of-1 immediately, and `track()` awaits
+ *   the post before resolving. `PostFn` (`ApiClient.postWithQueue`) performs
+ *   a write-ahead journal to `OfflineQueue` for critical events before any
+ *   network attempt, so by the time `track()` resolves the event is durable
+ *   on disk — not just handed off to a microtask. Used for events where loss
+ *   is unacceptable: `transaction`, `identify`, `lifecycle {type: "install"}`,
  *   `subscription_*`, `refund`, `checkout_started`.
  * - `"normal"` → buffered and flushed on a rolling window (whichever fires
  *   first): `BATCH_MAX_SIZE` events OR `BATCH_FLUSH_MS`. Used for events
@@ -535,6 +539,7 @@ declare class ApiClient {
         lastName?: string;
         dateOfBirth?: string;
         gender?: string;
+        zipCode?: string;
     }): Promise<void>;
     getVariant(flagKey: string, distinctId: string): Promise<FlagVariant>;
     getPaywall(placement: string): Promise<PaywallConfig | null>;
@@ -559,6 +564,7 @@ interface IdentityState {
     lastName: string | null;
     dateOfBirth: string | null;
     gender: string | null;
+    zipCode: string | null;
 }
 declare class IdentityManager {
     private deviceId;
@@ -570,6 +576,7 @@ declare class IdentityManager {
     private lastName;
     private dateOfBirth;
     private gender;
+    private zipCode;
     private apiClient;
     private secureStorage;
     private debug;
@@ -641,7 +648,6 @@ type NotificationsEnvironment = "sandbox" | "production";
 interface NotificationsConfig {
     debug?: boolean;
     environment?: NotificationsEnvironment;
-    apiBaseUrl?: string;
 }
 
 declare const NOTIFICATIONS_ERROR_CODES: {
@@ -748,7 +754,6 @@ interface HandlersConfig {
 }
 interface NotificationsManagerConfig {
     appKey: string;
-    apiBaseUrl?: string;
     debug?: boolean;
     environment?: NotificationsConfig["environment"];
 }
@@ -1632,8 +1637,25 @@ declare class OnboardingError extends PaywalloError {
 declare const ONBOARDING_ERROR_CODES: {
     readonly NOT_INITIALIZED: "ONBOARDING_NOT_INITIALIZED";
     readonly INVALID_STEP_NAME: "ONBOARDING_INVALID_STEP_NAME";
+    readonly INVALID_ORDER: "ONBOARDING_INVALID_ORDER";
 };
 
+/** Payload sent with onboarding.step events. */
+interface OnboardingStepPayload {
+    step_name: string;
+    /** Ordem de exibição do step (aceita decimais, ex: 2.1 para variantes A/B). Obrigatório. */
+    order: number;
+    variant_key?: string;
+    time_on_prev_s?: number;
+}
+interface OnboardingStepOptions {
+    variantKey?: string;
+    timeOnPrevS?: number;
+}
+interface OnboardingCompleteOptions {
+    variantKey?: string;
+}
+
 /**
  * Minimal surface the OnboardingManager needs from the unified event pipeline.
  * `PaywalloClient` satisfies this interface (forwarding to
@@ -1661,42 +1683,26 @@ declare class OnboardingManager {
      * Saves the step name internally for implicit drop detection on the backend.
      *
      * @param stepName - Unique name for this onboarding step.
-     * @param order - Optional explicit display order (accepts decimals, e.g. 2.1 for A/B variants).
+     * @param order - Ordem de exibição do step. Obrigatório. Aceita decimais (ex: 2.1 para variantes A/B).
+     *   Deve ser um número finito e não-negativo. O servidor faz o floor — não arredondar aqui.
      */
-    step(stepName: string, order?: number): Promise<void>;
+    step(stepName: string, order: number, options?: OnboardingStepOptions): Promise<void>;
     /**
      * Tracks successful completion of the onboarding flow.
      * Marks the flow as finished.
      */
-    complete(): Promise<void>;
-    /**
-     * Tracks an explicit drop (abandonment) at the given step.
-     * Marks the flow as finished.
-     *
-     * @param stepName - The step name where the user dropped off.
-     */
-    drop(stepName: string): Promise<void>;
+    complete(options?: OnboardingCompleteOptions): Promise<void>;
     /** Returns the last step name seen, or null if no step was tracked yet. */
     getLastStep(): string | null;
-    /** Returns whether the flow has been marked as finished (complete or drop). */
+    /** Returns whether the flow has been marked as finished (complete). */
     isFinished(): boolean;
     private emit;
     private assertConfig;
     private validateStepName;
+    private validateOrder;
 }
 declare const onboardingManager: OnboardingManager;
 
-/** Payload sent with onboarding.step events. */
-interface OnboardingStepPayload {
-    step_name: string;
-    /** Optional explicit order (accepts decimals, e.g. 2.1 for A/B variants). */
-    order?: number;
-}
-/** Payload sent with onboarding.drop events. */
-interface OnboardingDropPayload {
-    step_name: string;
-}
-
 interface PaywallContextValue {
     nodes: Record<string, PaywallNode>;
     rootId: string;
@@ -1863,9 +1869,8 @@ interface UseOfferingsResult {
 declare function useOfferings(ids?: string[]): UseOfferingsResult;
 
 interface UseOnboardingResult {
-    step: (stepName: string, order?: number) => Promise<void>;
-    complete: () => Promise<void>;
-    drop: (stepName: string) => Promise<void>;
+    step: (stepName: string, order: number, options?: OnboardingStepOptions) => Promise<void>;
+    complete: (options?: OnboardingCompleteOptions) => Promise<void>;
 }
 /**
  * React hook that exposes bound onboarding tracking methods.
@@ -2017,4 +2022,4 @@ declare function hasVariables(text: string): boolean;
 
 declare const Paywallo: IPaywalloClient;
 
-export { type AllPlansResponse, ApiClient, type ApiClientConfig, type AttributionCapture, AttributionTracker, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedOfferings, type CachedPlans, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, type DeviceTokenRegistration, PURCHASE_ERROR_CODES as ERROR_CODES, type EmergencyPaywallResponse, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IPushBridge, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, MetaBridge, NOTIFICATIONS_ERROR_CODES, NativePushBridge, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type NotificationEventType, type NotificationListener, type NotificationPayload, NotificationsError, NotificationsManager, ONBOARDING_ERROR_CODES, type Offering, type OfferingProduct, OfferingService, type OfferingServiceConfig, type OfflineQueueConfig, type OnboardingDropPayload, OnboardingError, OnboardingManager, type OnboardingStepPayload, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type Plan, PlanCache, type PlanProduct, PlanService, type PlanServiceConfig, type PlansResponse, type PrePromptHandle, type PrePromptOptions, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type PushPermissionStatus, type PushPlatform, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult$1 as RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, attributionTracker, createPurchaseError, Paywallo as default, detectDeviceLanguage, getActiveRouteName, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, metaBridge, nativeStoreKit, networkMonitor, notificationsManager, offeringService, offlineQueue, onboardingManager, parseVariables, planCache, planService, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, useOfferingPurchase, useOfferings, useOnboarding, usePaywallContext, usePaywallo, usePaywalloScreenTracking, usePlanPurchase, usePlans, useProducts, usePurchase, useSubscription };
+export { type AllPlansResponse, ApiClient, type ApiClientConfig, type AttributionCapture, AttributionTracker, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedOfferings, type CachedPlans, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, type DeviceTokenRegistration, PURCHASE_ERROR_CODES as ERROR_CODES, type EmergencyPaywallResponse, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IPushBridge, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, MetaBridge, NOTIFICATIONS_ERROR_CODES, NativePushBridge, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type NotificationEventType, type NotificationListener, type NotificationPayload, NotificationsError, NotificationsManager, ONBOARDING_ERROR_CODES, type Offering, type OfferingProduct, OfferingService, type OfferingServiceConfig, type OfflineQueueConfig, OnboardingError, OnboardingManager, type OnboardingStepPayload, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type Plan, PlanCache, type PlanProduct, PlanService, type PlanServiceConfig, type PlansResponse, type PrePromptHandle, type PrePromptOptions, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type PushPermissionStatus, type PushPlatform, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult$1 as RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, attributionTracker, createPurchaseError, Paywallo as default, detectDeviceLanguage, getActiveRouteName, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, metaBridge, nativeStoreKit, networkMonitor, notificationsManager, offeringService, offlineQueue, onboardingManager, parseVariables, planCache, planService, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, useOfferingPurchase, useOfferings, useOnboarding, usePaywallContext, usePaywallo, usePaywalloScreenTracking, usePlanPurchase, usePlans, useProducts, usePurchase, useSubscription };