Spin Wheel

⌘K
  2. Home
  4. Spin Wheel
  6. Hooks & Filters (Deve...
  8. Before saving to database (uspw_before_save_entry)

Before saving to database (uspw_before_save_entry)

uspw_before_save_entry

The uspw_before_save_entry filter runs inside Ultimate Spin Wheel just before a spin entry is written to the database. It lets you inspect, normalize, or enrich the entry data (name, email, phone) and add metadata to the stored user_data JSON before the row is inserted into wp_wdengage_entries.

Type: Filter  |  Since: 1.0.0  |  Signature: apply_filters( 'uspw_before_save_entry', $data, $campaign_id )

Important: This Hook Is Pro-Only

In the free plugin this filter is wrapped in a Pro gate. In the code it fires only when apply_filters( 'ultimate_spin_wheel_pro_init', false ) returns true, which happens only when the separate Ultimate Spin Wheel Pro plugin is installed and active. On the free plugin alone the filter never runs, so any callback you attach to it will not execute. Treat everything on this page as (Pro).

Parameters

  • $data (array): The entry data about to be saved. It contains the keys campaign_id, campaign_title, name, email, phone, campaign_type, and user_data (a JSON string with IP address, device ID, and user agent).
  • $campaign_id (int): The ID of the spin wheel campaign that produced this entry.

Because it is a filter, your callback must return the modified $data array. Do not rely on modifying it by reference — the plugin uses the returned value.

What Actually Gets Saved (Read This First)

Only specific fields from $data are written to the wp_wdengage_entries table. Understanding this prevents a common mistake — adding fields that are silently thrown away:

  • Persisted columns: campaign_id, campaign_title, name, email, phone, user_data, others_data, campaign_type, optin, and created_at. Changes you make to name, email, phone, and user_data are saved.
  • Custom top-level keys are dropped: Adding arbitrary keys such as $data['utm_source'], $data['lead_score'], or $data['country'] has no effect — only the mapped columns above are inserted. To keep extra data, encode it into the user_data JSON string instead.
  • others_data cannot be set here: The plugin rebuilds $data['others_data'] immediately after this filter runs (from the coupon title, coupon code, status, and phone), so anything you write to others_data inside the hook is overwritten. Use user_data for your own metadata.

Basic Usage

Register a filter with two accepted arguments and return the array:

add_filter( 'uspw_before_save_entry', 'my_enrichment', 10, 2 );
function my_enrichment( $data, $campaign_id ) { /* modify $data */ return $data; }

Example 1: Store UTM Parameters for Attribution

Capture UTM values from the request and fold them into the user_data JSON (not top-level keys, which would be discarded):

  1. Read and sanitize the UTM values from $_GET (for example utm_source, utm_medium, utm_campaign).
  2. Decode the existing $data['user_data'] JSON with json_decode( $data['user_data'], true ).
  3. Add a utm_tracking array (and any referrer/landing-page values) to that decoded array.
  4. Re-encode it: $data['user_data'] = wp_json_encode( $user_data ); and return $data;.

Example 2: Normalize Phone Numbers

The phone field is a saved column, so normalizing it here works and persists. Strip non-digits with preg_replace( '/[^0-9]/', '', $data['phone'] ), apply your preferred format, assign it back to $data['phone'], and return $data. Note that the phone input field itself is a Pro feature — this callback only matters when a phone value is present.

Example 3: Attach a Lead-Quality Score

Compute a score from the email domain, whether a phone was supplied, and any UTM metadata you stored, then keep it inside user_data so it survives to the database:

  • Inspect $data['email'] to weight business vs. free-mail domains.
  • Add points if $data['phone'] is not empty.
  • Decode user_data, set $user_data['lead_score'] and a grade, re-encode into $data['user_data'], and return $data.

Example 4: Real-Time Email Verification

Call an external verification API (for example ZeroBounce or Hunter.io) with $data['email'], then store the returned status inside the user_data JSON. Because this runs on the critical spin path, keep external calls fast and wrap them in is_wp_error() checks so a slow or failed API never blocks the save.

Notes & Best Practices

  • Always return the $data array — this is a filter, not an action.
  • Persist custom metadata inside the user_data JSON string; top-level keys and others_data will not survive.
  • The filter fires after the default fields are merged but before the $wpdb->insert() call.
  • Be cautious with external API calls (geolocation, email verification) — they run during the spin and can slow the response. Consider caching or deferring non-critical enrichment.
  • This filter only runs when Ultimate Spin Wheel Pro is active.

Related Documentation

Conclusion

The uspw_before_save_entry filter (Pro) is the right place to normalize and enrich a lead before it is stored. Remember three things: return the $data array, keep custom metadata inside the user_data JSON since other keys are dropped or overwritten, and keep any external calls lightweight. For help, visit the wowDevs support center.

How can we help?