About the App Install Flow

When a Wix user adds an app to a site, they trigger the Wix app install flow. This flow includes selecting the designated site and granting app permissions. You can start the install flow from inside Wix or externally. When started externally, you can extend the flow by redirecting the Wix user after installation and preserving custom state throughout.

Standard install flow

The standard install flow is the default installation path when a Wix user adds an app from in the Wix ecosystem. Wix users can add apps to a site from the Wix App Market, editor, or site dashboard. Wix handles the full flow from trigger to installation.

When installing an app:

• Wix App Market: Wix prompts the Wix user to select the intended site and grant permissions.
• Site dashboard and editors: The Wix user triggers the install from a specific site, so Wix only prompts them to grant permissions.

When completed, Wix redirects the Wix user to the site dashboard or the editor of the site they chose during the install flow.

External install flow

The external install flow is when a Wix user starts installing your app from outside the App Market, editor, or site dashboard. For example, from a published Wix site or a non-Wix website.

You provide the Wix app installer URL, such as by attaching it to a button on a site. When a site visitor navigates to the URL, the following flow starts:

1. Wix initiates the standard install flow.
2. After install, Wix redirects the site visitor to your callback URL and appends query parameters.
3. Your callback handler receives the redirect, verifies the install succeeded, and handles the query parameters.

The external install flow also supports state, custom data you can pass as query parameters in the callback URL. Wix preserves your state throughout the external install flow and returns it in the callback.

Learn more about setting up the external install flow.

Use cases for the external install flow

Use the external install flow when:

• A site visitor starts the install from a live or external site, such as a published Wix site, and you want to redirect them back after install.
• You want to track state across the install flow. For example, a campaign landing page where Wix users install the app, get redirected to a thank-you page, and you receive campaign or visitor details in the callback.
• Your private app has no frontend extensions, so Wix users have nothing to interact with after installing. Use the external install flow to redirect them to somewhere useful such as an onboarding or confirmation page.
• You're building a self-hosted app that needs to call Wix APIs. Use the external install flow to capture the instanceId in the callback and use it to authenticate API calls.

Wix app installer URL

To set up the external install flow, you must build and provide a Wix app installer URL. Build the Wix app installer URL by appending query parameters to the base URL using standard query string syntax:

The base URL supports the following query parameters:

What Wix sends in the redirect

To receive and process what Wix sends in the redirect, implement a callback handler at your postInstallationUrl.

After the install completes, Wix redirects the Wix user to your postInstallationUrl and appends the following parameters:

To verify that your app installed successfully, confirm that an instanceId exists.

Tracking installs

An app is recorded as successfully installed when a Wix user completes the standard install flow. You can view and manage app installations in the app dashboard.

To track Wix users who started but didn't complete the install flow, set up custom events for Google Analytics.

See also

• Adding an app to a site
• Set Up the External Install Flow
• Configure Post-installation Navigation Settings