@gethelium/personalise

The Helium Personalisation Platform SDK makes it easy to integrate intelligent product lists, dynamic merchandising, and personalized content into your website.

Features

• AI-Powered Recommendations: Leverage machine learning to show the most relevant products to each customer
• Dynamic Product Lists: Create personalized product collections that adapt to user behavior and preferences
• Easy Integration: Simple JavaScript SDK that works with any e-commerce platform
• Shopify Native: Seamless integration with Shopify stores
• Preview Mode: Test and preview your personalization features before going live
• TypeScript Support: Full type definitions for better development experience

Quick Start

Installation

npm install @gethelium/personalise

Basic Usage

import { PersonalisationClient } from "@gethelium/personalise";

// Initialize the client (auto-detects Shopify store)
const client = new PersonalisationClient();

// Render personalized product recommendations
await client.render({
  featureHandles: ["trending", "recommended-for-you"],
  position: ".product-recommendations",
  type: "product-list",
});

That's it! Your personalized product recommendations will now appear on your website.

Detailed Usage

For Shopify Stores

The SDK automatically detects your Shopify store configuration:

import { PersonalisationClient } from "@gethelium/personalise";

const client = new PersonalisationClient();

await client.render({
  featureHandles: ["trending", "you-might-like", "frequently-bought"],
  position: ".product-recommendations",
  type: "product-list",
});

For Custom E-commerce Platforms

import { PersonalisationClient } from "@gethelium/personalise";

const client = new PersonalisationClient("your-store-id", {
  apiBaseUrl: "https://api.heliumpersonalisation.com",
  shopifyConfig: {
    storefrontAccessToken: "your-storefront-token",
    shop: "your-store.myshopify.com",
  },
});

await client.render({
  featureHandles: ["featured", "on-sale", "new-arrivals"],
  position: "#recommendations-container",
  type: "product-list",
});

Preview Your Features

Test your personalization features before going live:

const client = new PersonalisationClient();

await client.render({
  featureHandles: ["test-feature"],
  position: ".preview-area",
  type: "product-list",
  isPreview: true,
  previewFeatureHandle: "test-feature",
  productHandle: "current-product",
});

Use Cases

• Product Detail Pages: Show "Customers also viewed" and "Frequently bought together"
• Homepage: Display trending products and personalized recommendations
• Category Pages: Enhance category listings with AI-powered sorting
• Cart Page: Suggest complementary products to increase average order value
• Email Campaigns: Generate personalized product recommendations for email content

⚙️ Configuration

PersonalisationClient Options

interface PersonalisationConfig {
  apiBaseUrl: string; // Your Helium API endpoint
  shopifyConfig?: {
    // Required for Shopify integration
    storefrontAccessToken: string;
    shop: string;
  };
  websiteUrl?: string; // Custom website URL for config loading
}

Render Options

interface RenderOptions {
  featureHandles: string[]; // Array of feature identifiers
  position: string; // CSS selector where to render
  type: "product-list"; // Currently supports product lists
  productHandle?: string; // Current product handle (optional)
  isPreview?: boolean; // Enable preview mode
  previewFeatureHandle?: string; // Specific feature to preview
}

Advanced Configuration

Custom Styling

The SDK renders product cards with default styling that you can customize:

/* Customize product card appearance */
.feature-container {
  margin: 2rem 0;
}

.product-card {
  /* Your custom product card styles */
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

License

MIT License - see LICENSE file for details.

Support

Need help? Contact our support team or check out our website.

Made with ❤️ by the Helium team