First-Visit Personalisation – Cordial Knowledge Base

How can we help?

Overview

First-Visit Personalization extends personalized onsite experiences to visitors who are unknown or not yet identified. This feature evaluates browsing behavior in real time and returns tailored product recommendations that can be rendered in carousels, landing pages, and other onsite experiences.

By aggregating data across all site browse and purchase behavior, a default recommendation on the first page visit is continuously refined with every subsequent browse and cart event. This allows you to deliver relevant recommendations from the very first interaction, and improve relevance as the visitor continues to engage.

Common use cases include “Recommended for You” product carousels, personalized recommendations in chatbots, and dynamic landing pages that update based on real-time behavior.

Contact your CSM to begin using First-Visit Personalization.

How it works

First-Visit Personalization implementation is greatly simplified via the Product Carousel SDK, a lightweight JavaScript library that fetches and renders product recommendations.

At a high level:

  1. You install the Product Carousel SDK on your website.
  2. You place a container element where you want recommendations to appear.
  3. You initialize the SDK and call the recommendations endpoint (/recommend/products) with your account and product IDs (or let the SDK infer them from events).
  4. The SDK renders a responsive, customizable product carousel and updates as new browse and cart events occur.

Integration typically takes less than 10 minutes and requires minimal engineering effort. Alternatively, recommended Product IDs can be retrieved directly from the provided API and used as the basis for a tailored web experience.

Ensure your site is configured to send browse and cart events to Cordial using the track.js library. This forms the basis for aggregate and visitor-specific recommendations.

Initial setup

Option 1: Script loader pattern

Step 1: Add the SDK to your website.

Copy and paste this snippet into your HTML page:

<script>(function(P,R,O,D,U,C,T){  P.ProductCarouselObject=U,P[U]=P[U]||function(){(P[U].q=P[U].q||[]).push(arguments)};  P[U].l=1*new Date,P[U].q=[],C=R.createElement(O);  T=R.getElementsByTagName(O)[0],C.async=1,C.src=D,T.parentNode.insertBefore(C,T);})(window, document, 'script', 'https://site-sdk.cordial.io/prod-rec/$DATE/$COMMIT_SHA/product-carousel-sdk.umd.js', 'ProductCarousel');</script>

Step 2: Add a container element.

Place this <div> where you want the carousel to appear:

<div id="my-carousel"></div>

Step 3: Initialize and load recommendations.

<script>  // Initialize the carousel  ProductCarousel('init', {    containerId: 'anonymous_prod_rec',    apiEndpoint: 'https://infer.apps.cordial.io/recommend/products',    useCORSProxy: true,    eventNames: ['cart', 'productView'],    onProductClick: (product) => {      if(product.url) {        window.location.href = `${product.url}`;      }      console.log(product);    },    theme: {      primaryColor: '#007bff',      backgroundColor: 'transparent',      borderRadius: '0px',      cardShadow: 'none',      priceColor: '#6a6a6a'    },    showNavigation: true,  });    // Load recommendations with callback  ProductCarousel('loadRecommendations', {    account: 'speakercity',    product_ids: (() => {        try {            return JSON.parse(localStorage.getItem('productIDs') || '[]');        } catch (e) {            console.error('Failed to parse productIDs from localStorage:', e);            return [];        }    })()  }, function(error, response) {    if (error) {        console.error('Failed to load recommendations:', error);        return;    }    console.log('Loaded', response.recommendations.length, 'recommendations');  });</script>

Once this is in place, your anonymous product carousel is live and will react to browse and cart activity.

Option 2: Direct script include

If you prefer a more traditional script include and promise-based API, use this option.

<!-- Include the SDK directly --><script src="https://site-sdk.cordial.io/prod-rec/$DATE/$COMMIT_SHA/product-carousel-sdk.umd.js"></script><!-- Add a container --><div id="my-carousel"></div><!-- Initialize --><script>  // Initialize SDK  const sdk = ProductCarouselSDK.init({    containerId: 'my-carousel',    apiEndpoint: 'https://infer.apps.cordial.io/recommend/products'  });  // Load recommendations  sdk.then(sdkInstance => {    sdkInstance.loadRecommendations({      account: 'speakercity',      product_ids: (() => {        try {            return JSON.parse(localStorage.getItem('productIDs') || '[]');        } catch (e) {            console.error('Failed to parse productIDs from localStorage:', e);            return [];        }      })()    });  });</script>

Customizing the carousel

The Product Carousel SDK is fully configurable so you can align it with your brand and UX.

Basic customization

Use simple configuration options to control display and behavior:

