> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Set Up the External Install Flow

## Article: Set Up the External Install Flow

## Article Link: https://dev.wix.com/docs/build-apps/launch-your-app/app-distribution/install-your-app/set-up-the-external-install-flow.md

## Article Content:

# Set Up the External Install Flow

The [external install flow](https://dev.wix.com/docs/build-apps/launch-your-app/app-distribution/install-your-app/about-the-external-install-flow.md) 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](https://dev.wix.com/docs/build-apps/launch-your-app/app-distribution/install-your-app/about-app-installation.md#standard-install-flow) with a post-install redirect and state tracking.   

This article guides you through building the [installation URL](https://dev.wix.com/docs/build-apps/launch-your-app/app-distribution/install-your-app/about-the-external-install-flow.md#about-the-installation-url) and implementing the callback handler to handle the post-install redirect and manage state.

The end result will be:

* An [installation URL](https://dev.wix.com/docs/build-apps/launch-your-app/app-distribution/install-your-app/about-the-external-install-flow.md#about-the-installation-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 installation URL

This step builds the installation URL with an `appId` and `postInstallationUrl`.

At the end of this step, you have an installation URL that supports redirects and any query parameters you add.

To build the installation URL:

1. Get your `appId` from the [app dashboard](https://manage.wix.com/account/custom-apps). 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:

    ```js
    const callbackUrl = new URL('https://yoursite.com/wix/connect')
    const state = { userId: '<USER_ID>', returnTo: '/dashboard' }
    callbackUrl.searchParams.set('state', JSON.stringify(state))
    ```

<blockquote class="important">

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

</blockquote>

4. Encode the callback URL with [encodeURIComponent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent).

5. Build the installation URL with `appId` and set the `postInstallationUrl` parameter to your encoded callback URL. Provide the installation 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 installation URL.

```js
const appId = '<YOUR_APP_ID>'
const callbackUrl = new URL('https://yoursite.com/wix/connect')
const state = { userId: '<USER_ID>', returnTo: '/dashboard' }

// Encrypt sensitive data before adding to URL

callbackUrl.searchParams.set('state', JSON.stringify(state))

const postInstallationUrlEncoded = encodeURIComponent(callbackUrl)
const installerUrl = `https://www.wix.com/app-installer?appId=${appId}&postInstallationUrl=${postInstallationUrlEncoded}`
```


## 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](https://dev.wix.com/docs/build-apps/launch-your-app/app-distribution/install-your-app/about-the-external-install-flow.md#what-wix-sends-in-the-redirect) 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](https://developer.mozilla.org/en-US/docs/Web/API/Location). 
 
<blockquote class="important">

__Important:__
Your callback handler endpoint must use HTTPS.
</blockquote>

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.

    ```js
    app.get('/wix/connect', async (req, res) => {
      const { appId, tenantId, instanceId, state } = req.query
    })
    ```

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:

    ```js
    if (!instanceId) {
      // Log the failure server-side if needed
      return res.redirect('/install-cancelled')
    }
    ```

3. Use the query parameters and state as needed.

The example below shows the complete callback handler:

```js
app.get('/wix/connect', async (req, res) => {
  const { appId, tenantId, instanceId, state } = req.query

  if (!instanceId) {
    // Log the failure server-side if needed
    return res.redirect('/install-cancelled')
  }

  const parsedState = JSON.parse(state)
  // Implement business logic to use the query parameters
})
```

## See also

- [About the External Install Flow](https://dev.wix.com/docs/build-apps/launch-your-app/app-distribution/install-your-app/about-the-external-install-flow.md)
- [About App Installation](https://dev.wix.com/docs/build-apps/launch-your-app/app-distribution/install-your-app/about-app-installation.md)