Learn how to create custom targeting attributes in Builder.io to go beyond the built-in targeting options.
Prerequisites:
- You may want to read Targeting Content in Builder if this topic is new to you.
The short video below explains custom targeting attributes.
You can set custom targeting attributes to conditionally render content based on complex criteria. For example, you can:
- Have an announcement bar appear when a customer adds a certain item to their cart.
- Display different pages depending on a user's current stage in your onboarding flow.
- Customize a sidebar depending on a user's profile.
Using Builder's built-in types, custom targeting attributes offer a straightforward way to allow your team to specify arbitrary targeting conditions using strings and booleans. Using custom types further allows your team to create targeting conditions based on input from forms, color pickers, calendars, and other rich user interfaces.
You can set up a custom targeting attribute on the Account page, which enables you to use that attribute when targeting any content across your space.
From the Account page, click the Edit pencil for Custom targeting attributes.
Click New target attribute.
You can add a new custom targeting attribute from the Custom targeting attributes window using the following properties:
- Name: The name of your custom targeting attribute.
- Type: Your attribute's type determines the editor UI that pops up when a user targets content using your attribute. For example, users may enter text for a targeting attribute that has a string type inside of a text box, while a boolean type attribute presents the user with a toggle switch.
- Enum (string type only): Restricts user input for the string type to a multiple-choice selection of strings.
Click Save to create your new custom targeting attribute.
You can target content with your custom targeting attributes by creating targeting conditions using those attributes.
The process is the same as targeting with built-in attributes; the only difference is that your custom targeting attributes appear in the list of attributes to choose from when creating a targeting condition.
The example below features two custom targeting attributes called Some string and Some product.
Targeting works by matching the value of targeting data sent with a content API request to the value of your targeted content's targeting conditions. When you request content that uses the built-in Device or URL path targeting attributes, Builder automatically infers the targeting data from your request.
When using custom targeting attributes, you can manually provide targeting data with your request either by using the JavaScript (JS) SDK or with query string parameters when requesting content using the content/GraphQL APIs.
For example, when requesting content that has a targeting condition named product that expects a product ID, you can set userAttributes when using the SDK:
const content = await builder.get('myTargetedContent', {
userAttributes: { product: product.id }
}).promise();You can alternatively use setUserAttributes to set the targeting attributes once across multiple content requests:
builder.setUserAttributes({ product: product.id });
const content = await builder.get('myTargetedContent').promise();
const otherContent = await builder.get('myOtherTargetedContent').promise();Finally, when requesting content directly from the content or GraphQL APIs, you can pass the targeting attributes using query strings:
const response = await fetch(`https://cdn.builder.io/api/v3/content/my-model?apiKey=YOUR_API_KEY&userAttributes.product=${product.id}`)If product.id matches the ID of the product selected for your targeting condition, then your content will be rendered.
In order to know what targeting data to send with a content API request, it's important to know how a targeting attribute's type editor stores a user's input as a value.
For example, the editor for the built-in string type is a simple text box. The value entered inside this text box when adding a targeting condition is the value that must match the targeting data sent with your content API request for your content to be rendered.
In contrast, custom types generally provide editors with rich user interfaces, allowing users to provide complex inputs such as colors, forms, or products. How these inputs are represented as a stored value isn't always immediately clear and depends on the editor.
For example, the Shopify plugin's Shopify product handle custom type provides a searchable menu for selecting a product from a Shopify store. The editor stores the product's Shopify handle as the value.
The same plugin also provides a Shopify product custom type. Despite providing the same editor user interface for selecting a product, it stores the selected product using its Shopify ID.
You can refer to the documentation for the plugin that provides the custom type used by your custom attribute for more information on how the type's editor stores values.
For more information on passing parameters, check out the Builder Content API.
- You can leverage targeting in a variety of ways for your store—check out the tutorial for how to create a product promotion targeted on specific product or collection pages.
- Take your targeting a step further by scheduling your content and creating A/B tests to measure your page performance.
- Create your own custom types by creating a plugin
