LoyaltyMatch Embed Plugins

Getting Started with LoyaltyMatch Embed

This guide walks you through integrating the LoyaltyMatch floating widget and companion plugins in under 10 minutes.

Prerequisites

  • LoyaltyMatch account with API access enabled
  • API credentials:
    • API Base URL (for example, https://yourdomain.myloyaltymatch.com)
    • ODPASS key for authenticated endpoints

Quick Start Guide

Option 1: Static Website (Fastest)

Perfect for HTML sites, WordPress, Shopify, or any implementation without a build step.

Step 1: Add Script Tag
<script src="https://loyaltymatch.com/node/latest/includes/loyalty-plugin.min.js"></script>
Step 2: Configure (Optional)
<script>
  loyaltyPlugin.configure({
    apiBaseUrl: '/loyaltymatch',
    floatPosition: 'right'
  });
</script>
Step 3: Set Up Proxy Server

The widget calls your proxy (not the LoyaltyMatch API directly). See the Express example referenced below for an end-to-end server.

Option 2: Node.js Application (Recommended)

Ideal for Express, Next.js, or any Node-based web application.

Step 1: Install Packages
npm install https://loyaltymatch.com/node/latest/loyaltymatch-embed-plugin.tgz https://loyaltymatch.com/node/latest/loyaltymatch-proxy-server.tgz

Direct downloads:

Step 2: Set Up Proxy Server
// server.js
const express = require('express');
const loyaltyProxy = require('@loyaltymatch/proxy-server');
require('dotenv').config();

const app = express();

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

app.use('/plugins', express.static('node_modules/@loyaltymatch/embed-plugin/dist'));

app.listen(3000);

Note: If you plan to enable the Registration Plugin with Vinoshipper, configure the Vinoshipper variables in your .env file and pass them through your proxy configuration.

Step 3: Create .env File
LOYALTYMATCH_API_BASE_URL=https://yourdomain.myloyaltymatch.com
LOYALTYMATCH_ODPASS=your-odpass-key

# Vinoshipper Configuration
# Replace with your actual Vinoshipper Account ID (numeric) API Key and Secret
VINOSHIPPER_ACCOUNT_ID=12345
VINOSHIPPER_API_KEY=your-api-key
VINOSHIPPER_SECRET=your-secret
VINOSHIPPER_API_URL=vinoshipper-api-url
VINOSHIPPER_CLUB_ID=your-club-id
Step 4: Add to Your HTML
<script src="/plugins/loyalty-plugin.min.js"></script>
<script>
  loyaltyPlugin.configure({
    apiBaseUrl: '/loyaltymatch'
  });
</script>
Step 5: Start Server
node server.js

Visit http://localhost:3000 to confirm the floating loyalty widget appears.

What You Get

  • ⭐ Floating loyalty widget that launches anywhere on your site
  • 🔐 Secure token-based authentication handled through your proxy
  • 📊 Member dashboard with live points and activity
  • 🎁 Rewards browsing with categories, search, and pagination
  • 🛒 Shopping cart with redemption checkout flow
  • 👤 Account management for member profile data

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

4. Registration Plugin

Member registration form with validation for new program sign-ups.

Key Features:

  • Form Validation - Real-time client-side validation for all fields
  • Required Fields - Email, Date of Birth, Address (City, State, Postal Code, Country)
  • Optional Fields - Name, Phone, Company, Salutation
  • Responsive Design - Mobile-friendly form layout with validation states
  • API Integration - Secure server-side submission via proxy
  • Callbacks - Success and error handlers for custom workflows
  • Auto-initialization - Optional data-attribute based setup

Technical Specifications:

  • File Size: ~20KB minified
  • Dependencies: None
  • Browser Support: All modern browsers (ES6+)
  • Validation: Email format, required field checks

Additional Plugins

Rewards Display Plugin

Render a full-page rewards showcase for marketing pages.

<div id="loyaltymatch-rewards-display"></div>
<script src="https://loyaltymatch.com/node/latest/includes/rewards-display.min.js"></script>
<script>
  new LoyaltyMatchRewardsDisplay({
    apiBaseUrl: '/loyaltymatch/api',
    itemsPerPage: 12
  });
</script>

Badge Plugin

Highlight member badges and achievements on any page.

<div id="loyaltymatch-badges"></div>
<script src="https://loyaltymatch.com/node/latest/includes/badge-plugin.min.js"></script>
<script>
  new LoyaltyMatchBadgePlugin({
    apiBaseUrl: '/loyaltymatch/api',
    token: 'user-token-here'
  });
</script>

Registration Plugin

Embed a member registration form for program sign-ups.

<div id="loyaltymatch-registration"></div>
<script src="https://loyaltymatch.com/node/latest/includes/registration-plugin.min.js"></script>
<script>
  new LoyaltyMatchRegistrationPlugin({
    apiBaseUrl: '/loyaltymatch',
    containerId: 'loyaltymatch-registration',
    onSuccess: function(result) {
      console.log('Registration successful!', result);
    },
    onError: function(error) {
      console.error('Registration error:', error);
    }
  });
</script>

Distribution Methods

CDN Delivery (Fastest Implementation)

Perfect for static websites, CMSs, and quick integrations:

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

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

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

<!-- Registration Plugin -->
<script src="https://loyaltymatch.com/node/latest/includes/registration-plugin.min.js"></script>

Non-minified (debugging):

<!-- Loyalty Widget -->
<script src="https://loyaltymatch.com/node/latest/includes/loyalty-plugin.js"></script>

<!-- Rewards Display -->
<script src="https://loyaltymatch.com/node/latest/includes/rewards-display.js"></script>

<!-- Badge Plugin -->
<script src="https://loyaltymatch.com/node/latest/includes/badge-plugin.js"></script>

<!-- Registration Plugin -->
<script src="https://loyaltymatch.com/node/latest/includes/registration-plugin.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 https://loyaltymatch.com/node/latest/loyaltymatch-embed-plugin.tgz https://loyaltymatch.com/node/latest/loyaltymatch-proxy-server.tgz
// ES6 Import
import { LoyaltyPlugin, LoyaltyMatchRewardsDisplay, LoyaltyMatchBadgePlugin, LoyaltyMatchRegistrationPlugin } from '@loyaltymatch/embed-plugin';

// CommonJS
const { LoyaltyPlugin, LoyaltyMatchRewardsDisplay, LoyaltyMatchBadgePlugin, LoyaltyMatchRegistrationPlugin } = 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

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/node/latest/includes/loyalty-plugin.min.js"></script>
  <script src="https://loyaltymatch.com/node/latest/includes/rewards-display.min.js"></script>
  <script src="https://loyaltymatch.com/node/latest/includes/badge-plugin.min.js"></script>
  <script src="https://loyaltymatch.com/node/latest/includes/registration-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 LoyaltyMatchBadgePlugin({
      apiBaseUrl: '/loyaltymatch/api',
      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 LoyaltyMatchBadgePlugin(options)

Options:

  • apiBaseUrl (string): API endpoint
  • containerId (string): Container element ID
  • token (string): Member token (optional)
  • showProgress (boolean): Show progress bars
  • showActivities (boolean): Show badge activity feed
  • theme (string): Theme name

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) { }

