Haptic Feedback

The Despia Haptic Feedback SDK enables your application to incorporate tactile vibration feedback, making your app feel more responsive and enhancing user experience. This SDK provides various vibration patterns suited for different interactions and events.

Quick Start

1. Implement Basic Vibration

Add a simple vibration feedback to your application elements.

Copy// Basic vibration
window.despia = `heavy://haptic`

2. Choose Vibration Mode

Select the appropriate vibration pattern based on the interaction type.

Copy// Light tap
window.despia = `lighthaptic://`

// Heavy tap
window.despia = `heavyhaptic://`

// Success
window.despia = `successhaptic://`

// Warning
window.despia = `warninghaptic://`

// Error
window.despia = `errorhaptic://`

3. Implement in User Interactions

Add haptic feedback to specific user interactions in your app.

Copyfunction onButtonPress() {
    window.despia = `lighthaptic://`
}

How It Works

Vibration Patterns

The Haptic Feedback SDK uses the device's built-in vibration hardware to provide tactile feedback. Different patterns are available to match various interaction types:

• Light Tap: A subtle, quick vibration for minor interactions

• Heavy Tap: A stronger vibration for more significant interactions

• Success: A positive, affirming vibration pattern

• Warning: An attention-grabbing pattern to indicate caution

• Error: A distinctive pattern to signal errors or failures

Implementation Examples

Here's how you can implement haptic feedback in different user interactions:

Copy// Button Press Example
function onButtonPress() {
    window.despia = `lighthaptic://`
}

// Success Action Example
function onPaymentSuccess() {
    window.despia = `successhaptic://`
}

// Error Feedback Example
function onError() {
    window.despia = `errorhaptic://`
}

// EXAMPLES FOR NO-CODE/LOW-CODE TOOLS
            
// ---------- WEWEB ----------     
// WEWEB example - just directly use the haptic command in a code block
// No need to return or process any data - simply execute:
window.despia = `errorhaptic://`
// Or any other haptic pattern as needed:
window.despia = `lighthaptic://`
window.despia = `successhaptic://`

// ---------- WIZED ---------- 
// WIZED example - direct implementation without additional processing
// Simply call the command directly in your code block:
window.despia = `errorhaptic://`
            
// ---------- NORDCRAFT / TODDLE ---------- 
// For Nordcraft / Toddle - simply install the "Despia" Package and listen for the event callback.
// Clone the package from here: https://toddle.dev/projects/despia_package/branches/main
// Or run the method code in a custom action
window.despia = `successhaptic://`

Data Structure

The Haptic Feedback SDK uses a simple string-based command structure:

Copy// General format
window.despia = `[type]haptic://`

// Examples
"lighthaptic://"  // Light haptic feedback
"heavyhaptic://"  // Heavy haptic feedback
"successhaptic://" // Success haptic feedback
"warninghaptic://" // Warning haptic feedback
"errorhaptic://"  // Error haptic feedback

Best Practices

User Experience

• Use light mode for subtle feedback on common interactions

• Reserve heavy mode for important actions

• Apply success/warning/error patterns for appropriate status notifications

• Don't overuse vibrations as it can annoy users

• Test on different devices to ensure consistent experience

Implementation

• Implement haptic feedback as an enhancement, not a requirement

• Ensure your app works properly even if haptic feedback fails

• Consider providing a setting for users to disable haptic feedback

• Use consistent patterns throughout your application

Complete Implementation Example

Here's a complete implementation showing how to incorporate haptic feedback in a form submission:

Copy// Form submission with haptic feedback
document.getElementById('submitButton').addEventListener('click', function() {
    // Show loading state
    document.getElementById('loadingIndicator').style.display = 'block';
    
    // Provide feedback that button was pressed
    window.despia = `lighthaptic://`;
    
    // Submit form data
    submitFormData()
        .then(response => {
            // Hide loading state
            document.getElementById('loadingIndicator').style.display = 'none';
            
            if (response.success) {
                // Show success message
                showMessage('Form submitted successfully!');
                
                // Provide success haptic feedback
                window.despia = `successhaptic://`;
            } else {
                // Show error message
                showMessage('Error: ' + response.message);
                
                // Provide error haptic feedback
                window.despia = `errorhaptic://`;
            }
        })
        .catch(error => {
            // Hide loading state
            document.getElementById('loadingIndicator').style.display = 'none';
            
            // Show error message
            showMessage('An unexpected error occurred.');
            
            // Provide error haptic feedback
            window.despia = `errorhaptic://`;
        });
});

function showMessage(message) {
    const messageElement = document.getElementById('messageBox');
    messageElement.textContent = message;
    messageElement.style.display = 'block';
    
    // Hide message after 3 seconds
    setTimeout(() => {
        messageElement.style.display = 'none';
    }, 3000);
}

function submitFormData() {
    // Replace with your actual form submission logic
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            // Simulate successful submission
            resolve({ success: true });
            
            // Or simulate error
            // resolve({ success: false, message: 'Invalid data' });
            // reject(new Error('Network error'));
        }, 1500);
    });
}

Troubleshooting

Common Issues

Haptic Feedback Not Working

• Ensure the device supports haptic feedback

• Check if the user has disabled haptic feedback in device settings

• Verify correct syntax in your implementation

• Test with different vibration patterns

Inconsistent Feedback Across Devices

• Some devices have stronger or weaker haptic motors

• Older devices may have limited haptic capabilities

• Consider device-specific adjustments for optimal experience

Delayed Feedback

• Ensure your code is calling the haptic function at the right time

• Avoid calling haptic feedback during intensive operations

• Check for performance issues in your application