Identifying groups

Overview

Identifying groups is similar to identifying users. You can identify groups 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.

Group identification

We manage your group data via upsertion i.e. we provide a single set of APIs for both creating new groups in Dopt and updating existing groups.

If you’ve used a customer data platform (CDP) like Segment before, this will be familiar to you.

Node.js client

Initialize the client

import { DoptApiClient } from '@dopt/users-javascript-client';

const client = new DoptApiClient({
  apiKey: process.env.DOPT_USERS_API_KEY,
});

Identify a group

await client.groups.identifyGroup({
  identifier: 'group_identifier_example',
  properties: {
    stringExample: 'string',
    numberExample: 12345,
    booleanExample: true,
    nullExample: null,
  },
})

JS browser client

Initialize the client

import { DoptApiClient } from '@dopt/users-javascript-client';

const client = new DoptApiClient({
  apiKey: process.env.DOPT_USERS_API_KEY,
});

Identify a group

await client.groups.identifyGroup({
  identifier: 'group_identifier_example',
  properties: {
    stringExample: 'string',
    numberExample: 12345,
    booleanExample: true,
    nullExample: null,
  },
})

Python client

Initialize the client

from dopt.client import DoptApi

client = DoptApi(api_key="YOUR_API_KEY")

Identify a group

client.groups.identify_group(
  identifier="group_identifier_example",
  properties={
    "string_example": "string",
    "number_example": 12345,
    "boolean_example": True,
    "null_example": None,
  },
)

@dopt/react-users

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 />
  </DoptProvider>,
  rootElement
);

Identify a group

import { useIdentifyGroup } from '@dopt/react-users';

export function Application() {
  const userId = useIdentifyGroup({
    identifier: 'group_identifier_example',
    properties: {
      stringExample: 'string',
      numberExample: 12345,
      booleanExample: true,
      nullExample: null,
    },
  });

  return ( ... );
}

cURL

curl 'https://users.dopt.com/identify/group' \
 -X POST \
 -H 'Content-Type: application/json' \
 -H 'x-api-key:$USERS_API_KEY' \
 -d '{
  "identifier": "group_identifier_example",
  "properties": {
    "stringExample": "string",
    "numberExample": 12345,
    "booleanExample": true,
    "nullExample": null
  }
}'

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

info

If a group has a name property, it will be displayed in Dopt web app and be more identifiable.

info

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.

Updating group properties

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

Initializing Dopt with a group

You can provide the group to the SDKs and APIs like this:

React SDK

<DoptProvider
  flows={{ [$YOUR_FLOW_ID]: $FLOW_VERSION }}
  userId={$USER_ID}
  groupId={$GROUP_ID}
  apiKey={$BLOCKS_API_KEY}
>
  ...
</DoptProvider>

Vue SDK

app.use(DoptPlugin, {
  flowVersions: { [$YOUR_FLOW_ID]: $FLOW_VERSION },
  userId: $USER_ID,
  groupId: $GROUP_ID,
  apiKey: $BLOCKS_API_KEY,
});

JavaScript SDK

const dopt = new Dopt({
  flowVersions: { [$YOUR_FLOW_ID]: $FLOW_VERSION },
  userId: $USER_ID,
  groupId: $GROUP_ID,
  apiKey: $BLOCKS_API_KEY,
});

Blocks API client

await client.flows.getFLow($YOUR_FLOW_ID, {
  version: $FLOW_VERSION,
  userIdentifier: $USER_ID,
  groupIdentifier: $GROUP_ID,
});