In simple terms, a placement is a location on your website, for example, a homepage hero banner, that you make available to receive Personalized content, Product recommendations, or Product badging campaigns.

Campaigns are created and managed independently by your merchandising and marketing teams, and they can define target audiences and target those audiences with different messaging and content.

For developers, placements represent a much simpler implementation of Qubit's personalization technology; you only need to render the content supplied by our API, with the content itself driven by merchandisers in the campaign creation flow.

Under the hood, we provide a GraphQL endpoint, currently https://api.qubit.com/placements, where you can query the content that should be shown by passing in a placement's Id and the current attributes (page/user attributes).

Because audience segmentation and traffic split are applied server-side, the placement only needs to check whether any content is returned. We've created an SDK in the form of an NPM package that abstracts this away.

Don't forget to check out the glossary for further explanations of concepts and terminology.

To guide you through building a placement, we'll use the example of a new homepage placement for personalized content, with three mandatory fields: message, image, URL.

To get started, select Placements from the side menu and then select the Create new Homepage placement button

Now select Personalized content as the placement type. This selection defines what campaigns your placement can be used for

The fields you add in this step define what inputs your merchandising and marketing teams can provide when creating their campaigns. Let's look at an example.

In this simple Personalized content campaign, created by selecting a Homepage placement, the merchandiser can provide two inputs, a message, and an image.

The merchandiser view:

The placement itself consists of two fields, one for the message, of the type string, and another for the image, of the type image.

The placement builder view:

So let's add our three fields for our placement: message, image, URL. The type, key, and label are mandatory, and we want the merchandiser to enter values for each of the placement fields, so we won't use the Field is optional flag.

TIP: When adding fields, you also have the option of duplicating a field. Duplicating is a good option when you are building a placement with several fields of the same type. Remember that the field key needs to be unique for each field.

Select Add field

From Type, select String

In Key, enter a unique value for the placement. We will display an error if you try to use the same key value for more than one field in the same placement

In Label, enter the text you would like to display as the field value. You can use this to help the merchandiser with ideas for what to enter when they are building their campaign or help with the expected input:

You can also enter a description for the field. You can do this to provide further information to help in the completion of the field. This text is available in the tooltip:

Once you have defined your field, select Add another field.

INFO: Selecting Add another field automatically saves the field you are currently working on.

From Type, select Image

Enter a key, label, and description in the same way you did for the message field

From Type, select URL

Enter a key, label, and description in the same way you did for the message field

Now that we've finished adding our fields, let's save our placement as a draft. You can do this by selecting Save at the bottom of the page.

We'll cover the use of these files in detail in our tutorials for personalized content, product recommendations, and product badging.