Motor Finance Application Form Widget

Comprehensive Developer Guide

v3.0

Table of Contents

Overview

The Motor Finance Application Form Widget is a plug-and-play JavaScript solution that renders a multi-step finance application form with company-specific theming and configuration. It's designed to be embedded in any website and provides a seamless user experience for motor finance applications.

🚀 Easy Integration

Simple setup with minimal configuration required. Works with any modern web framework.

📊 Multi-step Form Wizard

Progressive form completion with progress tracking and step navigation.

✅ Real-time Validation

Instant field validation with error messaging and form state management.

📱 Responsive Design

Mobile-first design that works perfectly on all devices and screen sizes.

🎨 Theme Configuration

Company-specific branding with custom colours, fonts, and logos.

📱 Mobile Responsive

Optimised for all screen sizes with touch-friendly interface.

🔗 Event System

Comprehensive event system for integration with external applications.

Advanced Features

  • Dynamic Error Handling: Automatic error code extraction and conditional contact links
  • Success Management: Customisable success callbacks and panel display
  • Form Interaction Tracking: Comprehensive analytics and user behaviour monitoring
  • Session Management: Secure session handling and data persistence
  • Device Detection: Automatic device and browser information collection
  • Validation Analytics: Error counting and form completion time tracking
  • Postal Code Lookup: Enhanced address validation and autocomplete functionality for improved user experience and data accuracy

Installation

Prerequisites

  • jQuery 3.6.0 or higher
  • dropdownDatepicker plugin (for date fields)

1. Include Dependencies

<!-- jQuery (required) -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

<!-- dropdownDatepicker plugin (required for date fields) -->
<script src="https://apply.kyiper.com/assets/js/scripts/jquery-dropdown-datepicker.js"></script>

<!-- Kyiper Form Widget CSS (required) -->
<link rel="stylesheet" href="https://apply.kyiper.com/assets/css/styles/wrapper-motor-form-ui-v2.css" />

<!-- Kyiper Form Widget -->
<script src="https://apply.kyiper.com/assets/js/kyiper-form-widget-v3.js"></script>

2. Create a Container

<div id="kyiper-form-container"></div>

3. Initialise the Widget

const widget = new KyiperFormWidget.init({
    apiToken: 'your-api-token-here',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://your-api-domain.com'
});
Note: The widget requires jQuery for date field functionality and the dropdownDatepicker plugin for enhanced date selection.

Basic Setup

Minimal Configuration

const widget = new KyiperFormWidget.init({
    apiToken: 'your-api-token-here',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com'
});

Complete Example

<!DOCTYPE html>
<html>
<head>
    <title>Motor Finance Application</title>
    <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
    <script src="https://apply.kyiper.com/assets/js/scripts/jquery-dropdown-datepicker.js"></script>
    <link rel="stylesheet" href="https://apply.kyiper.com/assets/css/styles/wrapper-motor-form-ui-v2.css" />
    <script src="https://apply.kyiper.com/js/kyiper-form-widget-v3.js"></script>
</head>
<body>
    <div id="kyiper-form-container"></div>
    
    <script>
        const widget = new KyiperFormWidget.init({
            apiToken: 'your-api-token-here',
            containerId: 'kyiper-form-container',
            apiBaseUrl: 'https://api.example.com'
        });
    </script>
</body>
</html>

Configuration Options

Parameter Type Default Description
apiToken string Required API authentication token for accessing company-specific form schema and theme configuration. This token can be generated in the Dashboard Settings under API Configuration.
containerId string Required ID of the HTML container element
LOAD_TIMEOUT number 15000 API request timeout in milliseconds
RETRY_ATTEMPTS number 3 Number of retry attempts for failed requests
RETRY_DELAY number 1000 Delay between retry attempts in milliseconds
dealerId string '' Unique identifier for a customer or dealership. For motor channel partners, this represents unique dealer IDs. For individual dealerships, this represents unique end customer IDs.
dealerName string '' Name of the customer or dealership. Optional parameter.
utmSource string '' UTM source parameter for tracking the origin of the application (e.g., 'google', 'facebook', 'email'). Optional parameter.

Dealer Configuration

The widget supports optional dealer identification through dealerId, dealerName, and utmSource parameters. These are particularly useful for tracking applications from specific dealerships, customers, and marketing channels.

Dealer ID Usage

The dealerId serves as a unique identifier that can represent different entities depending on your business model:

🏢 Motor Channel Partners

Use dealerId to identify unique dealership IDs within your network. This helps track which specific dealership the application originated from.

👤 Individual Dealerships

Use dealerId to identify unique end customer IDs. This helps track individual customers making applications through your dealership.

📊 Marketing Channel Tracking

Use utmSource to track which marketing channel or campaign the application originated from (e.g., 'google', 'facebook', 'email').

Validation Rules

