Skip to main content

Flows: Quick start

In this guide, you’ll learn how to use Dopt in a web app to develop your first flow by creating a modal that announces a new feature.

1. Sign up for a free Dopt account​

To get a free Dopt account, sign up here.

2. Identify users to Dopt​

Dopt requires you to identify users so we can keep track of where that user is in your flows and also allow you to target users via user or group properties.

You’ll need your users API key to start identifying users. You can retreive that by going to the Settings page and then navigating to Environments. We’ll use the Development environment so click Development and then the Generate API key button. After the key is generated, copy it to a safe place.

For this example, we’ll identify a user using the users API via a cURL command:

curl 'https://users.dopt.com/identify' \
 -X POST \
 -H 'Content-Type: application/json' \
 -H 'x-api-key:$USERS_API_KEY' \
 -d '{
  "identifier": "example_user",
  "properties": {
    "name": "Example User",
    "email": "user@example.com"
  }
}'

We’ve now identified a user called example_user with a name and an email property.

3. Create a flow​

We’ll create a flow in Dopt to represent our announcement.

Navigate to the flows page and click the Create flow button. Name your flow Announcement and set the identifier to announcement.

In the flow, drag a modal block onto the canvas. Draw a path from the start block to the modal block. Draw another path from the modal block to the finish block. When prompted, name this path complete.

Your flow should look like this:

Flow

4. Create the example app​

Run the following command in your terminal:

npm create @dopt/example@latest -- --template quick-start

This will create a new project in a folder named dopt-example-quick-start.

Next, run the following commands to start the app:

cd dopt-example-quick-start
npm run dev

5. Install Dopt​

Install the Dopt SDK​

Run the following command to install the Dopt React SDK:

npm install @dopt/react

Initialize Dopt​

We now need to initialize Dopt by adding the DoptProvider to the example app.

First, you’ll need your blocks API key. You can retreive that by going to the Settings page and then navigating to Environments. We’ll use the Development environment so click Development and then copy the API key to a safe place.

Open src/main.tsx in the project and import DoptProvider from @dopt/react. Wrap the provider around the <App /> element. The provider requires us to define userId, apiKey, and flows.

  • Set userId to example_user. This is the user we identified to Dopt in step 2.
  • Set apiKey to the blocks API key you retreived earlier.
  • Set flows to { announcement: 'uncommitted' }. This will initialize Dopt with the Announcement flow we created in step 3 and point it to the uncommitted version of the flow.

Your final code should look like this:

src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';

import { DoptProvider } from '@dopt/react';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <DoptProvider
      userId="example_user"
      apiKey="YOUR_BLOCKS_API_KEY"
      flows={{ announcement: 'uncommitted' }}
    >
      <App />
    </DoptProvider>
  </React.StrictMode>
);

6. Add the announcement modal​

Install the Dopt modal component​

Run the following command to install the react modal component:

npm install @dopt/react-modal

Render the modal​

We can now add our modal to the page.

Open src/App.tsx in the project and import the default export Modal and useModal from @dopt/react-modal.

Instantiate the useModal hook by passing in the identifier of the modal block you created in step 3.

const modal = useModal('announcement.YOUR_MODAL_BLOCK_ID');

Add the modal component to the return statement:

<Modal.Root active={modal.active}>
  <Modal.Overlay />
  <Modal.Content>
    <Modal.Header>
      <Modal.Title>{modal.title}</Modal.Title>
      <Modal.DismissIcon onClick={modal.dismiss} />
    </Modal.Header>
    <Modal.Body>{modal.body}</Modal.Body>
    <Modal.Footer>
      <Modal.DismissButton onClick={modal.dismiss}>
        {modal.dismissLabel}
      </Modal.DismissButton>
      <Modal.CompleteButton onClick={modal.complete}>
        {modal.completeLabel}
      </Modal.CompleteButton>
    </Modal.Footer>
  </Modal.Content>
</Modal.Root>

Your final code should look like this:

src/App.tsx
import Modal, { useModal } from '@dopt/react-modal';

function App() {
  const modal = useModal('announcement.YOUR_MODAL_BLOCK_ID');

  return (
    <>
      <h1>Dopt example app</h1>
      <p>
        Need help? Reach out via <a href="mailto:support@dopt.com">email</a> or{' '}
        <a href="https://www.dopt.com/slack">Slack</a>.
      </p>

      <Modal.Root active={modal.active}>
        <Modal.Overlay />
        <Modal.Content>
          <Modal.Header>
            <Modal.Title>{modal.title}</Modal.Title>
            <Modal.DismissIcon onClick={modal.dismiss} />
          </Modal.Header>
          <Modal.Body>{modal.body}</Modal.Body>
          <Modal.Footer>
            <Modal.DismissButton onClick={modal.dismiss}>
              {modal.dismissLabel}
            </Modal.DismissButton>
            <Modal.CompleteButton onClick={modal.complete}>
              {modal.completeLabel}
            </Modal.CompleteButton>
          </Modal.Footer>
        </Modal.Content>
      </Modal.Root>
    </>
  );
}

export default App;

7. See everything in action​

Navigate to http://localhost:5173 and you should see a modal rendered on the page.

You’ve accomplished quite a few things!

  1. You’ve provided user and flow context to the DoptProvider so Dopt knows what state to serve
  2. You’ve bound the visibility of the modal to the state of the modal block using useModal
  3. You’ve bound the content of the modal to content defined in the modal block
  4. You’ve bound the modal’s actions to state transitions provided by useModal

You can edit the modal block in the announcement flow to see content updated in the example app after a refresh.

You can click the Complete or Dismiss buttons and the modal will disappear and won’t show again because the state of the modal block has been updated.

You can reset the state of the flow with the following cURL command:

curl "https://blocks.dopt.com/v2/flow/announcement/reset?userIdentifier=example_user&version=0" \
 -X POST \
 -H "x-api-key:$YOUR_BLOCKS_API_KEY" \
 -H "Content-Type: application/json" \
 -d "{}"

Next steps​