LoyaltyMatch Embed Plugins

Overview

LoyaltyMatch Embed is a comprehensive JavaScript plugin suite that enables businesses to integrate full-featured loyalty program functionality into any website. Built with pure vanilla JavaScript and zero dependencies, it provides drop-in components for member authentication, rewards management, achievement tracking, and checkout functionality.

The solution transforms any web property into a complete loyalty program platform through client-side plugins and secure server-side middleware, all without requiring complex backend development.

Architecture

The LoyaltyMatch Embed ecosystem consists of two main packages:

Client Package: @loyaltymatch/embed-plugin

Client-side JavaScript plugins that run in the browser and provide all user-facing loyalty program features. These plugins are framework-agnostic and work with any website technology.

Server Package: @loyaltymatch/proxy-server

Express.js middleware that securely proxies API requests, handles authentication, and manages CORS policies. This keeps sensitive credentials server-side while enabling seamless client-side functionality.

Security Model

The architecture follows a proxy pattern for security:

User Browser → Client Plugin → Your Proxy Server → LoyaltyMatch API
  • Client plugins make API calls to your server (not directly to LoyaltyMatch)
  • Proxy middleware adds authentication headers server-side
  • API credentials never exposed to the browser
  • CORS issues handled automatically by the proxy

Available Plugins

1. Loyalty Widget Plugin

A complete floating loyalty program interface providing a full member experience.

Key Features:

  • Member Authentication - Token-based secure login system with session management
  • Member Dashboard - Real-time points balance and activity history
  • Rewards Catalog - Live rewards browsing with category navigation
  • Shopping Cart System - Add-to-cart functionality with quantity controls
  • Checkout Flow - Complete redemption processing with address management
  • Profile Management - Personal information and address updates
  • UI/UX Features - Non-intrusive floating button with smooth animations

Technical Specifications:

  • File Size: ~50KB minified
  • Dependencies: None
  • Browser Support: All modern browsers (ES6+)
  • Auto-initialization: Loads and activates automatically

2. Rewards Display Plugin

A standalone public-facing rewards showcase component perfect for marketing pages.

Key Features:

  • Catalog Display - Grid-based reward layout with professional imagery
  • Search & Filtering - Real-time search and category-based filtering
  • Pagination - Configurable items per page with smooth transitions
  • Customization - Theme support for custom styling and behaviors
  • Public Access - No authentication required, SEO-friendly

Technical Specifications:

  • File Size: ~35KB minified
  • Dependencies: None
  • API Calls: Public endpoints only
  • Performance: Efficient pagination with caching

3. Badge Plugin

Achievement and gamification system for member engagement.

Key Features:

  • Badge Display - Visual badge gallery with earned/locked differentiation
  • Progress Tracking - Animated progress indicators with milestone celebrations
  • Integration Features - Automatic sync with loyalty widget
  • Gamification Elements - Visual achievement recognition and progress motivation

Technical Specifications:

  • File Size: ~30KB minified
  • Dependencies: None
  • Modes: Public (all badges) and Authenticated (personal progress)
  • Integration: Auto-connects with loyalty widget

Distribution Methods

CDN Delivery (Fastest Implementation)

Perfect for static websites, CMSs, and quick integrations:

<!-- Loyalty Widget -->
<script src="https://loyaltymatch.com/plugins/loyalty-plugin.min.js"></script>

<!-- Rewards Display -->
<script src="https://loyaltymatch.com/plugins/rewards-display.min.js"></script>

<!-- Badge Plugin -->
<script src="https://loyaltymatch.com/plugins/badge-plugin.min.js"></script>

Advantages: Zero build process, fast delivery, hosted infrastructure, works immediately

npm Installation (Modern Development)

Ideal for React, Vue, Angular, and build-system projects:

npm install @loyaltymatch/embed-plugin@https://loyaltymatch.com/node/loyaltymatch-embed-plugin-1.1.3.tgz @loyaltymatch/proxy-server@https://loyaltymatch.com/node/loyaltymatch-proxy-server-1.1.3.tgz
// ES6 Import
import { LoyaltyPlugin, RewardsDisplay, BadgePlugin } from '@loyaltymatch/embed-plugin';

// CommonJS
const { LoyaltyPlugin, RewardsDisplay } = require('@loyaltymatch/embed-plugin');

Advantages: Version locking, bundler optimization, local development, dependency management

Self-Hosted Option

Download and host files directly on your server:

<script src="/js/loyalty-plugin.min.js"></script>

Advantages: Complete control, no external dependencies, custom caching policies, offline capability

Quick Start Guide

Step 1: Set Up Proxy Server

