Skip to main content

​
🟠 v2.111.0 - Shopify Integration & Critical Platform Fixes

⭐⭐⭐ Complex • 5 commits • 73 files changed
This release introduces Nudj’s Shopify integration, enabling e-commerce platforms to embed loyalty and gamification widgets directly in storefronts. Additionally, we’ve resolved critical issues with challenge launching and route conflicts that were impacting user experience.

​
What’s New

  • Shopify Loyalty Widget Integration - Embed gamification directly in Shopify storefronts with a lightweight floating widget scaffold supporting authentication and user context
  • Challenge Start Hook Restoration - Fixed challenge launch functionality for both authenticated users and admin previews with improved error handling
  • Route Conflict Prevention - Protected core application routes from being claimed as community slugs, preventing navigation and routing issues

​
Apps Updated

User App

✓ Updated - 4 changes

API

✓ Updated - 3 changes

Admin

✓ Updated - 1 change

MCP Server

— No changes

Design System

✓ Updated - i18n additions

Games

— No changes

​
Detailed Changes

Nudj now integrates with Shopify storefronts, enabling retailers to create gamified loyalty experiences for customers browsing and shopping.What You Get:
  • Embedded Widget - Lightweight floating widget that can be added to any Shopify storefront
  • Authentication - Seamless authentication flow with API Link integration for customer context
  • User Context - Widget displays customer info and loyalty status without disrupting shopping experience
  • Foundation for Expansion - Phase 1 scaffold ready for adding challenges, rewards, and leaderboards in future releases
  • Multi-Language Support - i18n support across 6 languages (English, German, Spanish, French, Portuguese, Chinese)
Architecture Highlights:
  • App Proxy Integration - Uses Shopify’s App Proxy for secure server-side communication
  • JWT Token Generation - Secure token handling for customer authentication between storefronts and Nudj
  • Responsive Design - Works across desktop and mobile shopping experiences
  • Server Components - Optimized Next.js server-side rendering for performance
Implementation Details:
  • New Shopify app with storefront extension support
  • Widget service for token generation and configuration
  • User app widget pages for content delivery
  • Shopify theme extension configuration for FAB (Floating Action Button)
  • Responsive CSS with support for theme customization
Files Changed: 22 files including new Shopify app, User app widget routes, extensions, and i18n updates
Fixed critical issue preventing users from launching challenges in challenge details pages.The Problem: Challenge start functionality was inadvertently broken, affecting user ability to begin new challenges. Additionally, the hook wasn’t properly handling authentication requirements and admin preview modes.What’s Fixed:
  • Challenge Launch - Users can now successfully start challenges from challenge details pages
  • Unified Hook - useChallengeStart hook now handles all variations: standard auth flow, guest auth requirements, and admin preview mode
  • Smart Mode Detection - Automatically detects preview vs. production and handles appropriately
  • Improved Error Handling - Clear error messages when challenges can’t be started, with guidance for users
  • Cache Invalidation - Proper cache refresh after successful challenge start ensures UI updates reflect server state
Technical Improvements:
  • Removed direct API mutation calls in component in favor of centralized hook
  • Consistent error handling across both challenge detail view variants (modern and parallax)
  • Better separation of concerns with authentication logic in hook
  • Comprehensive switch statement for handling different response states (success, preview, auth_required, error)
Files Changed: 4 files (both challenge detail variants + CLAUDE.md updates for documentation)
Added validation to prevent community slugs from conflicting with core application routes.The Problem: Community admins could create communities with slugs like “a”, “api”, or “_next” that conflicted with critical app routes, causing navigation issues and routing conflicts.What’s Fixed:
  • Reserved Slug Validation - API now rejects slugs that match reserved application routes
  • Case-Insensitive Matching - Slugs are checked case-insensitively to prevent “API” or “A” bypassing validation
  • Smart Filtering - Blocks only exact matches (e.g., “a” is blocked but “alpha” and “api-docs” are allowed)
  • Clear User Feedback - Error messages clearly explain why a slug was rejected
