Creating targeting rules

Configuring targeting rules

After creating a flow, navigate to the Settings tab to configure the rules for which users should qualify for this flow.

Type of rule	Description
Target all users	Every user that encounters this flow will qualify for it.
Target with an expression	Users with properties which pass the expression will qualify for this flow. You can also use the SDK or API to manually enter users into this flow.
SDK and API only	Users will not automatically qualify for this flow. You can only use the SDK or API to enter users into this flow.

Expression language

This is the expression language you can use to craft custom entry rules:

Unit	Operator(s)	Rules	Example
Number	== > >= < <= !=		user.properties.projects_created <= 3
Boolean	== !=	Allowed values are only true and false (not T, F, etc.)	user.properties.activated == true
String	== !=	Strings must be surrounded by double quotes ". You can escape any double quote characters with \. These are case sensitive: they must exactly match the property value.	user.properties.SKU == "Free" group.properties.name == "World’s \"Best\" Coffee"
Logical group	AND OR	These are case insensitive: for example, you can use OR, Or , or or	user.properties.role == "marketing" OR user.properties.role == "sales"
Parenthesis	( ... )	In logical expressions, AND takes precendence over OR. Parenthesis allow you to specify your own order of logical expressions.	(user.properties.role == "marketing" OR user.properties.role == "sales") AND user.properties.active == true
Logical not	!	! can be used in front of any logical expression	!(user.properties.role == "marketing" OR user.properties.role == "sales")

In addition to writing expressions, you can also refer to properties directly to check whether they are truth-y. When used in an expression user.properties.foo will return true if foo is present in user.properties and is not null, false, or 0. Conversely, !user.properties.foo will return true if foo is false, 0, or null.

info

Property names are case sensitive and the property name in the expression must match the case of the user or group property. Projects is different than projects.

info

Accessing nested user and group properties are currently unsupported. You can access a top level property such as user.properties.email, but not a nested property such as user.properties.sku.name.

Example targeting expressions

Let’s say a user and a group have the following properties:

User properties

{
  identifier: '55c8-2a34',
  properties: {
    email: 'oneill@acme.com',
    name: "O'Neil",
    activated: false,
    projects: 2,
    role: 'Marketing'
  },
  groups: [
    {
      identifier: 'ea83-47h1'
    }
  ]
}

Group properties

{
  identifier: 'ea83-47h1',
  properties: {
    email: '@acme.com',
    name: 'Acme Co',
    total_projects: 42,
    sku: 'Pro',
    integration_setup: false
  }
}

Here are some example targeting expressions and the result for this user:

Targeting expressions	Result
user.properties.activated == false	✅ User qualifies
user.properties.projects < 10 AND group.properties.sku == "Pro"	✅ User qualifies
user.properties.role == "Marketing" OR user.properties.role == "Sales"	✅ User qualifies
user.properties.activated == true	❌ User does not qualify
group.properties.integration_setup == true	❌ User does not qualify
user.properties.role == "Marketing" OR user.properties.role == "Sales" AND user.properties.activated == false	❌ User does not qualify
(user.properties.role == "Marketing" OR user.properties.role == "Sales") AND user.properties.activated == false	✅ User qualifies

The last two examples demonstrate the importance of parenthesis when crafting meaningful targeting conditions.

Flow qualification

A user’s qualification for a flow is evaluated in real-time. If the user hasn’t started the Flow and the user’s properties are updated where the user no longer matches the targeting rules, then they will no longer qualify for that flow and will not start it.

Once a user starts a flow, the flow is in progress, and the user will remain in that flow until the flow is finished or exited, even if the user’s properties are updated and no longer match the targeting rules.

Manually entering users

Users can be entered into a flow via the SDK or blocks API by calling the start or reset intents with the optional force parameter set to true.

When you do so, the user will be forcefully entered into the flow despite any targeting rules. As noted above, once a user has started a flow, the user will remain in that flow until the flow is finished or exited.

React SDK

const [_, intent] = useFlow('example-flow-identifier');
intent.start({ force: true });

Vue SDK

const { start } = useFlow('example-flow-identifier');
start({ force: true });

JavaScript SDK

const flow = dopt.flow('example-flow-identifier');
flow.start({ force: true });

Blocks API Client

await client.flows.intent('example-flow-identifier', 'start', {
  version: 3,
  userIdentifier: 'example-user-identifier',
  force: true,
});