// server.js
const express = require('express');
const loyaltyProxy = require('@loyaltymatch/proxy-server');

const app = express();

app.use('/loyaltymatch', loyaltyProxy({
  apiBaseUrl: process.env.LOYALTYMATCH_API_BASE_URL,
  odpass: process.env.LOYALTYMATCH_ODPASS
}));

app.listen(3000);

Step 2: Add Plugin to Website

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <!-- Your content -->
  
  <!-- LoyaltyMatch Plugin -->
  <script src="https://loyaltymatch.com/plugins/loyalty-plugin.min.js"></script>
  <script>
    loyaltyPlugin.configure({
      apiBaseUrl: '/loyaltymatch',
      floatPosition: 'right'
    });
  </script>
</body>
</html>

That's it! The floating loyalty widget appears on your site with full functionality.

Advanced Implementation

Multiple Plugins with Badge Integration

<!DOCTYPE html>
<html>
<head>
  <title>Complete Loyalty Experience</title>
</head>
<body>
  <!-- Rewards Showcase Section -->
  <section>
    <h2>Available Rewards</h2>
    <div id="rewards-container"></div>
  </section>
  
  <!-- Member Badges Section -->
  <section>
    <h2>Achievements</h2>
    <div id="badges-container"></div>
  </section>
  
  <!-- Load All Plugins -->
  <script src="https://loyaltymatch.com/plugins/loyalty-plugin.min.js"></script>
  <script src="https://loyaltymatch.com/plugins/rewards-display.min.js"></script>
  <script src="https://loyaltymatch.com/plugins/badge-plugin.min.js"></script>
  
  <script>
    // Configure loyalty widget
    loyaltyPlugin.configure({
      apiBaseUrl: '/loyaltymatch',
      floatPosition: 'right'
    });
    
    // Initialize rewards display
    const rewards = new LoyaltyMatchRewardsDisplay({
      apiBaseUrl: '/loyaltymatch/api',
      containerId: 'rewards-container',
      itemsPerPage: 12,
      showCategories: true,
      showSearch: true
    });
    
    // Initialize badge plugin
    const badges = new BadgePlugin({
      apiBaseUrl: '/loyaltymatch',
      containerId: 'badges-container'
    });
    
    // Connect badge plugin to loyalty widget
    loyaltyPlugin.connectBadgePlugin(badges);
  </script>
</body>
</html>

Platform Compatibility

Content Management Systems

  • ✅ WordPress - Add via theme or plugin
  • ✅ Shopify - Custom HTML/CSS section
  • ✅ Wix - Embed code widget
  • ✅ Squarespace - Code injection
  • ✅ Webflow - Custom code embed

Web Frameworks

  • ✅ React - Component wrapper
  • ✅ Vue.js - Component integration
  • ✅ Angular - Service/component pattern
  • ✅ Next.js - Dynamic import
  • ✅ Nuxt - Plugin registration
  • ✅ Svelte - Action or component

Backend Systems

  • ✅ Express.js - Native middleware
  • ✅ Node.js - Any framework
  • ✅ Python/Django - Reverse proxy
  • ✅ PHP - cURL proxy
  • ✅ Ruby/Rails - HTTP client proxy
  • ✅ .NET - HttpClient proxy

API Reference

Loyalty Plugin API

Configuration

loyaltyPlugin.configure(options)

Options:

  • apiBaseUrl (string): Proxy server endpoint
  • floatPosition (string): 'left' or 'right'
  • pluginId (string): Custom DOM ID

Methods

loyaltyPlugin.connectBadgePlugin(badgeInstance)  // Connect badge plugin
loyaltyPlugin.showWidget()                       // Show widget
loyaltyPlugin.hideWidget()                       // Hide widget
loyaltyPlugin.logout()                           // Logout member

Rewards Display API

Initialization

const rewards = new LoyaltyMatchRewardsDisplay(options)

Options:

  • apiBaseUrl (string): API endpoint
  • containerId (string): Container element ID
  • theme (string): Theme name
  • itemsPerPage (number): Items per page
  • showCategories (boolean): Show category filters
  • showSearch (boolean): Show search box

Methods

rewards.setCategory(categoryId)    // Filter by category
rewards.setSearch(term)            // Search rewards
rewards.refresh()                  // Reload data
rewards.destroy()                  // Cleanup

Event Handlers

rewards.onRewardClick = function(reward) { }
rewards.onPageChange = function(page) { }
rewards.onCategoryChange = function(category) { }

Badge Plugin API

Initialization

const badges = new BadgePlugin(options)

