Elements SDK

The Elements SDK is a powerful and flexible toolkit designed to help partners integrate e-commerce components into their websites with minimal effort. By using the Elements SDK, clients with an existing partner account can quickly create a fully functional e-commerce website with just a few lines of code. This SDK is a product of LiquidCommerce, designed to simplify e-commerce integration.

Key Features

• Ease of Integration: Add e-commerce functionality to your website with minimal setup.
• Customizable Components: Render and customize components like product detail pages, carts, addresses, and checkout.
• Event Subscriptions: Subscribe to various events such as add-to-cart, checkout, and more to enhance interactivity.
• Preview Mode: Visualize components in a static, non-functional mode for design and builder tools.

Installation

NPM

pnpm add @liquidcommerce/elements-sdk

Browser

<script id="liquidScriptConfigs" data-liquid-element-id="#product-detail" data-liquid-token="your-elements-api-key" data-liquid-product="your-product-upc" type="text/javascript" src="./elements-script.js"></script>

Usage

1. Initialize the SDK

import { ElementsSDK } from '@liquidcommerce/elements-sdk';

const API_KEY = 'your-api-key';
const GOOGLE_API_KEY = 'your-google-api-key';
const ELEMENTS_API_KEY = 'your-elements-api-key';

const sdk = ElementsSDK.init({
  apiKey: API_KEY,
  googleApiKey: GOOGLE_API_KEY,
  elementsApiKey: ELEMENTS_API_KEY,
});

2. Render Components

Product Detail Page (PDP)

<div id="product-detail"></div>

<script>
sdk.inject('product-detail', sdk.ComponentType.PDP, {
  upc: 'your-product-upc',
});
</script>

Cart Component

<div id="cart"></div>

<script>
sdk.inject('cart', sdk.ComponentType.CART, { previewMode: false });
</script>

Address Component

<div id="address"></div>

<script>
sdk.inject('address', sdk.ComponentType.ADDRESS, {
  previewMode: false,
  injectedByPdp: false,
});
</script>

Checkout Component

<div id="checkout"></div>

<script>
sdk.inject('checkout', sdk.ComponentType.CHECKOUT, {});
</script>

3. Preview Mode

Preview mode is designed for visualizing components as static screenshots or mockups. It is not intended for functional usage. To enable preview mode, set previewMode: true in the component options. This is typically used in builder tools or design environments.

Example:

<div id="cart"></div>

<script>
sdk.inject('cart', sdk.ComponentType.CART, { previewMode: true });
</script>

4. Subscriptions

You can subscribe to various events triggered by the SDK components. Below are some examples:

Add to Cart Event

sdk.subscribe(sdk.EventType.ADD_TO_CART, (data) => {
  console.log('Add to Cart Event:', data);
});

Checkout Event

sdk.subscribe(sdk.EventType.CHECKOUT, (data) => {
  console.log('Checkout Event:', data);
});

Quantity Decrease Event

sdk.subscribe(sdk.EventType.PDP_QTY_DECREASE, (data) => {
  console.log('Quantity Decrease Event:', data);
  console.log('Quantity is:', data.quantity);
});

5. Window-Based Subscriptions

The SDK also supports a window-based subscription system for additional flexibility.

Add to Cart Event

window.actions.subscribe(sdk.EventType.ADD_TO_CART, (data) => {
  console.log('Window Actions - Add to Cart:', data);
});

Quantity Decrease Event

window.actions.subscribe(sdk.EventType.PDP_QTY_DECREASE, (data) => {
  console.log('Window Actions - Quantity Decrease:', data);
  console.log('Quantity is:', data.quantity);
});

Email Input Event

window.form.subscribe(sdk.EventType.EMAIL_INPUT, (data) => {
  console.log('Window Form - Email Input:', data);
  console.log('Email is:', data.value);
});

Demos

We provide two demos to help you get started quickly:

1. Simple HTML Demo

Navigate to the demo/umd/ folder and open the index.html file in your browser. You can also use a live server to preview the demo.

2. React Demo

Navigate to the demo-react/elements-demo/ folder and follow these steps:

1. Install dependencies:

   npm install

2. Start the development server:

   npm start

3. Open the demo in your browser to explore the React-based implementation.

Development

1. Install dependencies:

pnpm install

2. Start development server:

pnpm dev

3. Build for production:

pnpm build

License

MIT