Protected Routes:
  • /a/ - Action route for individual challenge actions
  • /api/* - API routes
  • /_next/* - Next.js internal routes
Implementation:
  • Validation added in upsert-community mutation
  • Comprehensive test coverage for all edge cases
  • Case-insensitive comparison prevents workarounds
  • Substring-safe validation allows legitimate slugs like “alpha”, “api-docs”, etc.
Files Changed: 3 files (mutation, tests, and community navigation component)
Added translations for new widget UI elements across all supported languages.Supported Languages:
  • English
  • German (Deutsch)
  • Spanish (Español)
  • French (Français)
  • Portuguese (Português)
  • Chinese (简体中文)
New Translation Keys:
  • Widget connection status messages
  • Login requirements
  • Guest user labels
  • User info display labels
  • Community context messaging
Files Changed: 6 i18n locale files

​
Breaking Changes

None - This is a fully backward-compatible release. All existing functionality continues to work as expected.

​
Technical Highlights

Shopify Integration Architecture:
  • Shopify App Proxy for secure storefront integration
  • JWT-based authentication between storefronts and Nudj
  • Lightweight widget scaffold (~100KB total including CSS/JS)
  • Support for future expansion with challenges, rewards, and leaderboards
Challenge Start Fix:
  • Centralized useChallengeStart hook reduces code duplication
  • Proper handling of three states: authenticated flow, auth-required flow, and admin preview
  • Cache invalidation strategy ensures UI consistency after mutations
Route Protection:
  • Whitelist approach with reserved slugs: [“a”, “api”, “_next”]
  • Case-insensitive validation prevents accidental conflicts
  • Comprehensive test coverage for edge cases

​
Migration & Adoption

For End Users:
  • No action required - All existing functionality continues to work
  • Challenge launching now works as expected
  • Communities created with previously-conflicting slugs will function correctly
For Admins:
  • Community Creation - Cannot create new communities with reserved slugs (“a”, “api”, “_next”)
  • Shopify Setup - If using Shopify integration, install the Nudj app from Shopify App Store and configure widget for your storefront
  • Slug Management - Existing communities with conflicting slugs are unaffected; only new communities are restricted
For Developers:
  • New useChallengeStart hook is the primary way to launch challenges
  • Shopify widget service handles token generation and configuration
  • Protected route validation happens at API mutation level
  • Updated i18n keys available for widget translations

​
Usage Examples

Embedding Shopify Widget: The Shopify widget integrates via Shopify’s theme extension system. After installing the Nudj app:
  1. Add the widget block to your storefront theme
  2. Configure the community ID context
  3. Widget automatically handles authentication via API Link
  4. Users see their loyalty status and can access challenges
Launching Challenges (User App): 
import { useChallengeStart } from '@/hooks/use-challenge-start';

const { startChallenge, isStarting } = useChallengeStart();

const handleStart = async () => {
  const result = await startChallenge(challenge);

  switch (result.status) {
    case 'success':
      // Challenge started, cache invalidated
      navigateToNextAction();
      break;
    case 'auth_required':
      // Login modal opened automatically
      break;
    case 'preview':
      // Admin preview mode
      showPreviewIndicator();
      break;
    case 'error':
      showErrorMessage(result.error);
  }
};
  • Shopify App Integration
  • API Link Authentication
  • Challenge Management System
  • Community Configuration
  • Internationalization (i18n)

​
Contributors

James Cockayne@jamescockayne2 commits • +1,995/-15,304 linesShopify widget integration, widget service architecture

ZuhayrK00@ZuhayrK002 commits • +179/-99 linesChallenge start hook restoration, route protection validation

nudj-changelog-bot@nudj-changelog-bot[bot]1 commit • Changelog automation

​
Release Stats

MetricValue
Total Commits5
Lines Added+2,359
Lines Removed-15,403
Files Changed73
Release Size🟠 Large
Complexity⭐⭐⭐ Complex
v2.111.0 deployed on January 8, 2026