Options:

  • apiBaseUrl (string): API endpoint
  • containerId (string): Container element ID
  • token (string): Member token (optional)
  • showProgress (boolean): Show progress bars

Methods

badges.setToken(token)              // Set member token
badges.checkForNewBadges()         // Check for new achievements
badges.refresh()                    // Reload badge data
badges.destroy()                    // Cleanup

Event Handlers

badges.onBadgeEarned = function(badge) { }
badges.onBadgeClick = function(badge) { }

Customization Options

Visual Customization

Loyalty Widget

loyaltyPlugin.configure({
  floatPosition: 'right',      // 'left' or 'right'
  primaryColor: '#007bff',      // Brand color
  buttonSize: 'medium',         // Button size
  buttonIcon: 'custom-url.png'  // Custom icon
});

Rewards Display

const rewards = new LoyaltyMatchRewardsDisplay({
  theme: 'custom',
  itemsPerPage: 16,
  columns: 4,
  showCategories: true,
  showSearch: true,
  customStyles: {
    primaryColor: '#007bff',
    cardBorderRadius: '8px',
    gridGap: '20px'
  }
});

Behavioral Customization

Custom Reward Click Handler

rewards.onRewardClick = function(reward) {
  // Custom logic
  console.log('Reward selected:', reward);
  
  // Open custom modal
  openCustomModal(reward);
  
  // Track analytics
  trackEvent('reward_view', { rewardId: reward.id });
};

Security Best Practices

  • ✅ Always use HTTPS in production
  • ✅ Keep ODPASS secret on server-side only
  • ✅ Implement rate limiting on proxy endpoints
  • ✅ Validate all inputs server-side
  • ✅ Set CORS policies appropriately
  • ✅ Monitor API usage for anomalies
  • ✅ Rotate credentials periodically
  • ✅ Use environment variables for secrets

Browser Compatibility

  • ✅ Chrome 60+ (2017)
  • ✅ Firefox 60+ (2018)
  • ✅ Safari 12+ (2018)
  • ✅ Edge 79+ (2020)
  • ✅ Mobile browsers (iOS Safari, Chrome Mobile)

Requirements: ES6 support (arrow functions, promises, classes)

Performance Metrics

Plugin Minified Size Gzipped Load Time (3G)
Loyalty Widget ~50KB ~18KB <1s
Rewards Display ~35KB ~12KB <0.7s
Badge Plugin ~30KB ~10KB <0.6s

Troubleshooting

Plugin Not Loading

  • ✅ Check script URL is correct
  • ✅ Verify no console errors
  • ✅ Ensure script loads before configuration
  • ✅ Check browser console for errors

Authentication Failing

  • ✅ Verify proxy server is running
  • ✅ Check ODPASS credentials are correct
  • ✅ Ensure apiBaseUrl points to proxy
  • ✅ Check CORS settings on proxy server

Rewards Not Displaying

  • ✅ Check API credentials
  • ✅ Verify container element exists
  • ✅ Check console for API errors
  • ✅ Ensure public endpoints are accessible

Badge Plugin Not Updating

  • ✅ Verify connectBadgePlugin() was called
  • ✅ Check badge plugin initialized before connection
  • ✅ Ensure proxy passes token correctly
  • ✅ Check badge API endpoint availability

Squarespace Plugin

For step-by-step instructions to install the loyalty iFrame on Squarespace (including a dedicated page recommendation), see the Squarespace Plugin guide.

Use Cases

E-Commerce Integration

Add loyalty redemption alongside product purchases. Members can browse rewards, add to cart, and checkout using points—all without leaving your store.

Best For: Online retailers, subscription services, marketplaces

Membership Portals

Provide members with self-service access to their loyalty account, reducing support inquiries and increasing engagement.

Best For: Associations, clubs, subscription services, SaaS platforms

Marketing Campaigns

Showcase your rewards program on landing pages to drive sign-ups and conversions. The public rewards display attracts new members.

Best For: Promotional campaigns, acquisition funnels, event pages

Employee Recognition

Embed internal recognition programs with badge achievements and reward redemption for employees or partners.

Best For: Corporate intranets, HR portals, partner portals

Hospitality & Dining

Display loyalty status and available rewards throughout your digital properties, driving repeat visits and higher spend.

Best For: Restaurants, hotels, entertainment venues, travel

Mobile Web Applications

Touch-optimized interfaces provide native-like loyalty experiences in mobile web apps without app store distribution.

Best For: Progressive web apps, mobile-first sites, hybrid apps

Support & Resources

For additional support or questions about implementing the LoyaltyMatch Embed plugins, please contact:

  • Support Email: support@loyaltymatch.com
  • Documentation: Contact support for detailed technical documentation