Made in Builder

×

Developers

Product

Use Cases

Pricing

Developers

Resources

Company

Get StartedLogin

Product

Features

Integrations

Talk to an Expert

Pricing

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

Custom targeting attributes

Learn how to create custom targeting attributes in Builder.io.

Prerequisites:

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.

Setting up a custom targeting attribute

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:

  1. Name: The name of your custom targeting attribute.
  2. 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.
  3. 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.

Targeting content with custom targeting attributes

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.

Rendering targeted content with custom targeting attributes

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:

You can alternatively use setUserAttributes to set the targeting attributes once across multiple content requests:

Finally, when requesting content directly from the content or GraphQL APIs, you can pass the targeting attributes using query strings:

If product.id matches the ID of the product selected for your targeting condition, then your content will be rendered.

Matching custom targeting attributes with custom types

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.

Was this article helpful?