Note: dealerId, dealerName, and utmSource are all optional parameters. You can provide any combination of these parameters or none at all.

Usage Examples

Motor Channel Partner Example

const widget = new KyiperFormWidget.init({
    apiToken: 'your-api-token-here',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com',
    dealerId: 'DEALER_001',  // Unique dealership ID
    dealerName: 'ABC Motors Ltd',    // Dealership name
    utmSource: 'google'  // Marketing channel source
});

UTM Source Tracking Example

const widget = new KyiperFormWidget.init({
    apiToken: 'your-api-token-here',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com',
    utmSource: 'facebook'  // Track applications from Facebook ads
});

Without Dealer Data (Standard Usage)

const widget = new KyiperFormWidget.init({
    apiToken: 'your-api-token-here',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com'
    // dealerId, dealerName, and utmSource are all optional
});

Error Handling

dealerId, dealerName, and utmSource are all optional parameters:

// No validation errors - all parameters are optional
Note: dealerId, dealerName, and utmSource are all optional by default.

Theme Configuration

Theme configuration allows for company-specific branding and styling. You can configure themes in two ways:

  • Widget Parameters: Pass theme configuration directly in the widget initialization
  • Form Designer: You can Configuration in the Dashboard under form designer
Priority Order: Widget theme parameters take priority over API configuration, which takes priority over default values.

Theme Properties

Property Type Description Example
buttonColor string Primary button background colour '#004fa9'
buttonFontColor string Primary button text colour '#ffffff'
bodyFontFamily string Font family for form text 'Arial, sans-serif'
successPageTitle string Title displayed on success page 'Application Submitted Successfully!'
successPageMessage string Message displayed on success page 'Thank you for submitting...'
successContactInfoLabel string Contact information on success page 'Need assistance? Call us...'
errorPageTitle string Title displayed on error page 'Something Went Wrong'
errorPageMessage string Message displayed on error page 'We encountered an issue...'
errorContactInfoLabel string Contact information on error page 'Need assistance? Call us...'
contactUrl string Contact page URL for error messages 'https://example.com/contact'
showErrorCode boolean Whether to display error codes true
logo object Company logo configuration See Logo Configuration

Widget Theme Configuration

You can pass theme configuration directly in the widget initialization:

Basic Theme Example

const widget = new KyiperFormWidget.init({
    apiToken: 'your-api-token-here',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com',
    theme: {
        buttonColor: '#e74c3c',
        buttonFontColor: '#ffffff',
        bodyFontFamily: 'Helvetica, Arial, sans-serif'
    }
});

Complete Theme Example

const widget = new KyiperFormWidget.init({
    apiToken: 'your-api-token-here',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com',
    theme: {
        // Basic styling
        buttonColor: '#2c3e50',
        buttonFontColor: '#ffffff',
        bodyFontFamily: 'Roboto, sans-serif',
        
        // Success page customization
        successPageTitle: 'Congratulations!',
        successPageMessage: 'Your application has been received and is being processed.',
        successContactInfoLabel: 'Questions? Contact us at support@company.com',
        
        // Error page customization
        errorPageTitle: 'Application Error',
        errorPageMessage: 'We apologize for the inconvenience. Please try again.',
        errorContactInfoLabel: 'Need help? Call us at 1-800-SUPPORT',
        contactUrl: 'https://company.com/support',
        showErrorCode: false,
        
        // Logo configuration
        logo: {
            url: 'https://company.com/logo.png',
            alt: 'Company Logo',
            width: 250,
            height: 80
        }
    }
});

Logo Configuration

The logo configuration allows you to customize the company logo displayed in the form:

{
  "logo": {
    "url": "https://example.com/logo.png",    // Logo image URL
    "alt": "Company Logo",                    // Alt text for accessibility
    "width": 200,                            // Logo width in pixels
    "height": 60                             // Logo height in pixels
  }
}

Theme Configuration Priority

The widget uses the following priority order for theme configuration:

  1. Widget Parameters: Values passed in the theme object during initialization
  2. Form Designer: Values loaded from the form designer:
  3. Default Values: Built-in default theme values

Callback Functions

Success Callback

Called when the form is successfully submitted.

window.KyiperFormWidget.onSuccess = function(data) {
    console.log('Application submitted:', data);
    // Handle successful submission
    // data.applicationId - Generated application ID
    // data.submittedAt - Submission timestamp
    // data.status - Always 'submitted'
    // data.data - Full server response
};

Error Callback

Called when form submission fails.

window.KyiperFormWidget.onError = function(data) {
    console.log('Submission failed:', data);
    // Handle submission error
    // data.error - Error message
    // data.submittedAt - Error timestamp
    // data.status - Always 'error'
};
Note: If no callbacks are configured, the widget will display built-in success or error panels.

Error Handling

Error Panel Display