Registration Plugin API

Initialization

const registration = new LoyaltyMatchRegistrationPlugin(options)

Options:

  • apiBaseUrl (string): Proxy server endpoint (required)
  • containerId (string): Container element ID (required)
  • onSuccess (function): Callback after successful registration
  • onError (function): Callback if registration fails

Form Fields

Required: Email, Date of Birth, Address Line 1, City, State/Region, Postal Code, Country

Optional: Salutation, First Name, Last Name, Company Name, Phone Number, Address Line 2

Request Format

{
  "salutation": "Mr.",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phoneNumber": "(555) 123-4567",
  "dateOfBirth": "1990-01-15",
  "companyName": "Acme Corp",
  "addressLine1": "123 Main St",
  "addressLine2": "Apt 4B",
  "city": "Springfield",
  "region": "IL",
  "postalCode": "62701",
  "country": "USA"
}

Callbacks

// Success callback
onSuccess: function(result) {
  console.log('Registration complete:', result);
  // Redirect or update UI
}

// Error callback
onError: function(error) {
  console.error('Registration failed:', error);
  // Show error message to user
}

Customization Options

Visual Customization

Loyalty Widget

loyaltyPlugin.configure({
  apiBaseUrl: '/loyaltymatch',     // Required: proxy endpoint
  floatPosition: 'right',          // Optional: 'left' or 'right'
  pluginId: 'loyalty-match-plugin' // Optional: Custom ID
});

