Skip navigation

Integrating personalization (Optimizely)

In this tutorial, you will learn how you can easily link your content to audiences by creating a custom selector for Optimizely audiences. With the selector, you define what content is relevant for what audience, and leverage this information to personalize the content on the live web site.

Premium feature

Custom elements require a Professional plan or higher.

Table of contents

    A gif of the Optimizly audience selector in a content item.

    What is Optimizely?

    Optimizely is a powerful experimentation platform, empowering marketing and product teams to test, learn, and deploy winning digital experiences.

    For more details visit Optimizely web site.

    Optimizly logo

    Linking content to audiences

    By linking content to audiences, you can easily introduce personalization or targeted testing for your content.

    In this tutorial, you will:

    • Get Personal API token and Project ID from Optimizely.
    • Extend a Kentico Kontent content type with an Optimizely audiences selector.
    • Link individual content items to target audiences.
    • Set up Optimizely to retrieve audiences from visitor context.
    • Update the web site to display personalized content based on the linked audiences.

    After performing these steps, you will be able to provide your site visitors with content personalized based on their behavior.

    Step 1: Get Personal API token and Project ID from Optimizely

    The easiest way to access Optimizely API is leveraging Personal API token. The token provides the same permissions which are assigned to the user who generated it. Because of this, we don't want to expose the token for admin privileges, but only for read-only access.

    1. In Optimizely navigate to Settings and then to Collaborators.
    2. Add a collaborator with the role Viewer.
    3. Log out from Optimizely.
    4. Log in as the newly invited user.
    5. Navigate to Profile, open the API Access tab, and generate a new Personal API token for the user.
      • Token name – Kentico Kontent Optimizely audiences selector
    6. Copy the token code from the next screen as later the token won't be visible in this same UI due to security reasons.

    A screenshot of generating a new token in Optimizly.

    The next thing you will need is your Project ID, you can find it in the browser address when managing the project data in Optimizely.

    A screenshot where you can see the project ID in Optimizly.

    Notice the sample audiences on this screenshot. If you don't have any audiences defined in your project yet, you should create a few so you can assign them to content items in the next steps. The names and details of individual audiences are not so important for this tutorial. Feel free pick any names and conditions that may fit your business cases.

    Step 2: Add Optimizely audiences selector to Kentico Kontent

    content type

    In this step, we will extend the Article content type in our sample app with the audiences selector.

    1. In Kentico Kontent, choose Content models  from the app menu.
    2. Open an Article content type.
    3. Add a Custom Element.
      1. Title – Target audiences
      2. Hosted code URLhttps://kentico.github.io/kontent-custom-element-samples/Optimizely/audiences-selector.html
      3. Parameterssee below
    4. Save the content type.

    Because the sample Optimizely audiences selector is general and can be used for any Optimizely project, you need to connect the selector to your project by providing additional configuration to it. The selector uses the Optimizely API for audiences and needs the Project ID and Personal API token you got in the previous step.

    Use the following JSON configuration for parameters and replace <YOUR PROJECT ID> and <YOUR ACCESS TOKEN> with the values from your Optimizely project.

    • JSON
    { "projectId": "<YOUR PROJECT ID>", "apiToken": "<YOUR ACCESS TOKEN>" }
    { "projectId": "<YOUR PROJECT ID>", "apiToken": "<YOUR ACCESS TOKEN>" }

    If you would like to just try it using our sample data, feel free to use the following:

    • JSON
    { "projectId": "13645900009", "apiToken": "2:yZ4BN01nE71KgVr78tDnM0RV3hbuvuajUwNvmHPJek3f8obR7KL8" }
    { "projectId": "13645900009", "apiToken": "2:yZ4BN01nE71KgVr78tDnM0RV3hbuvuajUwNvmHPJek3f8obR7KL8" }

    Step 3: Link articles to specific audiences

    Now that you have extended the content type, you can assign individual content items to audiences.

    1. In Kentico Kontent, open Content & Assets  from the app menu.
    2. Filter the list by content type to only the Article type.
    3. Open a content item for editing.
    4. Use the audiences selector to find and select the audiences suitable for a particular article.
    5. Repeat steps 3 and 4 for other articles.

    A gif of the Optimizly audience selector in a content item.

    Customizing selector value format

    Note that the audiences selector used in the previous steps is a sample to demonstrate the possibilities. Feel free to adjust it to your needs and visual requirements, or build your own.

    You can find the source code of the audiences selector in a GitHub repository.

    The compiled version of the selector, used in the example above, is available in the Custom Element Samples repository.

    The selector stores the following value format in JSON which it also uses to display the selected audiences upon the first load:

    • JSON
    [ { "id": 14075630105, "name": "Caffeine addict" }, { "id": 14097300687, "name": "Regular drinker" } ]
    [ { "id": 14075630105, "name": "Caffeine addict" }, { "id": 14097300687, "name": "Regular drinker" } ]

    You can use any of those values in both the admin UI and your site. Should you need to extend the fieldset, you can do so simply by customizing the custom element code.

    Step 4: Access current audiences on live site

    In order to access visitor context from Optimizely, you need to place the Optimizely snippet to the page. See the Optimizely documentation for instructions on how to do that.

    Normally, you would do the rest in Optimizely admin UI where you would define and run experiments. In our case, we want to leverage the Optimizely data to build data-driven personalization of the content.

    The Optimizely engine doesn't provide user context (audiences, in our case) until there is an active experiment which would use the data.

    The JavaScript API method we will use to get the current active audiences for the user is getExperimentStates(). It provides all currently running experiments together with their metadata.

    Here is a JavaScript code which collects all active user audiences based on experiments which are active on the current page from the Optimizely context:

    • JavaScript
    function getActiveAudiences() { const audienceIds = []; const experiments = window.optimizely.get("state").getExperimentStates(); for (var experimentId in experiments) { if (experiments.hasOwnProperty(experimentId)) { const experiment = experiments[experimentId]; for (var i = 0; i < experiment.audiences.length; i++) { const audienceId = experiment.audiences[i].id; if (audienceIds.indexOf(audienceId) < 0) { audienceIds.push(audienceId); } } } } return audienceIds; }
    function getActiveAudiences() { const audienceIds = []; const experiments = window.optimizely.get("state").getExperimentStates(); for (var experimentId in experiments) { if (experiments.hasOwnProperty(experimentId)) { const experiment = experiments[experimentId]; for (var i = 0; i < experiment.audiences.length; i++) { const audienceId = experiment.audiences[i].id; if (audienceIds.indexOf(audienceId) < 0) { audienceIds.push(audienceId); } } } } return audienceIds; }

    The code relies on having an active experiment in Optimizely, which means you need to create an experiment that:

    • Is active on all pages (or at least the page where you plan to apply the personalization).
    • Evaluates all audiences that you want to use for personalization.

    To achieve that, follow these steps:

    1. Log in to Optimizely as an admin and navigate to Experiments.
    2. Create a New Experiment of the type A/B Test (we won't actually run an A/B test, but we need an experiment).
      1. Name – Kentico Cloud Personalization context
      2. Targeting URL - /

    A screenshot of creating a new experiment in Optimizly.

    As mentioned, we won't run a real A/B test, we just need a rich enough context for our personalization.

    3. On the Variations tab, delete all but the Original variation.

    A screenshot of variations in Optimizly with only the original remaining.

    You also need to ensure that the experiment will be active (and therefore provide you with personalization context) on all pages.

    4. On the Targeting tab, delete the prefilled condition in the Page settings section.

    5. Save the Targeting tab settings.

    A screenshot of the Targeting tab in Optimizly.

    No condition means the experiment targets all pages

    In the next step, we need to ensure that our experiment fires conditions for all our personalization audiences, and recognizes them in the context.

    6. On the Audiences tab, explicitly select audiences you want to use for the personalization.

    7. Select Match any audience from the top dropdown.

    8. Save the Audiences tab settings.

    A screenshot of audiences for an experiment in Optimizly.

    Experiment audiences explicitly listed.

    The last thing the experiment needs in order to be published is to have a metric defined.

    9. On the Metrics tab, add a metric.

    • For simplicity, you can use the predefined Page view metric.
    • If you plan to measure anything related to the personalization, pick any other metric you want.

    10. Save the Metrics tab settings.

    A screenshot of metrics within Optimizly.

    Now the experiment is ready to be published and it can provide us with the necessary context.

    11. Click Start Experiment.

    Note that it might take a few minutes and refreshing of your browser for the Optimizely to start handling the new experiment due to caching. After the cache refreshes with the new configuration, the Javascript function getActiveAudiences starts returning active audiences for the current user.

    Ensure that you make the necessary actions as a user to fall within at least one audience. This allows you to test content filtering in the next step.

    Step 5: Filter live site content by audiences

    The last step is to update the site presentation to filter the content by the current audiences provided by the Optimizely context.

    First, you need to update the data model of the article, so you can retrieve the audiences assigned to the particular content item.

    After you do that, update the code which is getting the list of articles to retrieve current visitor audiences, and filter the content based on the active audiences from the previous step.

    In this case, you are going to personalize the latest articles listed on the Home page of the Sample App. This is what it looks like originally with all articles displayed:

    A screenshot of an article listing with no personalization.

    You may consider the following within the filtering logic:

    • If the visitor does not fall into any audience, do not filter and display all the articles.
    • If you don't have enough content and results would yield just a small amount of articles, display the matching articles first, and fill the rest with the remaining articles up to the required count.
    • If the article is not assigned to any audiences by the editor, you can either display it to all people or to none (in this case it may display only when no audiences are detected according to the first point).

    After you update the code, you should be able to test how the filtering works. Test the filtering with the audience(s) returned from the previous step, or simulate some additional user actions which will assign the user specific audiences based on the conditions you defined in Optimizely.

    Observe how the content is filtered based on the user context and provides a personalized experience to the site visitor based on their interests. Here is an example of how a personalized view may look like:

    A screenshot of an article listing with no personalization.

    Adjust the conditions for individual Audiences or filtering code if necessary.

    See a full sample code showing how you can implement personalization based on Optimizely audiences in your web site.

    What's next?

    You learned how to link your content to online marketing context in order to provide personalization on your web site.

    The custom audiences selector sample provides a baseline you can use and further adjust to your needs. Other online marketing solutions may have different endpoints and contracts, but the selector code is easy enough to adjust for other systems.

    You can use a similar approach and build integrations with other online marketing solutions.