FairShare SDK Integration Guide

The FairShare SDK provides powerful e-commerce features that are automatically included in your Fluid application. This document explains how to use the pre-integrated SDK in your application.

For complete SDK documentation and advanced usage, see the Full SDK Documentation (NPM Package).

Automatic SDK Integration

If you are using themes within Fluid application, the FairShare SDK is already integrated by default. The following script tags are automatically injected into your application:

<script src="/assets/fairshare-[hash].js"></script>
<script>
let config = { 
  apiUrlHost: "https://[your-domain]/", 
  fluid_shop: "[your-shop].fluid.app", 
  country: "us", // country based on cookie or us
  featureConfig: { 
    cart: { 
      enabled: true,
      selector: '#cart-count'
    }, 
    chat: {
      enabled: true // based on the configuration on admin
    }, 
    country: "us" 
  },
};
</script>
<script>
document.addEventListener('DOMContentLoaded', function(e) { 
  window.fluid = {}; 
  FluidSDK.getInstance().initialize(config).then(() => { 
    console.log('Fluid SDK initialized') 
    document.dispatchEvent(new CustomEvent('fluidSdk:initialized', { 
      bubbles: true, 
      detail: { config } 
    })) 
  }); 
});
</script>

Configuration Parameters

The auto-injected script includes these key parameters:

Parameter	Description
`apiUrlHost`	Your API endpoint URL (can be your custom domain)
`fluid_shop`	Your Fluid shop identifier (your Fluid subdomain)
`country`	Default country code for localization
`featureConfig`	Feature-specific configuration options

Note on Backend vs Frontend Configuration

The configuration is automatically generated by the Rails backend
Default values are provided for each shop based on your admin settings
You can customize these settings in the Fluid Admin Dashboard

SDK Features Overview

The FairShare SDK provides four main components to enhance your e-commerce site:

1. Cart

Shopping cart functionality that can be displayed in different styles.

// Access the cart functionality
const cart = FluidSDK.cart();

// Check current cart data
console.log(cart.data);

// Add an item to the cart
await cart.add([{ variant_id: 123, quantity: 1 }]);

2. Chat

Customer support chat integration that appears as a widget on your site.

// Access the chat functionality
const chat = FluidSDK.chat();

// Show/hide the chat widget
chat.show();
chat.hide();

Promotional banners that can be displayed at the top of your site.

// Access the banner functionality
const banner = FluidSDK.banner();

// Show a promotional message
banner.update({
  text: 'Limited Time Offer!',
  buttonText: 'Shop Now'
});

4. Global Settings

Cross-cutting configurations like language and country settings.

// Access global settings
const globals = FluidSDK.global();

// Change the language or country
globals.changeLanguage('fr');
globals.changeCountry('CA');

Customizing the SDK in Your Application

While the SDK is automatically included, you can still customize its behavior after initialization:

Listening for SDK Initialization

document.addEventListener('fluidSdk:initialized', function(event) {
  // SDK is now initialized and ready to use
  const cart = FluidSDK.cart();
  
  // Custom initialization logic
  setupCustomCartButtons();
});

Creating Custom UI Elements

// Example: Create a custom "Add to Cart" button
function setupCustomCartButtons() {
  const addToCartButtons = document.querySelectorAll('.custom-add-to-cart');
  
  addToCartButtons.forEach(button => {
    button.addEventListener('click', async function() {
      const variantId = this.dataset.variantId;
      const quantity = parseInt(this.dataset.quantity || '1');
      
      try {
        await FluidSDK.cart().add([{ 
          variant_id: parseInt(variantId), 
          quantity: quantity 
        }]);
        
        // Success feedback
        button.textContent = 'Added!';
        setTimeout(() => {
          button.textContent = 'Add to Cart';
        }, 2000);
      } catch (error) {
        console.error('Failed to add item to cart:', error);
        // Error feedback
        button.textContent = 'Failed';
        setTimeout(() => {
          button.textContent = 'Add to Cart';
        }, 2000);
      }
    });
  });
}

Troubleshooting Common Issues

SDK Not Initializing

If the SDK is not initializing properly:

Check the browser console for error messages
Verify that your domain is correctly set up in the Fluid Admin Dashboard
Ensure there are no JavaScript errors on your page preventing the SDK script from loading

Cart Not Showing or Updating

If the cart is not visible or not updating correctly:

Verify the cart is enabled in your configuration with cart.enabled: true
Check that the cart flavor is set correctly (icon, drawer, or none)
Inspect network requests to ensure API calls are succeeding

If the chat widget is not appearing:

Confirm that chat is enabled with chat: true in your initSettings
Check if any CSS on your site might be hiding the chat widget
Verify that chat agents are available in your Fluid Admin Dashboard

Further Resources

For more detailed documentation on the FairShare SDK:

Support

If you encounter any issues with the FairShare SDK, please contact our support team.