Set Up the External Install Flow

The external install flow lets you trigger a Wix app install flow from outside the App Market, editor, or site dashboard, as well as extend the standard install flow with a post-install redirect and state tracking.

This article guides you through building the Wix app installer URL and implementing the callback handler to handle the post-install redirect and manage state.

The end result will be:

  • A Wix app installer URL that includes your callback URL and custom state.
  • A callback handler that receives the redirect, verifies the install succeeded, and uses the state you passed.

Step 1 | Build the Wix app installer URL

This step builds the Wix app installer URL with an appId and postInstallationUrl.

At the end of this step, you have a Wix app installer URL that supports redirects and any query parameters you add.

To build the Wix app installer URL:

  1. Get your appId from the app dashboard. On your app's home page, click More Actions and select View ID & keys.

  2. Choose your callback URL. Use a route on your server that handles the redirect.

  3. Add state to your callback URL. State is custom data you want to pass through the install flow, such as a user ID or return path. Add it as query parameters to your callback URL.

    The following example creates the callback URL and adds a state object as a query parameter:

    Copy

Important: If your state contains sensitive data, encrypt it before adding it to the URL.

  1. Encode the callback URL with encodeURIComponent.

  2. Build the Wix app installer URL with appId and set the postInstallationUrl parameter to your encoded callback URL. 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, such as by clicking on a button, it will trigger the external install flow.

The example below shows the complete code for building the Wix app installer URL.

Copy

Step 2 | Build the callback handler

This step implements the callback handler at your callback URL. After a site visitor completes the standard install flow, Wix redirects them to your callback URL. Wix appends query parameters to the URL and preserves any query parameters you added.

At the end of this step, you have a working callback handler and access to the query parameters and state you passed.

The following examples use a Node.js server with Express. If you use another framework or language, define a GET handler for your callback path and process the query parameters in the way your stack supports. You can also read the parameters client-side from the page URL using browser APIs.

Important: Your callback handler endpoint must use HTTPS.

To build the callback handler:

  1. Define a GET route for the path that matches your postInstallationUrl and read the query parameters. The following example registers the route and reads the query parameters from the request.

    Copy

  2. Verify the install succeeded. If instanceId is missing, the install failed or the Wix user canceled. The following example redirects to a cancellation page when instanceId is missing:

    Copy

  3. Use the query parameters and state as needed.

The example below shows the complete callback handler:

Copy

See also

Did this help?