Identifying users
Overview
In order for Dopt to power experiences for your users, Dopt needs to be aware of those users and their properties.
You can identify users to Dopt using the users API which can be done via the users API clients, @dopt/react-users SDK, or making requests to the users API directly.
We support two approaches for sending your user data to Dopt: individual identification and batch 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 users 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.
- Node.js client
- JS browser client
- Python client
- @dopt/react-users
- cURL
Initialize the client
import { DoptApiClient } from '@dopt/users-javascript-client';
const client = new DoptApiClient({
apiKey: process.env.DOPT_USERS_API_KEY,
});
Identify a user
await client.users.identifyUser({
identifier: 'user_identifier_example',
properties: {
stringExample: 'string',
numberExample: 12345,
booleanExample: true,
nullExample: null,
},
});
Initialize the client
import { DoptApiClient } from '@dopt/users-javascript-client';
const client = new DoptApiClient({
apiKey: process.env.DOPT_USERS_API_KEY,
});
Identify a user
await client.users.identifyUser({
identifier: 'user_identifier_example',
properties: {
stringExample: 'string',
numberExample: 12345,
booleanExample: true,
nullExample: null,
},
});
Initialize the client
from dopt.client import DoptApi
client = DoptApi(api_key="YOUR_API_KEY")
Identify a user
client.users.identify_user(
identifier="user_identifier_example",
properties={
"string_example": "string",
"number_example": 12345,
"boolean_example": True,
"null_example": None,
},
)
Initialize the users provider
import { DoptUsersProvider } from '@dopt/react-users';
import Application from './application';
const rootElement = document.getElementById('root');
ReactDOM.render(
<DoptUsersProvider apiKey={usersApiKey}>
<Application />
</DoptUsersProvider>,
rootElement
);
Identify a user
import { useIdentifyUser } from '@dopt/react-users';
export function Application() {
const userId = useIdentifyUser({
identifier: 'user_identifier_example',
properties: {
stringExample: 'string',
numberExample: 12345,
booleanExample: true,
nullExample: null,
},
});
return ( ... );
}
curl 'https://users.dopt.com/identify' \
-X POST \
-H 'Content-Type: application/json' \
-H 'x-api-key:$USERS_API_KEY' \
-d '{
"identifier": "user_identifier_example",
"properties": {
"stringExample": "string",
"numberExample": 12345,
"booleanExample": true,
"nullExample": null
}
}'
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.
If a user has an email
property, it will be displayed in Dopt web app and be more identifiable.
When you use the users 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. You can also call /identify
via the server which collects data from a server-based installation and isn't accessible to the user.
Batch identification
Many users have likely been created in your system before Dopt was integrated. To tell us about those users we offer a batch identify endpoint in the users 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.
- Node.js client
- JS browser client
- Python client
- cURL
Initialize the client
import { DoptApiClient } from '@dopt/users-javascript-client';
const client = new DoptApiClient({
apiKey: process.env.DOPT_USERS_API_KEY,
});
Identify a user
await client.users.identifyUsers([
{
identifier: 'user_identifier_example',
properties: {
stringExample: 'string',
numberExample: 12345,
booleanExample: true,
nullExample: null,
},
},
{
identifier: 'another_user_identifier_example',
properties: {
stringExample: 'string',
},
}
]);
Initialize the client
import { DoptApiClient } from '@dopt/users-javascript-client';
const client = new DoptApiClient({
apiKey: process.env.DOPT_USERS_API_KEY,
});
Identify a user
await client.users.identifyUsers([
{
identifier: 'user_identifier_example',
properties: {
stringExample: 'string',
numberExample: 12345,
booleanExample: true,
nullExample: null,
},
},
{
identifier: 'another_user_identifier_example',
properties: {
stringExample: 'string',
},
}
]);
Initialize the client
from dopt.client import DoptApi
client = DoptApi(api_key="YOUR_API_KEY")
Identify a user
client.users.identify_users(
request=[
{
"identifier": "user_identifier_example",
"properties": {
"string_example": "string",
"number_example": 12345,
"booldean_example": True,
"null_example": None,
},
},
{
"identifier": "another_user_identifier_example",
"properties": {
"string_example": "string",
},
},
]
)
curl 'https://users.dopt.com/identify/batch' \
-X POST \
-H 'Content-Type: application/json' \
-H 'x-api-key:$USERS_API_KEY' \
-d '[
{
"identifier": "user_identifier_example",
"properties": {
"stringExample": "string",
"numberExample": 12345,
"booleanExample": true,
"nullExample": null
}
},
{
"identifier": "another_user_identifier_example",
"properties": {
"stringExample": "string"
}
}
]'
Updating user properties
You can update user properties by using the users API. Call the identify user (or identify users) endpoint on the users 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.
Associating a user with a group
- Node.js client
- JS browser client
- Python client
- @dopt/react-users
- cURL
await client.users.identifyUser({
identifier: 'user_identifier_example',
properties: {},
groups: [
{
identifier: 'group_identifier_example',
properties: {},
},
]
});
await client.users.identifyUser({
identifier: 'user_identifier_example',
properties: {},
groups: [
{
identifier: 'group_identifier_example',
properties: {},
},
]
});
client.users.identify_user(
identifier="user_identifier_example",
properties={
"string_example": "string",
"number_example": 12345,
"boolean_example": True,
"null_example": None,
},
groups=[
{
identifier: "group_identifier_example",
properties: {},
},
]
)
const userId = useIdentifyUser({
identifier: 'user_identifier_example',
properties: {},
groups: [
{
identifier: 'group_identifier_example',
properties: {},
},
],
});
curl 'https://users.dopt.com/identify' \
-X POST \
-H 'Content-Type: application/json' \
-H 'x-api-key:$USERS_API_KEY' \
-d '{
"identifier": "user_identifier_example",
"properties": {},
"groups": [
{
"identifier": "group_identifier_example",
"properties": {}
}
]
}'