---
title: "App Installation Wizard"
description: "Multi-step install flow that creates user fields, registers placements, finalises the installation, and celebrates with confetti."
canonical_url: "https://bitrix24.github.io/b24jssdk/docs/examples/app-installation-wizard"
last_updated: "2026-06-02"
---
# App Installation Wizard

> Multi-step install flow that creates user fields, registers placements, finalises the installation, and celebrates with confetti.

> [!NOTE]
> **Required scopes** depend on what the wizard does — at minimum `crm`, `user_brief`, `userfieldconfig`, `placement`.

A Bitrix24 application is "installing" between when the user accepts the install dialog and when the app calls `installFinish()`. During that window you can provision custom fields, register placements, seed app options — anything the app needs before it greets the user. This recipe shows the structure of such a flow.

## Components Used

- [`B24Button`](https://bitrix24.github.io/b24ui/raw/docs/components/button.md) — start / retry / finish actions.
- [`B24Progress`](https://bitrix24.github.io/b24ui/raw/docs/components/progress.md) — visual progress bar.
- [`ProseH1`](https://bitrix24.github.io/b24ui/raw/docs/typography/headers-and-text.md#heading-1) / [`ProseP`](https://bitrix24.github.io/b24ui/raw/docs/typography/headers-and-text.md#paragraph) — title and status text.
- [`ProsePre`](https://bitrix24.github.io/b24ui/raw/docs/typography/code.md#inline-code) — debug / log output.
- [`useConfetti`](https://bitrix24.github.io/b24ui/raw/docs/composables/use-confetti.md) — closing animation.

## Flow

```ts
import { initializeB24Frame, type B24Frame } from '@bitrix24/b24jssdk'

let $b24: B24Frame

async function provision(): Promise<void> {
  // Wrap related steps in a batch so they hit a single round-trip
  await $b24.actions.v2.batch.make({
    calls: {
      addUserField: {
        method: 'userfieldconfig.add',
        params: {
          moduleId: 'crm',
          field: { ENTITY_ID: 'CRM_DEAL', FIELD_NAME: 'UF_CRM_DEAL_DEMO', USER_TYPE_ID: 'string' }
        }
      },
      bindPlacement: {
        method: 'placement.bind',
        params: { PLACEMENT: 'CRM_DEAL_LIST_MENU', HANDLER: '/embedded/menu' }
      }
    },
    options: {
      isHaltOnError: true,
      requestId: 'install:provision'
    }
  })
}

async function run() {
  $b24 = await initializeB24Frame()

  if (!$b24.isInstallMode) {
    // Already installed — render the regular UI
    return
  }

  await provision()
  await $b24.installFinish()
  // celebrate with useConfetti() ...
}

run().catch(console.error)
```

`installFinish()` throws `Error('Application was previously installed. You cannot call installFinish')` when the application is no longer in install mode — guard with `isInstallMode`.

## Full Source

See [bitrix24/b24sdk-examples](https://github.com/bitrix24/b24sdk-examples) for the complete wizard with progress UI, retry, and confetti.

## Sitemap

See the full [sitemap](/b24jssdk/sitemap.md) for all pages.