Setting Up Your Application
- You have created a Conscia account and have received an email confirming that you have been granted access to a sandbox environment.
- 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
This guide provides several examples of application configurations to help get you familiar with the Conscia platform. Keep in mind that while your sandbox environment may have different Channels, Data Templates, Components and connections, the steps to create and configure each of them remains the same.
When you first log into the Experience Studio, you'll be presented with the following home dashboard:
From here, you can navigate to the various Components. Let's get started with exploring each Component in greater detail.
Conscia supports a growing number of connectors to systems - including content CMSes, digital media platforms and product information management (PIM) systems. Visit the Conscia Connectors page for the full list of available connections.
As a business user, at this point, you will have all relevant Connections created for you by your Engineering team.
Channels represent a front-end or application where content is intended to be served. On the channels dashboard, you'll can create any number of channels such as:
For this guide and its included tutorials, we will focus on the "Web" channel. This will already be set up for you by your Engineering team.
Data Templates allow you to assemble a series of Experience Components into a logical group. 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.
Your sandbox environment may include existing Data Templates such as:
- Home Page
- Landing Page
In your sandbox environment, one Template has been populated with Components while the other Template has intentionally been left empty. As part of this guide, we will work to add Components to it.
Components are the atomic working unit for the DX Engine. Within your sandbox environment, you will be configuring Experience Rules for each Component that delivers dynamic content or data to the frontend. You will find that different Components give you different options for configuring business logic. For example, static Components source a single content record from the system of record whereas dynamic Components source a set of records based on a criteria.
Here's an example of a sandbox environment containing three (3) different starter Components.
- 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.
- 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.
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:
- Your sandbox customer code
- The Template code for the page you'd like to visualize
Once you have those two items, you can navigate to the following URL:
This is what the front-end looks like:
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.
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.
Here's another example:
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 Articles Component in the Landing Page and add a rule that applies to a specific context.
Navigate to the MANAGE EXPERIENCES > EXPERIENCE RULES dashboard
From the left navigation, click on the 'Web' Channel
Expand out one of the Templates in your sandbox
Select one of the Component
Create a new rule by clicking on the 'create record' button in the ribbon that appears to the right, just above the grid.
In the form, provide the following information
- 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
- Check the Enable A/B Test if you'd like to personalize content in the form of an A/B variant.
- 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.
- 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.
- The UI functionality of this section is dependant on the APIs of the connecting partner. In most cases, a typeahead functionity is available.
- 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.
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.
- Navigate to MANAGE EXPERIENCES > EXPERIENCE COMPONENTS.
- In the dashboard, select the “+” button to create a new Component.
In the form modal, enter the following segment information:
- Component Code (no spaces) : popularproducts
- Component Name (friendly name): Popular Products
- Component Description: Sample Component for popular products
In the Components Type field, select “BigCommerce Product List”.
In the Options section
- Set the Connection as “BigCommerce for Partners”.
- Select "name" as the Display Fieldname
- Multi-select the desired elements to include in the response.
- Select any "Product Categories" to filter on.
- Select any Brand to include
- Select if the product should be a featured product and whether it should include free shipping products only.
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.
Triggering the A/B Variants
When a rule is define as an A/B test, the target experience will update to allow the business user to define multiple experience variants. Each experience variant carries with it a 'relative weight' that is used by the personalization engine to determine how often the experience variant should be shown. The frequency at which an experience variant appears is based on the variants relative weight divided by the sum of all the relative weights. So, 2 variants with weight of 1 each, would show 50% of the time (1 / 2 = 50%). All of the experience variants defined as part of the rule will be triggered when the trigger condition in the previous section is met.
In the example shown here, two (2) experience variants have been setup and will each showcase 50% of the time. The first variant will dynamically return all Contentstack entries with tag = mobileappmac, whereas the second variant will dynamically return all Contentstack entries with tag = blackfriday. Notice that each variant also has an "identifier". This is a unique value that is passed to the reporting engine to bucket reporting metrics to the appropriate variant.
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.
- Select the Template you'd like to add the Component to. In this case, we'll select the homePage Template.
- Right click the record and select 'Update Template'
- Under the Experience Component Codes, check all experience Components that you would like to add to this Template.
- Hit Submit
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.
To create a new Template:
- Navigate to the MANAGE EXPERIENCES > TEMPLATES dashboard
- On the action ribbon, select the “Configure Experience Template” button ("+")
- Enter the following information:
- For the Experience Template Code, enter “productPage” (no spaces). This is the unique identifier for the template
- For the Name, enter “Product Page”. This is the friendly name for the template
- Under Experience Component Codes, add the “popular products” Component that we created earlier.
- 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.
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.
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:
- Navigate to the MANAGE EXPERIENCES > CHANNELS dashboard
- On the action ribbon, select the “Create Record” button
- Enter the following information:
- For the Experience Channel Code, enter “mobile-ios”. This is the unique identifier for the channel (no spaces)
- For the Name, enter “Mobile”. This is the friendly name for the channel
- For the Experience Template, search and add “productPage” to the list.
- Hit Submit to save the channel.
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:
- Navigate to the “MANAGE EXPERIENCES > CONTEXT FIELDS” dashboard
- Select the "+" button in the action ribbon to create a new record
- Enter the name of the context field (i.e. location) [no spaces]
- Enter "Geographical Location" as the Display Name
- Select "String" as the Data Type
- Enter Canada and USA as values in the Fixed List of Values
- 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.
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:
- Navigate to the SETTINGS > CONNECTIONS dashboard
- In the action ribbon, select the "+" button to create a new connection
- In the new modal, give your new connection:
- A connection code
- A connection name (friendly name)
- Select "Contentstack" as the Connector
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.
- Enter the Contentstack endpoint (i.e. https://cdn.contentstack.io/v3)
- Enter the Contentstack API key
- Enter the Contentstack token
- Click submit to create the connection.
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:
- On the Components dashboard, add a new Component.
- Select the 'Conscia - Rendering Instructions' Component from the list of Component types.
- Fill in the necessary details
- Hit submit to save the Component
- Navigate to the Template page and add the Component to the target Template
- Navigate to the experience rules page and select the Component
- Create a new rule and incorporate the context (location=Canada) and the following experience:
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.