Before any validation (uspw_before_spin_validation)

uspw_before_spin_validation

Description

Fires before spin validation begins, allowing developers to implement custom validation logic or block spins based on custom criteria.

Hook Type: Filter
Since: 1.0.0

Parameters

Parameter	Type	Description
$can_spin	bool	Whether the user can spin (default: true)
$campaign_id	int	The ID of the spin wheel campaign
$user_data	array	User submitted data (email, name, phone, etc.)

Usage

add_filter( 'uspw_before_spin_validation', 'my_custom_validation', 10, 3 );
function my_custom_validation( $can_spin, $campaign_id, $user_data ) {
    // Your custom logic here
    return $can_spin;
}

Real-World Examples

Example 1: Block Spins from Specific Email Domains

Prevent users with disposable or competitor email domains from spinning the wheel.

add_action( 'uspw_before_spin_validation', 'block_disposable_emails', 10, 3 );
function block_disposable_emails( $campaign_id, $user_data, &$block_spin ) {
    $blocked_domains = [
        'tempmail.com',
        'guerrillamail.com',
        '10minutemail.com',
        'competitor.com'
    ];
    
    if ( ! empty( $user_data['email'] ) ) {
        $email_domain = substr( strrchr( $user_data['email'], '@' ), 1 );
        
        if ( in_array( $email_domain, $blocked_domains, true ) ) {
            $block_spin = true;
            wp_send_json_error( [
                'message' => 'Email domain not allowed. Please use a valid email address.'
            ] );
        }
    }
}

Example 2: Limit Spins Based on IP Address

Restrict the number of spins per IP address within a specific timeframe.

add_action( 'uspw_before_spin_validation', 'limit_spins_by_ip', 10, 3 );
function limit_spins_by_ip( $campaign_id, $user_data, &$block_spin ) {
    global $wpdb;
    
    $user_ip = $_SERVER['REMOTE_ADDR'] ?? '';
    $table_name = $wpdb->prefix . 'wdengage_entries';
    
    // Count spins from this IP in the last 24 hours
    $count = $wpdb->get_var( $wpdb->prepare(
        "SELECT COUNT(*) FROM {$table_name} 
        WHERE campaign_id = %d 
        AND ip_address = %s 
        AND created_at > DATE_SUB(NOW(), INTERVAL 24 HOUR)",
        $campaign_id,
        $user_ip
    ) );
    
    if ( $count >= 3 ) {
        $block_spin = true;
        wp_send_json_error( [
            'message' => 'You have reached the maximum number of spins for today. Please try again tomorrow.'
        ] );
    }
}

Example 3: Require User Authentication for Premium Campaigns

Force users to be logged in before they can spin specific premium campaigns.

add_action( 'uspw_before_spin_validation', 'require_login_for_premium', 10, 3 );
function require_login_for_premium( $campaign_id, $user_data, &$block_spin ) {
    // Define premium campaign IDs
    $premium_campaigns = [ 123, 456, 789 ];
    
    if ( in_array( $campaign_id, $premium_campaigns, true ) && ! is_user_logged_in() ) {
        $block_spin = true;
        wp_send_json_error( [
            'message' => 'Please log in to participate in this exclusive spin wheel.',
            'login_required' => true,
            'login_url' => wp_login_url( get_permalink() )
        ] );
    }
}

Example 4: Validate Custom Fields

Ensure custom required fields are filled out before allowing a spin.

add_action( 'uspw_before_spin_validation', 'validate_custom_fields', 10, 3 );
function validate_custom_fields( $campaign_id, $user_data, &$block_spin ) {
    // Check if company name is required for B2B campaigns
    $b2b_campaigns = [ 101, 102, 103 ];
    
    if ( in_array( $campaign_id, $b2b_campaigns, true ) ) {
        if ( empty( $user_data['company'] ) ) {
            $block_spin = true;
            wp_send_json_error( [
                'message' => 'Company name is required for business campaigns.'
            ] );
        }
        
        // Validate phone number format
        if ( ! empty( $user_data['phone'] ) ) {
            $phone = preg_replace( '/[^0-9]/', '', $user_data['phone'] );
            if ( strlen( $phone ) < 10 ) {
                $block_spin = true;
                wp_send_json_error( [
                    'message' => 'Please enter a valid 10-digit phone number.'
                ] );
            }
        }
    }
}

Example 5: Implement Time-Based Restrictions

Allow spins only during specific business hours or promotional periods.

add_action( 'uspw_before_spin_validation', 'time_based_restrictions', 10, 3 );
function time_based_restrictions( $campaign_id, $user_data, &$block_spin ) {
    // Flash sale campaign - only available 9 AM to 5 PM EST
    if ( $campaign_id === 999 ) {
        $timezone = new DateTimeZone( 'America/New_York' );
        $current_time = new DateTime( 'now', $timezone );
        $hour = (int) $current_time->format( 'H' );
        
        if ( $hour < 9 || $hour >= 17 ) {
            $block_spin = true;
            wp_send_json_error( [
                'message' => 'This spin wheel is only available between 9 AM and 5 PM EST.',
                'next_available' => '9:00 AM EST'
            ] );
        }
    }
    
    // Weekend-only campaign
    if ( $campaign_id === 888 ) {
        $day_of_week = (int) current_time( 'w' ); // 0 = Sunday, 6 = Saturday
        
        if ( $day_of_week !== 0 && $day_of_week !== 6 ) {
            $block_spin = true;
            wp_send_json_error( [
                'message' => 'This special offer is only available on weekends!'
            ] );
        }
    }
}

Notes

• The $block_spin parameter is passed by reference, so setting it to true will prevent the spin from proceeding.
• Always use wp_send_json_error() when blocking a spin to provide user feedback.
• This hook fires very early in the process, before any prize selection or database operations.
• Perfect for implementing custom rate limiting, authentication checks, or business logic validation.