From 7c5e5ec8aac130ec113bd7a06f6fb1bf84ccf168 Mon Sep 17 00:00:00 2001 From: Jorge Armando Mejia Date: Mon, 23 Feb 2026 09:37:45 -0600 Subject: [PATCH 1/2] docs: add Expo integration and purchase/subscription guidance --- skills/qonversion-react-native/SKILL.md | 66 ++++++++ .../agents/openai.yaml | 4 + .../references/react-native-expo.md | 150 ++++++++++++++++++ 3 files changed, 220 insertions(+) create mode 100644 skills/qonversion-react-native/SKILL.md create mode 100644 skills/qonversion-react-native/agents/openai.yaml create mode 100644 skills/qonversion-react-native/references/react-native-expo.md diff --git a/skills/qonversion-react-native/SKILL.md b/skills/qonversion-react-native/SKILL.md new file mode 100644 index 0000000..3978630 --- /dev/null +++ b/skills/qonversion-react-native/SKILL.md @@ -0,0 +1,66 @@ +--- +name: qonversion-react-native +description: Integrate, debug, or migrate Qonversion SDK in React Native and Expo apps, including setup, initialization, offerings/products fetch, purchase/restore flows, entitlement checks, user identify/logout mapping, and major-version API migration handling. Use when tasks mention @qonversion/react-native-sdk, react-native-qonversion, subscriptions, entitlements, paywalls, App Store/Google Play purchases, or Expo prebuild/dev-client requirements. +--- + +# Qonversion React Native + +## Overview + +Use this skill to implement or fix Qonversion subscription flows in React Native and Expo projects. + +Read `references/react-native-expo.md` first, then apply only the sections required by the user request. + +## Workflow + +1. Detect project mode +- Confirm if app is Expo managed, Expo prebuild + dev client, or bare React Native. +- If Expo Go is being used for native purchase testing, move to dev client / native build path. + +2. Confirm SDK and version +- Check `package.json` for `@qonversion/react-native-sdk` (or older `react-native-qonversion`). +- If API usage does not match installed major version, use migration guidance from the references file. + +3. Initialize SDK early +- Initialize Qonversion once during app bootstrap. +- Use subscription-management launch mode. +- Keep project key outside hardcoded literals when possible. + +4. Bind identity lifecycle +- On login: call `identify(userId)`. +- On logout/account switch: call `logout()`. +- Keep backend and Qonversion identity mapping consistent. + +5. Implement commerce flow +- Fetch offerings/products. +- Trigger purchase with explicit product model/options. +- Handle user-cancel path separately from real errors. +- Support restore flow for reinstalls/device changes. + +6. Resolve access by entitlements +- Use `checkEntitlements()` to gate premium features client-side. +- Treat server state as source of truth for protected backend access. + +7. Validate on devices +- Test with sandbox testers on iOS/Android. +- Verify success, cancellation, restore, expired, billing issue, and offline fallback behaviors. + +## Implementation Rules + +- Prefer typed wrappers in `services/` instead of using SDK calls directly in UI screens. +- Centralize purchase/restore/error handling in a single service module. +- Keep entitlement keys and product IDs as constants. +- Add telemetry around purchase start/success/failure/cancel/restore. +- For Expo projects, document whether feature needs prebuild/dev client. + +## Output Expectations + +When completing a task with this skill, deliver: +- Exact files changed. +- Version assumptions and migration notes. +- Test checklist for iOS and Android sandbox. +- Any Expo-specific constraints (Expo Go vs dev client/prebuild). + +## References + +- Core guide: `references/react-native-expo.md` diff --git a/skills/qonversion-react-native/agents/openai.yaml b/skills/qonversion-react-native/agents/openai.yaml new file mode 100644 index 0000000..f8541fb --- /dev/null +++ b/skills/qonversion-react-native/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Qonversion RN + Expo" + short_description: "Integra y depura Qonversion SDK en React Native y Expo" + default_prompt: "Implementa o corrige Qonversion SDK en React Native/Expo con setup, identify/logout, offerings, compras, restore y entitlements" diff --git a/skills/qonversion-react-native/references/react-native-expo.md b/skills/qonversion-react-native/references/react-native-expo.md new file mode 100644 index 0000000..ff5bc05 --- /dev/null +++ b/skills/qonversion-react-native/references/react-native-expo.md @@ -0,0 +1,150 @@ +# Qonversion + React Native + Expo Reference + +## 1) Install and bootstrap + +Primary package (current docs): + +```bash +npm install @qonversion/react-native-sdk +``` + +Initialize once at app startup: + +```ts +import Qonversion, { QonversionConfigBuilder, LaunchMode } from '@qonversion/react-native-sdk'; + +const config = new QonversionConfigBuilder( + process.env.EXPO_PUBLIC_QONVERSION_PROJECT_KEY ?? '', + LaunchMode.SUBSCRIPTION_MANAGEMENT +).build(); + +Qonversion.initialize(config); +``` + +If using custom networking route: + +```ts +const config = new QonversionConfigBuilder( + process.env.EXPO_PUBLIC_QONVERSION_PROJECT_KEY ?? '', + LaunchMode.SUBSCRIPTION_MANAGEMENT +) + .setProxyURL('https://your-proxy.example.com') + .build(); +``` + +## 2) Expo integration notes + +- Qonversion React Native SDK is a native module; do not rely on Expo Go for full purchase testing. +- Use Expo prebuild + dev client or EAS builds for iOS/Android purchase validation. +- Re-run native build after dependency or native config changes. + +Practical commands: + +```bash +npx expo prebuild +npx expo run:ios +npx expo run:android +``` + +or EAS: + +```bash +eas build --platform ios --profile development +eas build --platform android --profile development +``` + +## 3) Identity lifecycle + +Call after login: + +```ts +await Qonversion.getSharedInstance().identify(userSub); +``` + +Call at logout/account switch: + +```ts +await Qonversion.getSharedInstance().logout(); +``` + +Optionally map Qonversion id for backend correlation: + +```ts +const userInfo = await Qonversion.getSharedInstance().userInfo(); +const qonversionId = userInfo.qonversionId; +``` + +## 4) Offerings, products, purchases, restore + +Load offerings/products: + +```ts +const offerings = await Qonversion.getSharedInstance().offerings(); +const products = await Qonversion.getSharedInstance().products(); +``` + +Purchase: + +```ts +try { + const entitlements = await Qonversion.getSharedInstance().purchaseProduct(product); +} catch (e: any) { + if (e?.userCanceled) { + // user canceled + } else { + // real error + } +} +``` + +Restore: + +```ts +const entitlements = await Qonversion.getSharedInstance().restore(); +``` + +## 5) Entitlement checks + +Client-side gate: + +```ts +const entitlements = await Qonversion.getSharedInstance().checkEntitlements(); +``` + +Use entitlement renew-state data when available to branch UX for: +- will renew +- canceled but still active +- billing issue / grace period + +## 6) Version and migration cautions + +Qonversion docs include multiple React Native migration guides (4+, 6+, 6->7, 7->8 and later). Validate API names against installed major version before editing code. + +Examples of migration-sensitive areas: +- `purchaseProduct(...)` vs newer `purchase(purchaseModel)` patterns +- `updatePurchase(...)` signatures +- permission naming transitions to entitlement naming +- user property API renames + +When code and package major are mismatched: +1. Pin target major version. +2. Refactor to that API shape. +3. Smoke-test purchase, restore, and entitlement-check flows. + +## 7) Recommended production checks + +- iOS and Android sandbox tester flows pass. +- Cancel path does not show fatal error UX. +- Restore path reactivates access. +- Entitlement-based UI unlocks immediately after purchase. +- Backend protected routes still enforce server truth. +- Logs include purchase lifecycle events. + +## 8) Sources + +- Qonversion React Native SDK docs: https://documentation.qonversion.io/docs/docs/react-native-sdk +- Purchase and restore patterns: https://documentation.qonversion.io/docs/docs/making-purchases +- React Native migration guides: https://documentation.qonversion.io/docs/docs/react-native-8-migration-guide +- Entitlement checks: https://documentation.qonversion.io/docs/docs/check-permissions +- User identifiers: https://documentation.qonversion.io/docs/user-identifiers +- Offline mode: https://documentation.qonversion.io/docs/offline-sdk-mode From cb8b3bc2d537141b2387aa2645ae2d246b7308d2 Mon Sep 17 00:00:00 2001 From: Jorge Armando Mejia Date: Mon, 23 Feb 2026 09:43:31 -0600 Subject: [PATCH 2/2] Revise short description and default prompt in openai.yaml --- skills/qonversion-react-native/agents/openai.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/qonversion-react-native/agents/openai.yaml b/skills/qonversion-react-native/agents/openai.yaml index f8541fb..ec78514 100644 --- a/skills/qonversion-react-native/agents/openai.yaml +++ b/skills/qonversion-react-native/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Qonversion RN + Expo" - short_description: "Integra y depura Qonversion SDK en React Native y Expo" - default_prompt: "Implementa o corrige Qonversion SDK en React Native/Expo con setup, identify/logout, offerings, compras, restore y entitlements" + short_description: "Integrate and troubleshoot Qonversion SDK in React Native and Expo" + default_prompt: "Implement or fix Qonversion SDK in React Native/Expo with setup, identify/logout, offerings, purchases, restore, and entitlements"