Fluid Web Widgets

This package provides web components for integrating Fluid into your website. It supports two distribution methods:

1. NPM Package - For bundled applications
2. CDN / Script Tag - For direct inclusion in HTML

Distribution Methods

NPM Package Distribution

Use this method if you're building a modern JavaScript application with a bundler (webpack, Vite, etc.).

Installation

# Using npm
npm install @fluid-app/web-widgets

# Using yarn
yarn add @fluid-app/web-widgets

# Using pnpm
pnpm add @fluid-app/web-widgets

Usage

// Import the components and styles
import { initializeFluid } from "@fluid-app/fluid";
import { registerWebComponents } from "@fluid-app/web-widgets";

import "@fluid-app/web-widgets/styles.css";

// Initialize Fluid SDK with your shop ID (server-side attribution)
initializeFluid({
  fluidShop: "your-shop-id",
});

// Or with attribution override - you can use any of these formats:
// Attribution by email
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    email: "[email protected]",
  },
});

// Attribution by username
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    username: "influencer-username",
  },
});

// Attribution by share GUID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    share_guid: "abc123-def456-ghi789",
  },
});

// Attribution by Fluid rep ID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    fluid_rep_id: 12345,
  },
});

// Attribution by external ID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    external_id: "external-affiliate-id",
  },
});

// Register the web components
registerWebComponents();

Then use the components in your HTML:

<fluid-cart-widget
  position="bottom-right"
  fluid-shop-display-name="Your Store Name"
></fluid-cart-widget>

CDN / Script Tag Distribution

Use this method for direct inclusion in a website without a build step.

<!-- Basic server-side attribution -->
<script
  id="fluid-cdn-script"
  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
  data-fluid-shop="your-shop-id"
  data-fluid-api-base-url="https://api.your-custom-endpoint.com"
></script>

<!-- With attribution override -->
<script
  id="fluid-cdn-script"
  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
  data-fluid-shop="your-shop-id"
  data-share-guid="your-affiliate-id"
></script>

<!-- Add the cart widget anywhere on your page -->
<fluid-cart-widget
  position="bottom-right"
  fluid-shop-display-name="Your Store Name"
></fluid-cart-widget>

Key Benefits of CDN Distribution

• No NPM installation required - Works with any HTML page
• Automatic style injection - No separate CSS file to include
• Single script tag does everything - Initializes SDK, loads styles, registers components
• Server-side attribution - Attribution calculated automatically server-side

Configuration Options

| Data Attribute | Description | Required | | ----------------------- | --------------------------------------------------------------- | -------- | | data-fluid-shop | Your Fluid shop identifier | Yes | | data-share-guid | Attribution override share GUID (overrides server-side) | No | | data-fluid-api-base-url | Custom API endpoint URL for development or testing environments | No | | data-debug | Enable debug mode (set to "true" to enable) | No |

The data-fluid-api-base-url attribute allows you to specify a custom API endpoint for local development or testing against different environments. When not provided, the system uses the default production endpoint.

Server-Side Attribution: Attribution is now calculated server-side automatically based on the current page URL. The system detects page changes (including SPA navigation) and refreshes attribution data as needed. Use data-share-guid when you need to override this with a specific attribution value.

Controlling the Cart

There are two ways to control the cart functionality:

Declarative Controls (HTML)

Use data attributes for the simplest implementation:

<button data-fluid-cart="open">Open Cart</button>
<button data-fluid-cart="close">Close Cart</button>
<button data-fluid-cart="toggle">Toggle Cart</button>

JavaScript Controls

For programmatic control:

// When using NPM package
import { closeCart, openCart, toggleCart } from "@fluid-app/react-widgets";

openCart();
closeCart();
toggleCart();

// When using CDN
window.fluidCart.open();
window.fluidCart.close();
window.fluidCart.toggle();

Displaying Cart Count

You can easily display the current cart item count anywhere on your page by using an element with the ID fluid-cart-count. The SDK will automatically update this element whenever the cart changes.

<!-- Simple cart count display -->
<span id="fluid-cart-count">0</span>

<!-- Cart count with styling -->
<div class="cart-icon">
  <i class="fas fa-shopping-cart"></i>
  <span class="badge" id="fluid-cart-count">0</span>
