Skip to main content

Getting Started with the DX Engine

Pre-requisites:

  1. Please make sure that you've read the 'Introduction to the Headless Experience Engine' before you go ahead with this step-by-step tutorial. This will ensure that you have an understanding of the basics with regards to the headless experience framework.
  2. You have created a Conscia account and have received an email confirming that you have been granted access to a partner sandbox environment.
  3. You have received your API token to start building your front-end against the Experience APIs.

Accessing the Experience Studio

To access the Experience Studio, simply navigate to the following URL:

Take note that your "sandbox customer code" is the name immediately following the base URL. For example:

https://admin-staging.conscia.ai/[sandbox customer code]/experience/channels

Getting Acquainted with Experience Studio

When you first log into the Experience Studio, you'll be presented with the following home dashboard:

alt_text

From here, you can navigate to the various components of Conscia's headless experience framework. Let's get started with exploring each component in greater detail.

Connections

The first step in the journey of orchestrating and personalizing content is to create connections to sources of content. Your sandbox environment is connected to a trial / partner account with the following headless platforms:

ConnectionDescription
alt_textA Headless Commerce Platform
alt_textA Headless Content Management System
alt_textA Headless Content Management System

Gaining familiarity with Conscia's Headless Experience Framework can be done through existing connections that the Conscia team has created within your sandbox environment. Through the course of this guide, you'll leverage these connections and also develop a level of familiarity with them that will allow you to connect the Conscia DX Engine to your own headless platform accounts.

To view the configurations for an existing connection, right click on the connection and hit 'Update Connection'.

Here is a sample configuration for a Contentful Connector. alt_text

In this example, to create a connection with Contentful all you need is the Endpoint, Token, Space and Environment. When these elements are saved, the connection is established and we can reference it when we create our components (later in this guide).

Channels

Channels represent a front-end or application where content is intended to be served. On the channels dashboard, you'll notice that four (4) channels have been created for you:

  • Web
  • Mobile
  • Email
  • Chatbot

For this guide and its included tutorials, we will focus on the "Web" channel.

Templates

Templates allow you to assemble a series of experience components into a logical group. This template (or group) reflects the overall experience the end user will interact with. Templates can consist of 1 or more experience components and can be shared across multiple channels. This allows you to generate a consistent experience across channels to provide a truly omni-channel experience.

The sandbox environment has been setup with two (2) existing templates:

  • Home Page
  • Landing Page

The Landing Page template has been populated with components while the Home Page template has intentionally been left empty. As part of this guide, we will work to add components to it.

Components

Components can be thought of as the workhorse for orchestration by pulling content from a source and returning the content to the template it belongs to. Recall that more than 1 component can be assigned to a template. Components exist in different flavors. For example, static components source a single content record whereas dynamic components source a set of records based on a criteria.

You will notice that the following components have been pre-configured in your sandbox:

  • Banner

    • Sourced from Contentstack
    • Component Type: Contentstack - Static Record List
    • The Banner component pulls the list of banners that are hand selected by the business user.
  • Featured Blogs

    • Sourced from Contentful
    • Component Type: Contentful - Dynamic Record List
    • The Featured Blogs component is sourcing content dynamically from Contentful based on the customerSegment passed in the query to the DX Engine.
  • Featured Product List

    • Sourced from BigCommerce
    • Component Type: BigCommerce - Product List
    • The list of products is dynamically sourced from BigCommerce based on the customer's real-time context.

Let's dive deeper into how a component is configured. To review the configuration of a component, for example the banner component, right click on it and select 'View/Edit Configuration'.

When looking at a component, you'll notice that each has a name, description and type. when looking at the banner component, you'll notice that the 'Component Type' is 'Contentstack - Static Record List'. This component uses Conscia's sandbox Contentstack instance and is tied to the "Banner" content type in Contentstack. Looking further in the configuration, we can see that the Component leverages the "Contentstack for Partners" connection and is binded to the staging environment.

Experience Rules

