Troubleshooting
Resolve common setup, Experience delivery, and purchase problems.
Use Connect your app, customer activity, and your SDK’s logs to locate an integration problem. Start with the symptom below.
| Symptom | Start here |
|---|---|
| The app never shows Connected | SDK connection |
| Events arrive, but no Experience appears | Experience delivery |
| An edited screen does not appear | Published updates |
| Activity appears under the wrong customer | Customer identity |
| A purchase succeeds, but access stays locked | Purchases and access |
| A metered action is denied | Quotas and credits |
SDK connection
Initialize the SDK before sending events or checking access. Use the publishable key from the same App and platform you have open in Nuxie. For a development build, use its Debug builds key (pk_test_). Cross-platform SDKs use the key for the platform running the app.
Connected means the SDK reached Nuxie. If it does not appear:
- Check initialization errors in the app’s logs.
- Confirm the device has network access to
https://i.nuxie.ai. - Keep the SDK’s default service host. A test key selects test data on the normal Nuxie service; you don’t need a separate development host.
- Follow the native setup steps in your framework’s guide, then rebuild the app if you changed its native dependencies.
GET /status can check a key independently of the SDK. A 200 response includes the App and environment; 401 means the key is missing, invalid, or revoked. This check does not mark the SDK as Connected. See the REST API.
Experience delivery
An event can be recorded without showing an Experience. Presentation requires a published Experience whose trigger, audience, schedule, and re-entry rules match the customer.
Open the customer profile for the ID returned by your SDK, then check:
| Check | What to look for |
|---|---|
| Event | The exact event name configured for the trigger, including spelling and case |
| Publication | A published Version in the same App and environment as the key |
| Availability | The Experience is live, not paused or outside its delivery schedule |
| Audience | The customer’s properties and Segment memberships match the rules |
| Re-entry | The customer can enter again under the configured frequency |
| Journey | Whether the customer entered, reached a screen, or exited before presentation |
For a one-time Experience, repeat testing with a separate test identity or change the test Experience’s re-entry policy. Calling a trigger again does not override the policy.
$experience_shown confirms presentation. $experience_errored, $experience_artifact_load_failed, and $products_unavailable provide failure details. Use the system event reference and Journey history to interpret them.
Published updates
Saving a draft does not update the installed app. Publish the edited Project to the intended target, then start a new Journey that meets its delivery rules.
An in-progress Journey can continue using its existing Version. Compare the Version in customer activity with the one you published. See Versions and updates.
The SDK selector in these docs only changes the examples and navigation. It does not change your App’s platform or environment.
Customer identity
Use your application’s stable account ID when the customer signs in. Send the same ID to your billing provider when that provider supplies access. On sign-out, reset the SDK before another person uses the app.
If activity appears split between profiles, compare the actual IDs used by the app, your server, and the provider. An email address and an internal account ID are different identities even when they belong to the same person.
Let the SDK manage anonymous identity and linking. Don’t identify multiple people as guest or anonymous: a shared ID would combine their activity and access. See your SDK reference for identity and reset methods.
Purchases and access
A completed checkout, a verified purchase, and Feature access are separate results. Check them in order:
- Confirm the store or billing provider reports a successful purchase rather than pending, cancelled, or failed checkout.
- Confirm the purchase belongs to the expected App, environment, Product, and customer.
- Open the Product’s grants and confirm it grants the Feature your app checks.
- Check whether the native purchase or connected provider has synchronized with Nuxie.
- Refresh access through the SDK and inspect its returned decision.
The Feature key must match the grant. Use allowed to decide access; HTTP 200 alone does not mean the customer has it. After reinstalling or moving devices, use the SDK’s restore operation for store purchases.
For a paywall that cannot load Products, check the store connection and synchronized catalog, then follow the store-specific setup: App Store Connect or Google Play.
Quotas and credits
A balance check does not reserve units. Submit a consumption request before starting the paid action and read its accepted decision. The final successful use can leave a zero balance.
If consumption is denied, check the Feature key, quantity, customer identity, entity scope when used, and available allowance. Reuse the same operation ID when retrying the same action. A new ID represents another action and may spend units again.
See Metered usage for the full workflow and the consumption endpoint for response fields.
Information to include when asking for help
Include the SDK and version, platform and OS version, test or live environment, steps to reproduce, and the relevant error code. For an HTTP failure, include its status and X-Request-Id when available. For an Experience, include the Version and Journey involved.
Remove credentials, purchase evidence, and customer data from shared logs. Your SDK’s logging configuration can help capture a focused reproduction; see iOS logging or your SDK reference.