TruCustom SDK - Integration Examples

Method 1: Data Attributes (Zero JS Required)

The easiest way to add the customizer. Just add data attributes to an element:

<!-- Container where customizer will render -->
<div id="customizer"
     data-pc-product-id="YOUR_PRODUCT_ID"
     data-pc-store-id="YOUR_STORE_ID"
     data-pc-template-id="OPTIONAL_TEMPLATE_ID"
     data-pc-variant-id="OPTIONAL_VARIANT_ID"
     data-pc-on-finalize="handleFinalize">
</div>

<!-- Include SDK - it auto-detects its host from script src -->
<script src="/sdk/product-customizer.js" data-pc-auto-init></script>

<script>
// Register callback for when design is finalized
ProductCustomizer.registerCallback('handleFinalize', function(data) {
  console.log('Design finalized!', data);
  // Add to cart logic here
});
</script>

Tip: The SDK automatically detects the API host from where the script is loaded. No configuration needed if you're using the hosted version.

Method 2: JavaScript API

For more control, initialize programmatically:

<script src="/sdk/product-customizer.js"></script>
<script>
const customizer = ProductCustomizer.init({
  container: '#customizer',
  productId: 'prod_abc123',
  storeId: 'store_xyz',
  templateId: 'tmpl_001',        // Optional: pre-load template
  variantId: 'var_red',          // Optional: pre-select variant
  token: 'existing_session',     // Optional: resume design
  mode: 'inline',                // 'inline' | 'modal' | 'fullscreen'
  theme: {
    primaryColor: '#4f46e5',
    fontFamily: 'Inter, sans-serif'
  },
  onReady: (instance) => {
    console.log('Customizer ready!');
  },
  onDesignChange: (design) => {
    console.log('Design changed:', design);
  },
  onFinalize: (data) => {
    console.log('Finalized:', data);
    addToCart(data);
  },
  onError: (error) => {
    console.error('Error:', error);
  }
});

// Control methods
customizer.setVariant('var_blue');
customizer.save();
customizer.finalize();
customizer.destroy();
</script>

Method 3: Button Trigger (Modal)

Open the customizer in a modal when user clicks a button:

<!-- Customize button with data attributes -->
<button data-pc-open
        data-pc-product-id="prod_abc123"
        data-pc-store-id="store_xyz"
        data-pc-variant-id="var_red">
  Customize This Product
</button>

<script src="/sdk/product-customizer.js" data-pc-auto-init></script>

Live Demo:

Configuration Options

Option	Data Attribute	Type	Description
`productId`	`data-pc-product-id`	String (required)	Your product ID
`storeId`	`data-pc-store-id`	String (required)	Your store ID from the dashboard
`templateId`	`data-pc-template-id`	String	Pre-load a design template
`variantId`	`data-pc-variant-id`	String	Pre-select product variant
`token`	`data-pc-token`	String	Session token to resume existing design
`mode`	`data-pc-mode`	String	`inline`, `modal`, or `fullscreen`
`theme`	`data-pc-theme`	Object/JSON	Custom theming options
`onFinalize`	`data-pc-on-finalize`	Function/String	Callback when design is finalized

E-commerce Integration Example

Complete example for adding customized products to cart:

<script src="/sdk/product-customizer.js"></script>
<script>
ProductCustomizer.init({
  container: '#customizer',
  productId: '{{ product.id }}',
  storeId: 'YOUR_STORE_ID',
  variantId: '{{ selected_variant.id }}',
  
  onFinalize: function(data) {
    // data contains:
    // - design: { id, session_token, canvas_data, preview_url }
    // - product: { id, name }
    // - variant: selected variant ID
    // - previewUrl: base64 preview image
    
    // Add to cart with customization data
    fetch('/cart/add', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        product_id: data.product.id,
        variant_id: data.variant,
        quantity: 1,
        properties: {
          _customization_id: data.design.id,
          _customization_preview: data.previewUrl,
          _customization_token: data.design.session_token
        }
      })
    })
    .then(res => res.json())
    .then(cart => {
      // Redirect to cart or show success
      window.location.href = '/cart';
    });
  }
});
</script>

Platform-Specific: Swell

<!-- In your Swell product template -->
<div id="customizer"
     data-pc-product-id="{{ product.id }}"
     data-pc-store-id="{{ store.customizer_store_id }}"
     data-pc-variant-id="{{ selected_option.id }}">
</div>

<script src="{{ settings.customizer_host }}/sdk/product-customizer.js"></script>
<script>
ProductCustomizer.init({
  container: '#customizer',
  productId: '{{ product.id }}',
  storeId: '{{ store.customizer_store_id }}',
  
  onFinalize: async function(data) {
    // Swell cart integration
    await swell.cart.addItem({
      product_id: '{{ product.id }}',
      quantity: 1,
      options: {
        customization_design_id: data.design.id,
        customization_preview: data.previewUrl
      }
    });
    
    // Refresh cart
    window.location.reload();
  }
});
</script>

Deployment & Configuration

Self-Hosted Setup

Set these environment variables on your TruCustom server:

# .env or environment configuration
APP_URL=https://customizer.yourdomain.com
RAILS_ENV=production

# Database
DATABASE_URL=postgres://user:pass@host:5432/product_customizer

# File Storage (AWS S3)
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_REGION=us-east-1
AWS_BUCKET=your-bucket

# Optional: Redis for caching
REDIS_URL=redis://localhost:6379/0

Embed Snippet Generator

Your dashboard provides a ready-to-use embed snippet with your store ID pre-filled:

<!-- Generated from Dashboard → Stores → [Your Store] → Embed Code -->
<script 
  src="https://customizer.yourdomain.com/sdk/product-customizer.js"
  data-pc-store-id="your-actual-store-id"
  data-pc-auto-init>
</script>