Now let's review how experience rules are constructed and how you can pull personalized content from a source such as Contentstack.

To get started, navigate to Experience Rules page. From there, select Web > Landing Page > Banners (Contentstack).

alt_text

Here you will see the list of Experience Rules that are configured to show content based on the user's real-time context.

Right click on one of the rules on the right hand side of the dashboard and select 'Edit'.

Each Experience Rule are composed of three main elements:

  • General Information

    • Allows you to define the Rule Name, Schedule, and the Priority of the rule
  • Trigger Conditions

    • Outlines what type of component the experience rule is based on.
    • Defines which type of trigger the rule has. This can be either a global or default rule or triggered by specific criteria that a business user defines.
  • Target Experience

    • Allows the selection of the content record(s) to return or, in the case of dynamic components, a filter criteria to refine the list of records returned from the source system, which in turn returns multiple records.

The Experience API

Now that you have seen how Channels, Templates, Components and Connections are configured in Conscia, let's query the DX Engine to see what the API response looks like. We will run a query to request the Landing Page Template and pass 'customerSegment = traveler' as the user's real-time context.

To run the query, you can use the OpenAPI endpoint (https://docs.conscia.ai/api/dx-engine#tag--Experience-Engine), or feel free to use any other client of your choice.

Use the customer code that you were given for your sandbox as part of your queries:

{
"templateCode": "landingPage",
"context": {
"customerSegment": "traveler",
"productCategory": 19
},
"debug": true
}

Here is the API response:

{
"duration": 804,
"components": {
"banner-contentstack": {
"response": [
{
"_version": 2,
"locale": "en-us",
"uid": "blt12ad65449abe6825",
"ACL": {},
"_in_progress": false,
"call_to_action": {
"title": "Learn More",
"href": "#"
},
"created_at": "2022-03-30T19:17:39.995Z",
"created_by": "blt573706c250004fc1",
"heading": "Great Outdoors",
"image_link": {
"title": "",
"href": "https://images.pexels.com/photos/32870/pexels-photo.jpg?auto=compress&cs=tinysrgb&dpr=2&h=750&w=1260"
},
"subheading": "Enjoy the Great Outdoors",
"tags": [],
"title": "Great Outdoors",
"updated_at": "2022-03-30T19:17:45.491Z",
"updated_by": "blt573706c250004fc1",
"publish_details": {
"environment": "blt8f23432714f82d9b",
"locale": "en-us",
"time": "2022-04-05T02:46:17.664Z",
"user": "blt21250abb4c30c1a0"
}
}
]
},
"featured-blogs-contentful": {...},
"product-list-bigcommerce": {...}
}
}

As you can see in the above response, the various components that are defined as part of the template (banners, featured blogs, products) are returned. If we focus on a single Component within the overall response, specifically banners, you can see banner records are returned as part of the banner element of the payload.

Note that the DX Engine is truly headless, which means that it is not specific to any front-end. The response payload contains a block of JSON for each component that pulls the content model directly from the source system that it is connected to. Note that Conscia does not modify the JSON structure of the content returned from the source system in any way, unless the component is explicitly configured to do so.

The content returned for each component is tailored to the customer based on the trigger conditions met by the query, such as rule priority, active start/end date, and context fields.

The Reference Front-End

A front-end, created in Builder.io, has been configured to consume the JSON payload coming from the Experience API. This helps showcase the different aspects of the payload from an end-user point of view.

To access the front-end, you will need two (2) pieces of information:

  1. Your sandbox customer code
  2. The template code for the page you'd like to visualize

Once you have those two items, you can navigate to the following URL:

https://aim-ui.conscia.io/<sandbox-customer-code>/<landing-page-code>

This is what the front-end looks like: alt_text

The sample front-end renders the contents contained within the response payload, in this case, the three visual components, a banner, blogs and products.

Passing A User's Real-time Context via the Front-end

Similiar to passing context to the DX Engine via the API, context can be passed to the front-end by including it as part of the page URL request.

For example, a context field has been defined for customer segment (code: customerSegment). We know one of the values for customer segment is 'traveler'. So, to pass this context in the URL, we can add "?customerSegment=traveler" as the URL suffix.

https://aim-ui.conscia.io/<sandbox-customer-code>/landingPage?customerSegment=traveler

This causes a different experience rule to take effect and returns different content. In the example above, we can see the hero banner changes to reflect the context.

alt_text

Here's another example:

  • https://aim-ui.conscia.io/<sandbox-customer-code>/landingPage?customerSegment=home_office

Making Changes to Your Sandbox

Now that you are familiar with all the various dashboards in Experience Studio, let's dive in and make some changes to your sandbox.

Creating a New Experience Rule

Let's take a look at the Featured Blogs component in the Landing Page and add a rule that applies to a specific context.

  1. Navigate to the MANAGE EXPERIENCES > EXPERIENCE RULES dashboard

  2. From the left navigation, click on the 'Web' Channel

  3. Expand out the 'Landing Page' Template

  4. Select the Featured Blogs component

  5. Create a new rule by clicking on the 'create record' button in the ribbon that appears to the right, just above the grid. alt_text

  6. In the form, provide the following information

    1. General

      • Provide a Rule ID and Name for the rule.
      • Enter a priority number if this rule should win over other rules (lower values take priority)
      • Enter a campaign code if you'd like to associate this rule into a campaign
    2. Trigger Conditions

      • Select the 'Active' checkbox.
      • Global rule - checking this box will set the rule as the default rule which will always run unless another rule is triggered with a higher priority.
      • Real-time Context - Clicking on the edit button will bring up the canvas in which you can build a context criteria that must be satisfied for this rule to run. Feel free to try out a few different combinations and see how this impacts the target response.

alt_text

  1. Target Experience

    • Since this is a dynamic record list component, you can use type-ahead search to find and select the target content tag from Contentful. Note that this search is querying the data directly from the backend datasource.

alt_text

  1. Hit submit to save the rule

Tagging Experience Rules to Campaigns

When creating an experience rule for the rendering of a personalized experience, a “campaign code” can be associated with the rule. Campaign codes can be thought of as tagging the experience. With this approach, a campaign code can be shared across multiple rules allowing the Track API to aggregate analytics tied to experiences. These aggregated analytics can then be rendered as part of a dashboard focused on the nature of the campaign.

alt_text

Create a New Component

Now that you have a good understanding of the elements within the Experience Studio, you may want to create a component of your own in order to connect to an headless content source.

For this example, we would like to create a new component that dynamically sources Popular Products from BigCommerce based on certain filter and sort parameters. Specifically, we want to return the most popular products in a specific category.

  1. Navigate to MANAGE EXPERIENCES > EXPERIENCE COMPONENTS.
  2. In the dashboard, select the “+” button to create a new component.

alt_text

  1. In the form modal, enter the following segment information:

    1. Component Code (no spaces) : popularproducts
    2. Component Name (friendly name): Popular Products
    3. Component Description: Sample component for popular products
  2. In the Components Type field, select “BigCommerce Product List”.

  3. In the Options section

    1. Set the Connection as “BigCommerce for Partners”.
    2. Select "name" as the Display Fieldname
    3. Multi-select the desired elements to include in the response.

    alt_text

    1. Select any "Product Categories" to filter on.
    2. Select any Brand to include
    3. Select if the product should be a featured product and whether it should include free shipping products only.
  4. Hit submit to save the component

Setting a Component as an A/B Test Type

When creating a new component, business users have the option to define the component as an A/B test type. This is done by checking the “Enable A/B Test” attribute when the component is created. When this attribute is set, the subsequent experience rules that are part of this component should be set up so that each experience rule is an A/B variant.

alt_text

Triggering the A/B Variants

In order to trigger the different A/B variants, the context trigger in the experience rule will be used. This feature will look for a specific traffic identifier passed to it as context. This traffic identifier will then match an experience rule which will then return the experience containing the corresponding A/B variant.

The proportioning of traffic into different traffic identifiers (i.e. 60% traffic identifier 01, 40% traffic identifier 02) can be configured outside of the Experience Studio and then the identifier can be passed to the DX Engine to render the appropriate experience containing the A/B variant.

alt_text

A/B Analytics

When A/B test components are created, analytics dashboards are available to monitor the progress of the A/B campaign. Dashboards can be tailored to showcase the different metrics configured as part of Conscia’s Track API.

alt_text

Adding the Component to an Existing Template

Now that we've created our new component, the next step is to add it to a template. To do so, navigate to MANAGE EXPERIENCES > TEMPLATES dashboard.

  1. Select the template you'd like to add the component to. In this case, we'll select the homePage template.
  2. Right click the record and select 'Update Template'
  3. Under the Experience Component Codes, select "Add another item" and select the component we just created.
  4. Hit Submit

alt_text

Create a New Template

For our next exercise, let's go ahead and create a new template that represents the product page and add our newly created “Popular Products” component to the template.

alt_text

To create a new template:

  1. Navigate to the MANAGE EXPERIENCES > TEMPLATES dashboard
  2. On the action ribbon, select the “Configure Experience Template” button ("+")
  3. Enter the following information:
    1. For the Experience Template Code, enter “productPage” (no spaces). This is the unique identifier for the template
    2. For the Name, enter “Product Page”. This is the friendly name for the template
    3. Under Experience Component Codes, add the “popular products” component that we created earlier.

alt_text

  1. Hit SUBMIT to save the template.

We’ve successfully created our product page template and added our component to it. The template can be edited at any time to add (or remove) other components as needed.

Previewing a Template

When a template is created AND the contents of the orchestrated / personalized experience are rendered in a front-end outside out the Experience Studio, Conscia has the ability to incorporate the rendered front-end as a preview directly inside the Experience Studio. This allows business users to easily preview the front-end experience directly inside the Experience Studio application without the need to navigate away.

alt_text

Previewing a Personalized Version of the Template

In addition to the ability to preview a rendered front-end, business users can also configure the calling parameters used for the preview. This allows different experiences personalized to the viewers context to be triggered and returned in the preview. To do this, users can simply expand the “Context” section of the preview modal and select a context and context value from the list of those available

Selecting a context (or combination of context) will cause the rendered preview to change based on the respective experience rules that match the triggering context.

alt_text

In the example above, you can see that the “Customer Segment”, “Location” and “Device” are all available contexts that are made available. Selecting “United States” causes the rendered preview update based on experience rules that fire when “location = US”.

In the next step, we’ll associate this template with a channel.

Add a New Channel

As mentioned before, Templates belong to one or more Channel. Channels are a way of grouping Templates for organizational purposes. In the example of a product page above, the Template might be shared by a ‘Web’ and ‘Mobile’ Channel.

Channels are created similar to Templates and can contain a number of Templates:

  1. Navigate to the MANAGE EXPERIENCES > CHANNELS dashboard
  2. On the action ribbon, select the “Create Record” button
  3. Enter the following information:
    1. For the Experience Channel Code, enter “mobile-ios”. This is the unique identifier for the channel (no spaces)
    2. For the Name, enter “Mobile”. This is the friendly name for the channel
    3. For the Experience Template, search and add “productPage” to the list.
  4. Hit Submit to save the channel.

alt_text

Now that we’ve set up our Channel, Template and Components, we’ll do one final step by adding a context field to the components.

Add a New Context Field

The ability to present different content to different audiences while on the same page is done through the use of context fields. Context fields are pre-defined “triggers” and component rules can be configured to present different content based on the incoming trigger conditions (context fields).

Example of Context Fields

For this example, we'll set up a new context field for "location". This will allow us to show different featured articles based on what location the customer is in.

 
To Create a New Context Field:

  1. Navigate to the “MANAGE EXPERIENCES > CONTEXT FIELDS” dashboard
  2. Select the "+" button in the action ribbon to create a new record
  3. Enter the name of the context field (i.e. location) [no spaces]
  4. Enter "Geographical Location" as the Display Name
  5. Select "String" as the Data Type alt_text
  6. Enter Canada and USA as values in the Fixed List of Values
  7. Leave the other values empty and hit Submit

When context fields are created, they are automatically made available as part of the trigger conditions within an experience rule.

alt_text

Create a New Connection using an Existing Connector

New connections can be created using any of the existing out-of-the-box Conscia connectors. Although each connection requires a slightly different setup, all connections are share common elements such as Connection Code, Name, Connector Type and Connection setup details such as tokens, API keys, environments, etc.

In the following example, we'll setup a new connection using the Contentstack connector:

  1. Navigate to the SETTINGS > CONNECTIONS dashboard
  2. In the action ribbon, select the "+" button to create a new connection
  3. In the new modal, give your new connection:
    • A connection code
    • A connection name (friendly name)
    • Select "Contentstack" as the Connector

alt_text

  1. Selecting the connector type will bring up a new set of fields. These fields will be specific to the Connector type and are used by Conscia to connect to the headless platforms API.

alt_text

  1. Click submit to create the connection.

Advanced Use Cases

The best way to explore some of the more advanced features and capablities of the DX Engine is through use cases.

Product Recommendations Based on Customer's Real-time Profile

You may have a Customer Data Platform (or have licensed Conscia's Identity Graph module) that gives you real-time intelligence about your customer. In this case, you would want to return content to them that is specifically relevant to that customer. In this scenario, we would be extracting information such as brand affinities, product affinities, etc from the customer's profile and passing it to the Product List component. We are essentially creating Product Recommendations in this case.

We will assume that we have created a Customer Profile component that connects to the external CDP and have also defined a dependency between the Customer Profile component and the Product List Component from BigCommerce (how this is done is a topic for one of the upcoming tutorials).

Let's go ahead and create a new Component called 'Product Recommendations' using the 'BigCommerce - Product List' Component Type. Notice that in the 'Target Experience' section, for Product Categories, Brands and various other filter and sort parameters, you can configure the component to pull the value directly from the 'Context Field' instead of 'Specific Value' which you would provide in a typical scenario. Select 'Context Field' as your value type for Product Categories as well as Product Brand.

Now, if you want to test this component out, you simply need to run an Experience API query and pass Product Categories and/or Brand as context. This will filter the list of products returned from BigCommerce to the ones that were provided as affinities of this particular customer by the customer profile component.

Providing advanced rendering instructions to the front-end

Sometimes you want to instruct the front-end to include certain styling or layout details for different customer contexts. For instance, customers coming from Canada should see a different theme than if they are coming from US.

Here is how you would set this up:

  1. On the Components dashboard, add a new component.
  2. Select the 'Conscia - Rendering Instructions' component from the list of component types.
  3. Fill in the necessary details alt_text
  4. Hit submit to save the component
  5. Navigate to the template page and add the component to the target template
  6. Navigate to the experience rules page and select the component
  7. Create a new rule and incorporate the context (location=Canada) and the following experience:

alt_text

As seen above, within the 'Target Experience' portion of any rule, generic metadata can be passed to the front-end via a key/value pattern. In the example above, a value of "activeTheme = red_and_white" is passed to the front-end when the containing rule is triggered.

Upcoming Tutorials

Over the next few weeks, we will roll out further step-by-step tutorials to help you explore the following topics:

  • Generic Components for existing Connections
  • How to use the 'Universal Webservice Connector' to connect to any back-end
  • Using Expressions in Components to reshape content from source systems
  • API Orchestration
    • Defining dependencies between components
    • Expressions to reshape the API response from source systems
  • How to enable A/B Testing within the DX Engine
  • Using GraphQL with the DX Engine
  • Intelligent Recommendations