userGist
Get started

Upgrade guides

Core, Web, Flutter, stable React Native, iOS, and Android are published at v0.1.4. Android is available on Maven Central under com.usergist:feedback; the Kotlin import namespace remains studio.usergist.feedback.

Expo uses the separate npm next channel, currently v0.2.0-beta.2 of @usergist/feedback-react-native. It remains a prerelease while signed-device acceptance is incomplete. Follow the Expo guide for that channel.

Deploying the UserGist API or dashboard does not publish SDK packages or update an app's installed dependency. After an SDK upgrade, verify the resolved version in your lockfile and rebuild the app.

Identity lifecycle: earlier stable SDKs → 0.1.4

For Expo, upgrade from 0.2.0-beta.1 to 0.2.0-beta.2 on next. Keep stable React Native on latest unless adopting the Expo integration.

  1. Install the new version and rebuild the native app; refresh iOS pods where required. For Web, rebuild and deploy the site with the updated package.
  2. Keep the existing backend account ID, including a verified guest ID, as externalId. Obtain its subject token from your authenticated backend and configure the SDK's token renewal provider.
  3. Observe confirmed identification before sending account-specific events. Native iOS 0.1.3 does not expose the new async completion methods; replacing a void call with a resolved promise does not confirm server acceptance.
  4. Update profile fields through set/unset instead of identifying on every property change. Keep the same identity when a guest registers with the same ID.
  5. On logout or account switch, wait for successful local reset before identifying the next account and applying its consent decisions. Verify restart and offline cleanup with the host app's push integration.

The backend requires previousSubjectToken to prove ownership when linking existing anonymous history. Updated SDKs supply it automatically. Older clients can receive HTTP 409 IDENTITY_PROOF_REQUIRED and must upgrade; resetting the installation is not a history-preserving workaround. Publishing SDKs or deploying the backend cannot update copies already installed by your users.

The identity guide includes the backend token endpoint, guest-account example, expiry handling, and platform-specific APIs.

Startup readiness across SDKs

The readiness controls are available in native iOS/Android, React Native/Expo, Flutter, and Web. Update the installed package and lockfile, initialize with presentationPaused: true (presentationPaused = true in Kotlin), then call resumePresentation() after the loaded screen and startup navigation are ready. Keep initialization at app launch so analytics and identity can start immediately.

Existing integrations default to unpaused presentation. Adopting the startup option and readiness callback is required to defer UI. Pause/resume does not require sign-in and does not dismiss an active SDK surface. Queued work is invalidated on consent revocation, reset, and user changes. Web direct-open methods return status: 'queued' when presentation is deferred.

Versioning policy

  • Patch (0.1.x) — bug fixes and additive SDK APIs. Check coordinated backend requirements; the identity release above requires upgrading older clients.
  • Minor (0.x.0) — new features. May add new method signatures, never remove existing ones.
  • Major (x.0.0) — breaking changes. Each major bump ships a migration guide on this page with codemods where possible.

SDKs normally ship as one aligned release train. A registry-only correction may advance one SDK by a patch version without changing the cross-platform feature matrix in PARITY.md.

iOS 0.1.0 → 0.1.1

Update the Swift package dependency to 0.1.1 or later and verify the resolved version before rebuilding. This fixes the crash when a feedback or survey rating includes endpoint labels; no integration API changes are required.

Simulator builds must keep signing enabled so the SDK can save its subject session in Keychain. Version 0.1.1 includes clearer diagnostics for Keychain error -34018. See the iOS setup guide.

iOS 0.1.1 → 0.1.2

Startup presentation readiness shipped in 0.1.2. Initialize at app launch with presentationPaused: true, then call resumePresentation() after startup loading and navigation finish. This prevents a startup campaign from occupying the splash controller before it can present your main screen. See the readiness examples.

The default remains unpaused for compatibility, so upgrading the package alone does not install the host readiness hook. Keep analytics initialization at launch; do not move the entire SDK to viewDidDisappear. Existing $app_open campaigns continue to work and wait behind the presentation gate.

React Native 0.1.0 → 0.1.1

Update @usergist/feedback-react-native to the stable npm latest channel, at least 0.1.1, then install iOS pods and rebuild. This removes an unused codegen declaration that referenced unpublished sources and could block native build setup. Existing native bridges and the core dependency are preserved.

Future migrations

Future releases follow Semantic Versioning. Any release requiring application changes will include a version-to-version guide here, an SDK changelog entry, and exact rollback guidance before the package is published. Subscribe to the changelog for release notices.

Flutter 0.1.2 → 0.1.3

Flutter 0.1.3 moved network warm-up out of initialization. Initialization completes after local hydration while session and mutation warm-up run in the background. The usual await UserGist.init(...) before runApp no longer waits for networking. Continue to initialize presentation paused and resume after host navigation. Do not make host rendering depend on consent, identity, or flush network responses.

iOS 0.1.2 → 0.1.3

The iOS 0.1.3 patch reads newly queued campaign instructions after app-open upload, so the first reopen can display a new message. Keep presentationPaused: true and resume after the main screen is visible. These fixes are included in the current release.