Rewards Display

const rewards = new LoyaltyMatchRewardsDisplay({
  apiBaseUrl: '/loyaltymatch/api', // Required
  containerId: 'rewards-container', // Optional
  itemsPerPage: 12,
  showCategories: true,
  showSearch: true,
  theme: 'default'
});

Badge Plugin

const badges = new LoyaltyMatchBadgePlugin({
  apiBaseUrl: '/loyaltymatch/api', // Required
  token: 'user-token',             // Optional member token
  containerId: 'badges-container', // Optional
  showProgress: true,
  showActivities: true,
  theme: 'default'
});

Registration Plugin

const registration = new LoyaltyMatchRegistrationPlugin({
  apiBaseUrl: '/loyaltymatch',     // Required: proxy endpoint
  containerId: 'registration-form', // Required: container element
  onSuccess: function(result) {
    console.log('User registered:', result);
    window.location.href = '/welcome';
  },
  onError: function(error) {
    console.error('Registration error:', error);
  }
});

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

Do

  • Use a proxy server to handle all API authentication
  • Store credentials in environment variables and rotate them regularly
  • Serve the widget over HTTPS in every environment
  • Validate user input server-side and apply appropriate CORS policies

Don't

  • Expose API credentials or ODPASS keys in client-side code
  • Hard-code API keys inside JavaScript bundles
  • Skip CORS configuration on your proxy routes
  • Trust client-side data without additional validation

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
Registration Plugin ~20KB ~7KB <0.5s

Next Steps

  1. Explore Examples: Start with the Static Website Example and Express.js Example inside the examples directory.
  2. Read Documentation: Review the client plugin and proxy server READMEs inside packages/embed-plugin and packages/proxy-server.
  3. Customize: Layer on custom styles, event handlers, and auth integrations that match your stack.

Troubleshooting

Plugins Not Loading?

  • Check browser console for errors
  • Verify every script src URL is correct
  • Ensure scripts load after the DOM is ready

API Errors?

  • Verify the proxy server is running
  • Check that environment variables are set
  • Confirm API credentials are correct
  • Review CORS settings on the proxy

Login Not Working?

  • Verify the /api/login proxy endpoint responds
  • Inspect the browser network tab for failed requests
  • Confirm test credentials are valid

Registration Form Issues?

  • Verify the proxy POST /api/register endpoint is accessible
  • Check that required fields are present in the form submission
  • Verify email validation is passing in the form
  • Check the network tab to see the API request and response
  • Ensure onSuccess and onError callbacks are properly defined

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

Member Registration & Onboarding

Embed the registration form on sign-up pages to quickly onboard new members into your loyalty program. Validate member data in real-time and submit to your backend system.

Best For: New member acquisition, welcome pages, mobile-friendly registration flows

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

If you need help implementing or extending the embed plugins:

  • Email: support@loyaltymatch.com
  • Documentation: See the client and proxy README files inside each package
  • Examples: Review the code inside the /examples directory

License

Proprietary – LoyaltyMatch

Ready to get started? Choose the integration path above and follow the steps.