The external install flow lets you trigger a Wix app installation from outside the Wix App Market, editor, or site dashboard. For example, from a published Wix site or non-Wix site. When triggered externally, Wix supports the functionality to specify a post-installation redirect, track custom state, and provides OAuth credentials to simplify integrating external app services with Wix sites.
To support the external install flow:
When a site visitor navigates to the URL, the following flow starts:
The external install flow also supports custom state, which is data you can pass as query parameters in the callback URL. Wix preserves your state throughout the external install flow and returns it to the callback handler.
Learn more about setting up the external install flow.
To start the external install flow, you must build and expose an installation URL. Build the URL by appending query parameters to the base URL using standard query string syntax:
The installation URL supports the following query parameters:
| Query parameter | Required | Description |
|---|---|---|
appId | Yes | The app ID of the app you want to install. Triggers the standard install flow for the specified app. |
postInstallationUrl | No | Your callback URL, which you can specify at runtime. After the install completes, Wix redirects the Wix user to this URL and appends its own query parameters. Wix also preserves any query parameters you include. |
Important:
The postInstallationUrl must be an encoded URI component.
After the install completes, Wix redirects the Wix user to your postInstallationUrl and appends query parameters. Implement a callback handler to receive and process them.
Important: Your callback handler method must use HTTPS.
The following table describes the query parameters Wix appends to the redirect URL:
| Query parameter | Description |
|---|---|
appId | Your Wix app ID. |
tenantId | The ID of the Wix site that installed the app. |
instanceId | A unique ID for this app installation. |
| Custom state | Query parameters you included in the postInstallationUrl. |
Important: The instanceId is a permanent credential for this app-site connection. Store it securely.
To verify that your app installed successfully, confirm that an instanceId exists.
Use the instanceId from your callback handler to create OAuth access tokens that grant access to the permissions you've defined in your app dashboard and enable your backend to call Wix APIs on behalf of the installed app.