</div>

The cart count is updated automatically when:

• Items are added to the cart
• Items are removed from the cart
• Item quantities are updated
• The cart is cleared
• A new cart is created
• The cart is refreshed from the API

Adding Products to Cart

Declarative Product Controls (HTML)

Use data attributes to add products to cart without writing JavaScript:

<!-- Add a single product (variant) to cart -->
<button data-fluid-add-to-cart="123456">Add to Cart</button>

<!-- Specify quantity -->
<button data-fluid-add-to-cart="123456" data-fluid-quantity="2">
  Add 2 to Cart
</button>

<!-- Add to cart and open cart drawer immediately -->
<button data-fluid-add-to-cart="123456" data-fluid-open-cart-after-add="true">
  Add to Cart and View
</button>

<!-- Add with subscription enabled -->
<button data-fluid-add-to-cart="123456" data-fluid-subscribe="true">
  Add with Subscription
</button>

<!-- Add multiple products with different subscription settings -->
<button
  data-fluid-add-to-cart="123456,789012"
  data-fluid-subscribe="true,false"
>
  Add Multiple Items
</button>

<!-- Combine subscription with quantity and cart opening -->
<button
  data-fluid-add-to-cart="123456"
  data-fluid-subscribe="true"
  data-fluid-quantity="2"
  data-fluid-open-cart-after-add="true"
>
  Add 2 with Subscription and View
</button>

Adding Enrollment Packs

Enrollment packs can be added to the cart using data attributes:

<!-- Add an enrollment pack to cart -->
<button data-fluid-add-enrollment-pack="42">Add Enrollment Pack</button>

<!-- Add enrollment pack and open cart drawer immediately -->
<button
  data-fluid-add-enrollment-pack="42"
  data-fluid-open-cart-after-add="true"
>
  Add Enrollment Pack and View
</button>

Customizing Widget Styles

You can customize the widgets to match your brand's color scheme and typography using CSS variables:

/* In your CSS file */
:root {
  --company-color: #3461ff; /* Replace with your brand color */
  --ff-body: "Your Custom Font", sans-serif; /* Your custom font */
}

Available customization variables:

• --company-color: Controls primary colors, accents, and highlights
• --ff-body: Sets the font family used throughout the widgets (falls back to system fonts if not specified)

Available Components

Cart Widget (<fluid-cart-widget>)

| Attribute/Property | Type | Default | Description | | ----------------------- | ------- | -------------- | -------------------------------------------------------------------------- | | position | string | 'bottom-right' | Position on screen: 'top-left', 'top-right', 'bottom-left', 'bottom-right' | | size | number | 60 | Size of the widget button in pixels | | x-margin | number | 40 | Horizontal margin from the edge of the screen in pixels | | y-margin | number | 98 | Vertical margin from the edge of the screen in pixels | | z-index | number | 50 | Z-index for layering | | fluid-shop-display-name | string | 'My Store' | Shop name displayed in the cart header | | hide-widget | boolean | false | When true, hides button but keeps cart functionality |

Banner Widget (<fluid-banner-widget>)

| Attribute/Property | Type | Default | Description | | ------------------ | ------- | ---------- | ------------------------------------------------------------ | | title | string | - | Title text for the banner | | description | string | - | Description or promotional text | | image-url | string | - | URL for the banner image | | image-alt | string | - | Alternative text for the image | | position | string | 'center' | Position: 'top', 'bottom', 'left', 'right', 'center' | | variant | string | 'default' | Style variant: 'default', 'outline', 'vibrant', 'minimal' | | size | string | 'md' | Size of the banner: 'sm', 'md', 'lg', 'full' | | target-url | string | - | Banner click destination URL | | button-text | string | 'Shop Now' | Text for the call-to-action button | | show-button | boolean | true | Whether to show a button or make the entire banner clickable | | class-name | string | - | Optional additional CSS classes | | tracking-id | string | - | Optional tracking ID for analytics | | aspect-ratio | number | 16/9 | Aspect ratio for the banner | | hide-widget | boolean | false | When true, hides the banner completely |

For More Information

For full documentation on attribution settings and advanced configuration, refer to the @fluid-app/fluid documentation.

For a complete working example, see the cdn-example.html file in this package.