When no error callback is configured, the widget displays an error panel with:

  • Dynamic error code extraction
  • Conditional contact link (based on theme config)
  • Professional error messaging

Error Code Extraction

The widget automatically extracts error codes from:

  • error.status - HTTP status code
  • error.statusCode - Alternative status code
  • error.code - Generic error code
  • HTTP message parsing (e.g., "HTTP 404: Not Found")

Error Message Examples

HTTP Error 404. Resource not found. contact us
HTTP Error 500. Database connection failed. contact us
HTTP Error 422. Validation failed. contact us

Success Handling

Success Panel Display

When no success callback is configured, the widget displays a success panel with:

  • Success confirmation message
  • Checkmark icon
  • "Thank you for submitting your application" message

Success Panel Structure

<div class="form-panel">
    <div class="document-upload-success-part common-portal-panel">
        <div class="application-document justify-content-center flex-wrap flex-column">
            <div class="body-text">
                <span>Successfully Submitted!</span>
            </div>
            <div class="uploaded-image-box">
                <div class="body-text">
                    <!-- Success SVG icon -->
                    <p>Thank you for submitting your application.</p>
                </div>
            </div>
        </div>
    </div>
</div>

Examples

Basic Implementation

const widget = new KyiperFormWidget.init({
    apiToken: 'your-api-token-here',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com'
});

With Callbacks

// Success callback
window.KyiperFormWidget.onSuccess = function(data) {
    // Redirect to success page
    window.location.href = '/success';
};

// Error callback
window.KyiperFormWidget.onError = function(data) {
    // Show custom error message
    alert('Application failed: ' + data.error);
};

// Initialise widget
const widget = new KyiperFormWidget.init({
    apiToken: 'your-api-token-here',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com'
});

Advanced Configuration

const widget = new KyiperFormWidget.init({
    apiToken: 'your-api-token-here',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com',
    LOAD_TIMEOUT: 20000,
    RETRY_ATTEMPTS: 5,
    RETRY_DELAY: 2000,
    dealerId: 'DEALER_001',
    dealerName: 'ABC Motors Ltd',
    utmSource: 'google',
    theme: {
        buttonColor: '#2c3e50',
        buttonFontColor: '#ffffff',
        bodyFontFamily: 'Roboto, sans-serif',
        logo: {
            url: 'https://company.com/logo.png',
            alt: 'Company Logo',
            width: 250,
            height: 80
        }
    }
});

Theme-Only Configuration

const widget = new KyiperFormWidget.init({
    apiToken: 'your-api-token-here',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com',
    theme: {
        // Override only specific theme properties
        buttonColor: '#e74c3c',
        successPageTitle: 'Thank You!',
        errorPageTitle: 'Oops! Something went wrong'
    }
});

Troubleshooting

Common Issues

Widget Not Loading

Problem: Widget doesn't appear or shows errors
Solution: Check that all required files are loaded and the container element exists

API Connection Issues

Problem: "Failed to load form schema" errors
Solution: Verify API URL, endpoints, and CORS settings

Theme Not Applied

Problem: Default styling appears instead of company theme
Solution: Verify apiToken is correct and theme configuration API response

Form Validation Issues

Problem: Validation not working as expected
Solution: Check form schema validation rules and required field configuration

Debug Mode

Enable debug logging by setting:

window.KyiperFormWidget.debug = true;

Performance Tips

  • Use a CDN for widget files in production
  • Minify CSS and JavaScript files
  • Optimise API response times
  • Consider lazy loading for multiple widgets

Changelog

Version 3.0 Current

  • NEW: Priority-based theme merging (widget parameters > API config > defaults)
  • IMPROVED: Enhanced success and error page customization options
  • Fix: Resolved issues in the theme and logo configuration for widget-level parameters

Version 2.0

  • NEW: Implement lookup by postal code for enhanced address validation
  • CHANGED: Replace customerReference with dealerId for clearer dealer identification
  • CHANGED: Replace customerName with dealerName for consistent terminology
  • IMPROVED: Make dealerName parameter optional (remove validation requirement)
  • NEW: Add optional utmSource parameter for UTM tracking
  • IMPROVED: Enhanced dealer identification system for better tracking
  • IMPROVED: Better marketing channel attribution

Version 1.0

  • NEW: Multi-step form wizard with progress tracking
  • NEW: Theme configuration support
  • NEW: Success and error callbacks
  • NEW: Event-driven architecture
  • NEW: Mobile-responsive design
  • NEW: Dynamic error handling
  • NEW: Conditional field logic
  • NEW: Form validation system
  • NEW: Public API methods

Support & Resources

For additional support, documentation, or feature requests:

  • Documentation: This guide covers all features and configurations
  • Examples: Check the example files for implementation patterns
  • API Reference: Ensure your API matches the expected request/response format
  • Browser Support: Tested on Chrome, Firefox, Safari, and Edge