Skip to main content

Using Dopt

Set up

Create an API key

Now that you are logged in to Dopt you can generate API keys that will be used to authenticate requests made to Dopt’s APIs. Dopt provides two separate API keys: a blocks API Key and a users API key. The blocks API key is used to integrate with @dopt/react and the users API key is used to send requests to our users API.

Head over to Dopt’s setting page to generate the necessary API keys. Once you’ve generated a key you will be prompted to copy it to your clipboard as you will only be shown this key once. This is because the API key is a secret key that can perform any API request to Dopt. Accordingly, you should keep it somewhere safe/secure (e.g. a secret manager like AWS Secret Manager or GCP Secret Manager).

API requests made without authentication or using an incorrect key will return a 401 error.

Identify users

In order for Dopt to power experiences for your users, Dopt needs to be aware of those users and their properties.

Developers will need to identify users to Dopt using the Dopt users API.

info

API documentation for the Dopt users API can be found here.

We support two approaches for sending your user data to Dopt: individual identification and bulk identification. In both cases, we manage your user data via upsertion i.e. we provide a single set of APIs for both creating new users in Dopt and updating existing users.

Individual identification

You can use the identify API to send us data for a single user. If you've used a Customer Data Platform (CDP) like Segment before, this will be familiar to you. In practice, you might integrate individual identification code into your users CRUD handler.

API reference →

curl \
-H "Content-Type: application/json" \
-H "x-api-key:$USERS_API_KEY" \
-d '{ "name":"Joe McKenney", "email": "joe@dopt.com", "city": "Oakland" }' \
-X POST \
https://users.dopt.com/identify/123456789

We recommend you use a unique user identifier that won’t change for your identifier, such as a database ID from your organization’s internal systems.

note

We will provide SDKs for easier user identification in the very near future.

info

When you use the identify API in the browser the source’s write key is public because it runs in a user’s browser and can be accessed using the browser’s developer tools. If this is not acceptable to your organization, you can call Identify via the server which collect data from a server-based installation, and which are not accessible to the user.

Bulk identification

Many users have likely been created in your system before Dopt was integrated. To tell us about those users we offer a bulk identify API that allows you to send us data for many users at once. This endpoint allows you to identify up to 100 users at a time.

API reference →

curl -X POST https://users.dopt.com/identify/bulk \
-H "Content-Type: application/json" \
-H "x-api-key:HNWvcT78tyTwygnbzU6SW" \
-d '
[{
"identifier": "123456789",
"name":"Joe McKenney",
"email": "joe@dopt.com",
"city": "Oakland"
}, {
"identifier": "987654321",
"name": "Alon Bartur",
"email": "alon@dopt.com",
"city": "Oakland"
}]
'

Updating user properties

You can update user properties by using the identify API. Call the identify API with a user identifier and new or updated user properties. The user properties will be updated via upsertion: if the user property doesn’t exist, it will be created. If it does exist, it will be updated.

Creating a flow

There are a few steps to creating a flow.

  1. Determine requirements
  2. Create the flow
  3. Set targeting rules in the start block
  4. Design the flow logic using step and finish blocks

1. Determine requirements

The first step of creating a Flow is determining a few details about a flow you want Dopt to power in your product.

You should determine:

  • Targeting rules:
    • What user properties will I use to target the right set of users? → This will determine what user properties you’ll need to send Dopt and what the targeting rules in the start block will be.
  • Steps and flow logic:
    • What are the steps of the desired flow? → You’ll likely need 1 step block per step.
    • What’s the logic that connects the steps? → This will determine the paths between blocks.

2. Create the flow

To create a Flow, go to the flow page at https://app.dopt.com/flows and click the Create flow button.

This will bring you to the flow canvas with an start block, step block, and finish block created by default.

You can rename the flow and add a description by clicking on the flow name.

You can scroll the flow canvas by holding space bar and dragging the canvas or scroll using a mouse wheel/trackpad (holding shift while scrolling will scroll the canvas horizontally).

3. Set targeting rules

Click on the start block to open the detail pane. In the details pane you can set the expression for which users should qualify for this flow.

You can read more about start blocks and the targeting rules expression language here.

4. Design the flow logic using step and finish blocks

Now, for each step in your desired flow, create a step block.

To create a step block, drag a step block from the details panel onto the canvas.

You can drag and drop blocks to move them around.

Then connect the step blocks with paths to represent the flow logic. Do this by selecting a block and then dragging the edge from the bottom of the block to the other block.

Wherever you want the flow to end, you can add a finish block.

You can read more about step blocks, finish blocks, and paths here.

Now that your flow is created, developers can leverage the SDK to build the experience into your application.

Using the React SDK to create experiences

The Dopt React SDK offers a convenient framework-specific client for accessing Dopt's block model API, effectively allowing you to bind user flow state (defined in Dopt) to your UI.

The SDK lives in our open-source monorepo odopt.

It is published to NPM as @dopt/react

To get started using the React SDK, we would recommend going through its README.

Additionally, we generate documentation for the functions and types in the @dopt/react SDK.

Provide feedback

Contributing

All contributions are welcome! Feel free to open a pull request.

Testing

We support two approaches for testing your integration with Dopt: local/offline and live against our APIs. These “modes” are configured through your usage of the <DoptProvider />.

info

Generated documentation for the <DoptProvider /> can be found here

Offline/Local

In offline/local mode, you provide the <DoptProvider /> with configuration that allows for mocking of blocks. This gives the developer complete control over the starting state of individual blocks. Actions/intents on the block will update the state correctly but the flow will not progress. This is great for developing individual experiences powered by Dopt before testing how they connect in a flow.

import { DoptProvider } from '@dopt/react';
import Application from './application';

const blocks: Blocks = {
'HNWvcT78tyTwygnbzU6SW': {
active: true,
started: false,
completed: false,
stopped: false,
exited: false,
uuid: 'HNWvcT78tyTwygnbzU6SW'
},
};

export function Index() {
return (
<DoptProvider mocks={{ blocks }}>
<Application />
</DoptProvider>
);
}
note

We will allow the mocking of edges in the near future, allowing you to test the journey locally.

Live

In live mode you are using our APIs directly. You do so by providing the <DoptProvider /> with your API key and an identifier for a user you’ve identified (see ProviderConfig).

This is great for testing your flow E2E. We provide a testing endpoint to reset the state of the flow for the user you are testing with. Assuming the user identified earlier (i.e. User 123456789) and a flow with id 1.

curl \
-H "x-api-key:$YOUR_API_KEY" \
-X POST \
https://blocks.dopt.com/user/123456789/journey/1/reset
info

You can grab the flow ID from the flow URL in Dopt e.g. https://app.dopt.com/flows/81 would be 81.

Viewing and resetting flow states for users

You can see each user’s details, attributes, and flow state on the user page: https://app.dopt.com/users/

This is useful to see:

  • That users have the right set of attributes
  • What flows they’ve qualified for, started, finished, and exited

You can also reset the state for a flow on this page.