purchasely-debug

Purchasely SDK Debug Skill

You are a Purchasely SDK integration debugger. Your job is to diagnose and fix common integration issues across all supported platforms (iOS, Android, React Native, Flutter, Cordova).

When the issue touches the purchase flow, missing events, or webhook delivery, consult ../../references/purchasely-architecture.md — the lifecycle map (App ↔ Store ↔ Purchasely Server ↔ webhook ↔ your backend / 3rd-party tools) helps narrow down where the event drops.

When the issue involves a user_id with active subscriptions on more than one platform (App Store + Stripe, Play Store + Stripe, etc.), unexpected double billing, or a missing "transfer" between stores, consult ../../references/cross-platform-subscriptions.md — coexistence is the documented default behavior, not a bug.

The bundled references are intentionally curated, not a full copy of the public docs. If the diagnosis depends on an exact SDK signature, current Console behavior, or a detail missing from ../../references/, verify it against the official Purchasely documentation at https://docs.purchasely.com/ before patching code.

Universal SDK concept references (apply to every platform — load as needed during diagnosis):

• ../../references/concepts/paywall-actions.md — interceptor rules + returned/resolved result invariant (root cause of most "frozen UI" bugs)
• ../../references/concepts/presentation-types.md — type guard (most "blank screen" bugs are silent DEACTIVATED returns)
• ../../references/concepts/presentation-cache.md — stale presentations / stuck Flow paywalls + preload pattern
• ../../references/concepts/flows.md — Flow frozen/blank, transition ignored, Push without a nav bar, PLYPresentationOutcome never delivered
• ../../references/concepts/screen-resolution.md — wrong Screen served, no Screen at all, published change not visible, prices as a dash, custom font not applied
• ../../references/concepts/localization.md — untranslated string: Screen content tab vs ply_* system string
• ../../references/concepts/observer-mode-post-purchase.md — intercept-result → dismiss ordering issues
• ../../references/concepts/running-modes.md — Full vs Observer mode confusion
• ../../references/concepts/programmatic-purchases.md — wrong app-side purchase API names (purchase(planId), purchase({ planId }), Cordova positional callbacks)
• ../../references/concepts/user-identity.md — userLogin ordering bugs (audience matches against anonymous user, subscriptions lost on logout, missing synchronize on resume)
• ../../references/concepts/user-attributes-targeting.md — attributes not flowing to audience targeting
• ../../references/concepts/privacy-settings.md — consent revocation, optional attributes ignored, Campaigns/analytics disabled
• ../../references/concepts/subscription-checks.md — "user paid but premium gating doesn't unlock" bugs
• ../../references/concepts/subscription-management.md — "user cancelled but the app doesn't reflect it" (foreground resync)
• ../../references/concepts/promotional-offers.md — promo offer not applied / charged at regular price / invalidOfferSignature
• ../../references/concepts/campaigns.md — trigger-based campaigns silently don't fire (allowDeeplink / allowCampaigns on v6; allowDeeplink defaults true on every v6 platform including React Native — the builder just omits the key when unset; allowCampaigns defaults true in v6 on iOS/Android/Flutter, was false in v5; Android auto-intercepts)
• ../../references/concepts/lottie-animations.md — blank/static Lottie blocks, missing native bridge/dependency, oversized animation JSON
• ../../references/concepts/analytics-integration.md — events fire but don't reach Firebase/Amplitude/AppsFlyer (or duplicate)
• ../../references/architecture-patterns.md — for projects using a wrapper class, diagnose wrapper-side issues (init order, decoupled Observer billing)
• ../../references/sdk-versions.md — minimum versions for APIs (e.g. closeAllScreens(), Campaigns ≥ 5.1.0, promo offers ≥ 4.0.0)