Fix 'Setup Incomplete' Badge in Wix Studio Apps: Expert Guide

For Wix Studio app developers, guiding users through the initial setup process is crucial. The 'Setup incomplete' badge is a vital tool for this, signaling to site owners when their app requires further configuration. However, as a recent Wix Studio community forum topic highlighted, developers often face challenges with this badge failing to appear, even after diligently sending relevant Business Intelligence (BI) events.

Understanding the 'Setup Incomplete' Badge

The 'Setup incomplete' badge within the Wix site dashboard is designed to prompt users to complete essential steps for an app to function. As per Wix's BI event sample flows, once an app signals its general readiness for configuration (an app-level 'setup-finished' declaration), all new installations should display this badge until that specific site instance completes its unique setup.

The Forum's Challenge: A Developer's Misstep

A developer reported that for their public dashboard app (self-hosted backend, OAuth), the 'Setup incomplete' badge never showed. They had sent both APP_FINISHED_CONFIGURATION and APP_SETUP_FINISHED BI events, authorized with an instance access token of a test site, receiving 200 {} responses. Despite this, new installations lacked the badge, indicating a disconnect in how the app's setup status was being communicated to Wix.

The developer's attempts involved:

POST https://www.wixapis.com/apps/v1/bi-event
{
  "eventName": "APP_FINISHED_CONFIGURATION"
}

POST https://www.wixapis.com/apps/v1/bi-event
{
  "eventName": "APP_SETUP_FINISHED"
}

Clarifying BI Event Roles: App-Level vs. Instance-Level

The confusion often arises from the distinct roles of BI events in the app lifecycle:

APP_FINISHED_CONFIGURATION (or equivalent): This event, or a specific setting, typically serves as an app-level declaration by the developer. It tells Wix that the app, as a product, requires post-installation setup for every new user. This is the primary trigger for the 'Setup incomplete' badge to appear on new installs.
APP_SETUP_FINISHED: This event is sent by an individual app instance (on a specific Wix site) once the site owner has completed all necessary setup steps for that particular installation. It signals completion for that instance, leading to the removal of the 'Setup incomplete' badge for that specific site.

The forum developer's core issue likely stems from sending these events from a test site instance using an instance access token, which might inadvertently mark that specific instance as complete, rather than properly enabling the global 'requires setup' flag for their app.

Actionable Solutions: Ensuring Correct Badge Behavior

1. Enable Your App's Global Setup Requirement

The most critical step is to inform Wix that your app generally requires setup. This is typically a one-time declaration by the developer:

Wix Developer Center Configuration: Access your app's settings in the Wix Developer Center (dev.wix.com). Look for explicit options like "Requires Configuration," "Setup Steps," or similar checkboxes. Enabling this flag is the most direct way to instruct Wix to display the 'Setup incomplete' badge for all new installations of your app.
Review Sample Flows for App-Level Event: Re-examine the sample-flows.md documentation. Confirm if APP_FINISHED_CONFIGURATION is indeed intended as a global app-level event, and if so, understand the correct context (e.g., specific API call, different authentication) for sending it to declare your app's overall setup requirement.

2. Implement Instance-Specific Completion Judiciously

Once the global setup requirement is active, each installation will show the badge. Your app's backend should then manage its removal:

Send APP_SETUP_FINISHED Only When Setup is Complete: Ensure your backend sends the APP_SETUP_FINISHED event exclusively after a user has genuinely completed all required setup steps for their particular app instance. This event, authorized with the respective instance access token, will correctly remove the 'Setup incomplete' badge for that specific site.
Avoid Premature Signaling: Do not send APP_FINISHED_CONFIGURATION or APP_SETUP_FINISHED immediately upon installation or during initial testing if the setup is not truly complete. Prematurely sending APP_SETUP_FINISHED will remove the badge before the user sees it, defeating its purpose.

3. Rigorous Testing Protocol

Verify your implementation with these steps:

Install on a New Site: Install your app on a fresh Wix test site where it has never been installed before.
Verify Badge Appearance: Immediately check the site dashboard. The 'Setup incomplete' badge must be visible.
Complete Setup: Go through your app's configuration flow on the new site.
Verify Badge Removal: After completing setup and confirming your app's backend has sent APP_SETUP_FINISHED, verify the badge disappears from the site dashboard for that specific instance.

Conclusion

The 'Setup incomplete' badge is an indispensable component of a smooth onboarding experience for Wix Studio apps. The forum discussion underscores the importance of correctly understanding and implementing Wix's BI event system, particularly the distinction between app-level declarations and instance-specific completions. By adhering to these guidelines, developers can ensure their apps effectively communicate their status, leading to a better user experience and fewer support queries.

Wix Studio App Setup Badge: Troubleshooting 'Setup Incomplete' Display Issues