<script>ProductCarousel('init', {  containerId: 'my-carousel',  apiEndpoint: 'https://api.example.com',    // Display options  showPrice: true,  showDescription: true,  maxDescriptionLength: 150,  imageAspectRatio: '1:1',    // Carousel behavior  autoPlay: true,  autoPlayInterval: 5000,  itemsToShow: 4,  showNavigation: true,  showDots: true,    // Brand colors  theme: {    primaryColor: '#007bff',    backgroundColor: '#ffffff',    borderRadius: '12px',    fontFamily: 'Arial, sans-serif'  }});</script>

Advanced theming

For more granular control over colors, typography, and layout:

ProductCarousel('init', {  containerId: 'my-carousel',  apiEndpoint: 'https://api.example.com',  theme: {    // Colors    primaryColor: '#007bff',    textColor: '#333333',    priceColor: '#28a745',    descriptionColor: '#6c757d',    backgroundColor: '#f8f9fa',        // Card styling    cardBackground: '#ffffff',    cardBorder: '1px solid #e9ecef',    cardShadow: '0 4px 6px rgba(0,0,0,0.1)',    borderRadius: '12px',        // Typography    fontFamily: 'Inter, sans-serif',    titleFontSize: '16px',    titleFontWeight: 600,    titleAlign: 'left',    priceFontSize: '18px',    priceFontWeight: 700,    priceAlign: 'right',    descriptionFontSize: '14px',    descriptionAlign: 'center'  }});

Mobile responsiveness

Configure layouts for different devices:

ProductCarousel('init', {  containerId: 'my-carousel',  apiEndpoint: 'https://api.example.com',  responsive: {    mobile: { itemsToShow: 1 },    tablet: { itemsToShow: 2 },    desktop: { itemsToShow: 4 }  }});

Integration examples

These examples show how to embed First-Visit Personalization in common site experiences.

Example 1: Product detail page

<h2>You May Also Like</h2><div id="related-products"></div><script>ProductCarousel('init', {  containerId: 'related-products',  apiEndpoint: 'https://api.example.com',  itemsToShow: 4,  theme: { primaryColor: '#ff6b6b' }});ProductCarousel('loadRecommendations', {  account: 'your-account',  product_ids: ['<%= current_product_id %>']}, function(error, response) {  if (error) console.error('Error:', error);});</script>

Example 2: Cart page

<h2>Frequently Bought Together</h2><div id="cart-recommendations"></div><script>var cartProductIds = ['prod1', 'prod2']; // from your cartProductCarousel('init', {  containerId: 'cart-recommendations',  apiEndpoint: 'https://api.example.com',  itemsToShow: 3,  showDescription: false});ProductCarousel('loadRecommendations', {  account: 'your-account',  product_ids: cartProductIds});</script>

Example 3: Homepage recommendations

<h2>Recommended For You</h2><div id="homepage-carousel"></div><script>ProductCarousel('init', {  containerId: 'homepage-carousel',  apiEndpoint: 'https://api.example.com',  autoPlay: true,  autoPlayInterval: 3000,  itemsToShow: 5,  theme: {    primaryColor: '#4CAF50',    borderRadius: '8px'  }});ProductCarousel('loadRecommendations', {  account: 'your-account',  product_ids: [] // empty for general recommendations});</script>

Example 4: Custom product click handler

ProductCarousel('init', {  containerId: 'my-carousel',  apiEndpoint: 'https://api.example.com',  onProductClick: function(product) {    // Track analytics    gtag('event', 'product_click', {      product_id: product.productID,      product_name: product.productName,      price: product.price    });        // Navigate to product page    window.location.href = '/products/' + product.productID;  }});

Data attribute configuration

For simple integrations, you can configure the carousel directly in HTML. The SDK will automatically initialize any element with the product-carousel-sdk class.

<div class="product-carousel-sdk"     id="carousel-1"     data-api-endpoint="https://api.example.com"     data-auto-play="true"     data-auto-play-interval="3000"     data-show-navigation="true"     data-show-dots="true"     data-items-to-show="3"     data-primary-color="#28a745"     data-background-color="#f8f9fa"     data-text-color="#333333"     data-border-radius="12px"     data-font-family="Arial, sans-serif"></div>

Key data attributes include:

JavaScript-only configuration

Some options are only available in JavaScript (not via data attributes), including:

Example:

const sdk = ProductCarouselSDK.create('my-carousel');await sdk.init({  containerId: 'my-carousel',  apiEndpoint: 'https://api.example.com',  showPrice: true,  showDescription: false,  onProductClick: (product) => {    window.location.href = '/products/' + product.productID;  },  theme: {    titleAlign: 'left',    priceAlign: 'right'  }});

Event and data model (BroadcastChannel integration)

The SDK can listen to the x-crdl BroadcastChannel for product interaction events and automatically build up the context used for recommendations.

When enabled, the SDK:

Configuration:

ProductCarousel('init', {  containerId: 'my-carousel',  apiEndpoint: 'https://api.example.com',  eventTypes: ['event'],  eventNames: ['cart', 'productView']});

Broadcasting events from elsewhere in your application:

const channel = new BroadcastChannel('x-crdl');channel.postMessage({  action: ['event', 'cart', {    productID: 'PROD-123',    quantity: 1  }]});channel.postMessage({  action: ['event', 'productView', {    productID: 'PROD-456'  }]});

The SDK will automatically capture and store these product IDs, which can then be passed to /recommend/products.

API: Get product recommendations

First-Visit Personalization uses the recommendations API to fetch products.

Base URL: https://infer.apps.cordial.io

Endpoint: POST /recommend/products

Content-Type: application/json

Request body

{  "account": "speakercity",  "product_ids": [    "1",    "2"  ]}

cURL example:

curl --location --request POST 'https://infer.apps.cordial.io/recommend/products' \  --header 'Content-Type: application/json' \  --data-raw '{    "account": "speakercity",    "product_ids": ["1", "2"]  }'

Response schema

The API returns a JSON object with a recommendations array and optional metadata:

Example response:

{  "recommendations": [    {      "product_id": "1889075",      "score": 100.0,      "confidence": 1.0,      "category": "TVs",      "price": 713.95,      "name": "65 inch Class U6 Series Mini-LED ULED 4K Smart Google TV - 65U6N",      "description": "Hisense's 65 inch Class U6 Series Mini-LED ULED 4K Smart Google TV - 65U6N brings a perfect mix of function and style to your everyday routine.",      "url": "https://store.cordialthreads.com/collections/tvs/products/hisense-65-inch-class-u6-series-mini-led-uled-4k-smart-google-tv-65u6n",      "image_urls": [        "https://cdn.shopify.com/s/files/1/0592/9789/0510/files/28537855_fpx.jpg?v=1747713588"      ],      "total_quantity": 84,      "variants": null    }  ],  "extra": [    "verified"  ]}

Styling and theming

The SDK exposes CSS custom properties, which you can override in your own stylesheet to align with your brand:

:root {  /* Base colors */  --pc-sdk-primary-color: #007bff;  --pc-sdk-secondary-color: #6c757d;  --pc-sdk-background-color: #ffffff;  --pc-sdk-text-color: #333333;  --pc-sdk-border-radius: 8px;  --pc-sdk-font-family: Montserrat, sans-serif;  /* Card styling */  --pc-sdk-card-background: #ffffff;  --pc-sdk-card-border: 1px solid #e9ecef;  --pc-sdk-card-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);  /* Button styling */  --pc-sdk-button-color: #007bff;  --pc-sdk-button-hover-color: #0056b3;  /* Text colors */  --pc-sdk-price-color: #28a745;  --pc-sdk-description-color: #6c757d;  /* Text alignment */  --pc-sdk-title-align: center;  --pc-sdk-description-align: center;  --pc-sdk-price-align: center;  /* Font weights and sizes */  --pc-sdk-title-font-weight: 600;  --pc-sdk-description-font-weight: 400;  --pc-sdk-price-font-weight: 700;  --pc-sdk-title-font-size: 12px;  --pc-sdk-description-font-size: 12px;  --pc-sdk-price-font-size: 12px;}

Example overrides:

.pc-sdk-product-card {  transition: transform 0.3s ease !important;}.pc-sdk-product-card:hover {  transform: translateY(-4px) !important;  box-shadow: 0 8px 16px rgba(0,0,0,0.2) !important;}.pc-sdk-product-title {  font-weight: 700 !important;  text-transform: uppercase !important;}

You can also update the theme at runtime:

<script>sdk.updateTheme({  primaryColor: '#28a745',  backgroundColor: '#f8fff9',  borderRadius: '12px'});
</script>

Troubleshooting

Carousel not appearing

Symptoms: the container is empty and no products display.

Check:

Debug example:

ProductCarousel('init', {  containerId: 'my-carousel',  apiEndpoint: 'https://api.example.com'}, function(error) {  if (error) {    console.error('Initialization error:', error);  } else {    console.log('SDK initialized successfully!');  }});

Products not loading

Symptoms: loading state persists and recommendations never render.

Check:

Test with:

curl -X POST https://api.example.com/recommend/products \  -H "Content-Type: application/json" \  -d '{"account":"your-account","product_ids":["prod1","prod2"]}'

Styling issues

If the carousel style does not match your site:

Performance problems

If you see slow loading or lag: