Installation & Setup

Follow this guide to install and configure Quantum Competitions for WooCommerce on your WordPress site.

Installation Methods

Method 1: WordPress Admin Upload (Standard)

1. Log into your WordPress Dashboard (/wp-admin).
2. Navigate to Plugins > Add New > Upload Plugin.
3. Choose the plugin .zip package (quantum-competitions-for-woocommerce.zip) and click Install Now.
4. Once uploaded, click Activate Plugin.

Method 2: Manual FTP / SFTP Upload

1. Extract the quantum-competitions-for-woocommerce.zip file on your computer.
2. Connect to your web server using SFTP/FTP.
3. Upload the unzipped quantum-competitions-for-woocommerce folder into:

   /wp-content/plugins/

4. Go to Plugins > Installed Plugins in WordPress and click Activate.

---

License Activation & Automatic Updates

To receive automatic one-click updates and access support, navigate to: Competitions > Settings > License.

Quantum Competitions provides two flexible activation methods depending on whether you are the site owner or managing client websites:

---

Method 1: WPGenie Account Login (Standard)

Best for store owners managing their own websites who want automatic updates and direct access to the in-admin support ticket desk.

1. In the WPGenie Account Login tab, enter your Username and Password from wpgenie.org.
2. Click Authenticate.
3. Once authenticated, your account name and Remaining domain slots are displayed.
4. Click Register Domain (or Register Staging Domain if working on a local/staging environment).
5. The license status changes to Active, unlocking automated plugin updates and the Competitions > Support ticket desk.

---

Method 2: Site Key / Agency (Client & Agency Sites)

Ideal for agencies, freelancers, and multi-client deployments where you do not want to expose your master WPGenie login credentials on a client’s server.

1. Log into your WPGenie My Account and generate a Site Key (wpg_sk_...) bound to the client’s domain.
2. In the WordPress admin, switch to the Site Key / Agency tab.
3. Paste the Site Key into the Site Key field.
4. Select the environment (Production or Staging).
5. Click Activate Site Key.

Headless / wp-config.php Constant Activation

You can also automate activation via your site’s wp-config.php file, making it ideal for version-controlled codebases, Docker, or CI/CD pipelines:

// Define site key constant in wp-config.php
define( 'WPGENIE_SITE_KEY', 'wpg_sk_your_generated_site_key_here' );
// Alternatively:
define( 'QCW_SITE_KEY', 'wpg_sk_your_generated_site_key_here' );

• When defined in wp-config.php, the plugin automatically activates itself on admin load.
• The license cannot be deactivated from the UI while the constant is present.
• The in-admin support ticket desk is automatically disabled for client users, ensuring support queries route through your agency instead of your personal WPGenie account.

---

WooCommerce Configuration: Disable Guest Checkout

Quantum Competitions requires all ticket purchases to be linked to a registered customer account for ticket logging, verification, and prize claims.

1. Navigate to WooCommerce > Settings > Accounts & Privacy.
2. Under Guest checkout, uncheck:
   • ❌ Allow customers to place orders without an account
3. Under Account creation, ensure customer registration is permitted during checkout:
   • ✅ Allow customers to create an account during checkout
4. Click Save changes.

Guest Checkout Incompatible

If guest checkout is enabled, Quantum Competitions will display an admin error notice. The plugin cannot track ticket ownership or assign prizes to anonymous guest sessions.

---

Required Cron Jobs Configuration

For accurate countdown closings, instant winner determination, and automatic relisting, you must configure two external cron jobs on your server or hosting panel.

The plugin executes these routines via dedicated URL endpoints:

1. Main Competition Check Cron (Every 1 Minute)

This cron job executes the simple_lottery_cron() engine. It checks for finished competitions, finalizes ended draws, and triggers automatic winner selections.

• Trigger URL: https://yourdomain.com/?competition-cron=check
• Recommended Frequency: Every 1 minute (* * * * *)

# Option A: Using wget (Standard)
* * * * * wget -q -O - "https://yourdomain.com/?competition-cron=check" >/dev/null 2>&1

# Option B: Using curl
* * * * * curl -s "https://yourdomain.com/?competition-cron=check" >/dev/null 2>&1

Sub-Minute Precision

Internally, simple_lottery_cron() loops 3 times with 20-second sleep intervals per execution. This gives your store sub-minute precision, closing competitions within seconds of their scheduled end time without hammering the server.

2. Automated Relisting Cron (Every 1 Hour)

If you enable the Automatic Relist option on your competitions, this cron triggers qcw_pn_cron() to republish expired competitions with new dates.

• Trigger URL: https://yourdomain.com/?competition-relist=true
• Recommended Frequency: Every 1 hour (0 * * * *)

# Using wget
0 * * * * wget -q -O - "https://yourdomain.com/?competition-relist=true" >/dev/null 2>&1

# Using curl
0 * * * * curl -s "https://yourdomain.com/?competition-relist=true" >/dev/null 2>&1

Admin Notice Dismissal

Once your server executes each cron endpoint for the first time, the plugin detects the ping and automatically dismisses the dashboard setup notice.

---

Database Verification

Upon activation, the plugin automatically creates dedicated custom database tables via dbDelta:

• {$wpdb->prefix}wc_lottery_log: Participant log connecting users, orders, and competition IDs.
• {$wpdb->prefix}wc_lottery_pn_log: Ticket allocations and answered question IDs.
• {$wpdb->prefix}wc_lottery_pn_reserved: Session cart holds and anti-collision locks.
• {$wpdb->prefix}wc_lottery_pn_instantwin: Log of awarded instant win prizes and winners.
• {$wpdb->prefix}wc_lottery_pn_instant_prizes: Configuration table of instant win prizes mapped to tickets.

If you ever need to recreate or repair these tables, navigate to Competitions > Settings > Tools and click Repair Database Tables.