Candy Cane Conundrum

Web Game Integration Guide v1.0.0

Questions? We're Here to Help!

Contact Zach for any integration questions. He'll respond quickly with detailed answers.

Try the Game

See exactly what players will experience:

Reference: View All Trivia Questions & Answers

Quick Start

A two-phase web game for santasfunnight.com that drives engagement and offers rewards:

  1. Phase 1: Trivia - 5 questions about Santa's Wonderland Nights website
  2. Phase 2: Santa Says - Progressive memory game (Simon Says style)

Players who reach Round 10 can enter their email to receive a $5 discount code.

Download Production Files (ZIP)

Contains: candy-cane-web-v1.0.0.html + backend-example.php

Embedding the Game

Option 1: iframe (Recommended) Easy

Upload candy-cane-web-v1.0.0.html to your media library or theme folder, then embed:

<iframe
  src="/wp-content/uploads/candy-cane-web-v1.0.0.html"
  width="100%"
  height="700"
  frameborder="0"
  style="max-width: 540px; margin: 0 auto; display: block;">
</iframe>
Why this works best: Isolates the game's CSS/JS from your theme, preventing style conflicts.
Option 2: WordPress Shortcode Easy

Add to your theme's functions.php:

function candy_cane_game_shortcode() {
    return '<iframe
      src="' . get_template_directory_uri() . '/games/candy-cane-web-v1.0.0.html"
      width="100%"
      height="700"
      frameborder="0"
      style="max-width: 540px; margin: 0 auto; display: block;">
    </iframe>';
}
add_shortcode('candy_cane_game', 'candy_cane_game_shortcode');

Then use [candy_cane_game] in any post or page.

Option 3: Direct HTML Embed May Have Issues

Copy the contents of the HTML file into a Custom HTML block.

Warning: May have CSS conflicts with your theme. Test thoroughly.

Backend Setup (Required for Rewards)

The game needs a REST endpoint to validate gameplay and send discount codes.

What the Backend Does
Function Description
Validate gameplay Checks timing to prevent cheating (can't reach round 10 in <15 seconds)
Prevent duplicates One reward per email address
Generate codes Creates unique coupon codes (SANTA-XXXXXXXX format)
Send email Delivers discount code via wp_mail()
Implementation Steps ~1-2 hours
  1. Add the endpoint code to your theme's functions.php or create a custom plugin (see backend-example.php in the ZIP)
  2. Configure email - WordPress uses wp_mail(). Consider an SMTP plugin for reliable delivery.
  3. Integrate with tickets - The example generates codes but you need to make them work with your ticket/e-commerce system:
    • If WooCommerce: Create actual coupon codes
    • If external ticketing: Set up codes in that system
    • Manual approach: Store codes and verify at checkout
Endpoint URL: /wp-json/santasfunnight/v1/claim-reward
If using a different URL, update CONFIG.API_ENDPOINT in the game's JavaScript.
View PHP Code

Add to your theme's functions.php or create as a custom plugin. Three components:

Component Required? Description
Core Backend Required REST endpoint, validation, email sending
WooCommerce Integration Optional Auto-create WooCommerce coupons
Admin Dashboard Optional View all generated codes in WP admin
Core Backend Required
Review before using: Check the email message text (lines 45-54) to confirm dates and URLs match your event.
<?php
/**
 * Candy Cane Conundrum - Core Backend (Required)
 * Add this to functions.php or create as a plugin.
 */

// Register REST API endpoint
add_action('rest_api_init', function() {
    register_rest_route('santasfunnight/v1', '/claim-reward', [
        'methods' => 'POST',
        'callback' => 'sfn_handle_game_reward_claim',
        'permission_callback' => '__return_true'
    ]);
});

function sfn_handle_game_reward_claim($request) {
    $email = sanitize_email($request->get_param('email'));
    $play_token = $request->get_param('playToken');
    $rounds_completed = intval($request->get_param('roundsCompleted'));

    // Validate email
    if (!is_email($email)) {
        return new WP_Error('invalid_email', 'Please enter a valid email address.', ['status' => 400]);
    }

    // Check if already claimed
    $claimed_emails = get_option('sfn_claimed_emails', []);
    if (in_array(strtolower($email), array_map('strtolower', $claimed_emails))) {
        return new WP_Error('already_claimed', 'This email has already claimed a reward.', ['status' => 400]);
    }

    // Validate play token
    $token_data = json_decode(base64_decode($play_token), true);
    if (!$token_data || $token_data['rounds'] < 10 || $rounds_completed < 10) {
        return new WP_Error('invalid_game', 'Game validation failed.', ['status' => 400]);
    }

    // Anti-cheat: minimum 15 seconds for 10 rounds
    if ($token_data['duration'] < 15000) {
        return new WP_Error('timing_invalid', 'Game completed too quickly.', ['status' => 400]);
    }

    // Generate unique code
    $coupon_code = 'SANTA-' . strtoupper(substr(md5($email . time() . wp_rand()), 0, 8));

    // Store for tracking
    $generated_codes = get_option('sfn_generated_codes', []);
    $generated_codes[] = [
        'code' => $coupon_code,
        'email' => $email,
        'rounds' => $rounds_completed,
        'created' => current_time('mysql'),
        'redeemed' => false
    ];
    update_option('sfn_generated_codes', $generated_codes);

    // Record claim
    $claimed_emails[] = strtolower($email);
    update_option('sfn_claimed_emails', $claimed_emails);

    // =============================================
    // REVIEW THIS SECTION - Update for your event
    // =============================================
    $subject = "Your Santa's Wonderland Nights Discount Code!";

    $message = "Congratulations on completing Santa Says!\n\n";
    $message .= "You reached Round {$rounds_completed} - amazing memory skills!\n\n";
    $message .= "Your \$5 discount code is:\n\n";
    $message .= "    {$coupon_code}\n\n";
    $message .= "Use this code when purchasing tickets at:\n";
    $message .= "https://santasfunnight.com/tickets/\n\n";
    $message .= "See you at the Kringleworks!\n\n";
    $message .= "---\n";
    $message .= "Santa's Wonderland Nights\n";
    $message .= "Dayton, OH | Dec 12 - Jan 4\n";
    // =============================================

    $email_sent = wp_mail($email, $subject, $message, ['Content-Type: text/plain; charset=UTF-8']);

    if (!$email_sent) {
        error_log("SFN: Failed to send email to {$email} for code {$coupon_code}");
        return new WP_REST_Response([
            'success' => true,
            'message' => "Your discount code is: {$coupon_code} (Email failed - save this!)"
        ], 200);
    }

    return new WP_REST_Response([
        'success' => true,
        'message' => 'Check your email for your $5 discount code!'
    ], 200);
}
WooCommerce Integration Optional

If you use WooCommerce, add this function and call it from the core backend to auto-create real coupons.

To enable: Add sfn_create_woocommerce_coupon($coupon_code, 5.00); in the core backend right after the coupon code is generated.
/**
 * WooCommerce Coupon Creation (Optional)
 * Creates actual WooCommerce coupons that work at checkout.
 */
function sfn_create_woocommerce_coupon($code, $amount) {
    $coupon = new WC_Coupon();
    $coupon->set_code($code);
    $coupon->set_discount_type('fixed_cart');
    $coupon->set_amount($amount);
    $coupon->set_individual_use(true);
    $coupon->set_usage_limit(1);
    $coupon->set_usage_limit_per_user(1);
    $coupon->set_date_expires(strtotime('+30 days'));
    $coupon->save();
    return $coupon->get_id();
}
Admin Dashboard Optional

Adds a "Game Rewards" page to WordPress admin to view all generated codes, emails, and redemption status.

/**
 * Admin Dashboard for Game Rewards (Optional)
 * Adds a page in WP admin to view all generated codes.
 */
add_action('admin_menu', function() {
    add_menu_page(
        'Game Rewards',
        'Game Rewards',
        'manage_options',
        'sfn-game-rewards',
        'sfn_admin_rewards_page',
        'dashicons-tickets-alt',
        30
    );
});

function sfn_admin_rewards_page() {
    $codes = get_option('sfn_generated_codes', []);
    ?>
    <div class="wrap">
        <h1>Santa Says Game Rewards</h1>
        <table class="wp-list-table widefat fixed striped">
            <thead>
                <tr>
                    <th>Code</th>
                    <th>Email</th>
                    <th>Rounds</th>
                    <th>Created</th>
                    <th>Redeemed</th>
                </tr>
            </thead>
            <tbody>
                <?php foreach (array_reverse($codes) as $code): ?>
                <tr>
                    <td><code><?php echo esc_html($code['code']); ?></code></td>
                    <td><?php echo esc_html($code['email']); ?></td>
                    <td><?php echo esc_html($code['rounds']); ?></td>
                    <td><?php echo esc_html($code['created']); ?></td>
                    <td><?php echo $code['redeemed'] ? 'Yes' : 'No'; ?></td>
                </tr>
                <?php endforeach; ?>
            </tbody>
        </table>
        <p>Total codes generated: <?php echo count($codes); ?></p>
    </div>
    <?php
}

Optional: Leaderboard

What Would a Leaderboard Add? ~3-4 hours

A leaderboard would show top scores, encouraging competition and repeat plays.

Required changes:

  • New REST endpoints: GET /leaderboard and POST /submit-score
  • Database storage (wp_options or custom table)
  • Frontend: Name input, fetch/display top 10
  • Spam prevention (rate limiting, captcha)

Decision points:

  • Anonymous vs. name-required?
  • How to handle duplicate names?
  • Reset leaderboard daily/weekly/never?
Recommendation: Skip for launch. The email capture already provides engagement data. Leaderboard is "nice to have" that adds scope without significant value for the news segment.

Optional: Social Sharing

The Viral Potential ~8-16 hours

Social sharing could make this game go viral with people everywhere playing and telling others about it.

Current state: Players can download a certificate PNG and manually share it.

What "proper" social sharing would require:

Platform Requirements
Facebook Open Graph meta tags, Facebook App ID, share dialog integration
Twitter/X Twitter Cards meta tags, intent URL with pre-filled text
Instagram No direct sharing API - users download and post manually

The bigger picture:

We could create a mini arcade with simplified versions of various games - a "preview" of the event that builds anticipation. But there's a balance: we don't want to give away all our magic before people come.

Considerations:
  • Too much online could reduce in-person excitement
  • Games should tease, not replace the experience
  • Could save full social integration for post-event "share your experience"
Recommendation: Keep manual download/share for now. If this takes off organically, we can add proper sharing later. The certificate already includes the website URL.

Testing Checklist

Before Going Live
  • Open the game directly in browser - does it load?
  • Complete trivia (get 4/5 correct) - does it advance?
  • Play Santa Says - do sounds work on mobile?
  • Reach round 10 (use dev version for testing)
  • Email form shows appropriate error without backend
  • Certificate downloads as PNG
  • Works in WordPress iframe
  • No console errors
  • Test on mobile (touch targets, scrolling)

Files Included

File Purpose
candy-cane-web-v1.0.0.html Production game - embed this one
candy-cane-web-dev.html Development version with cheat modes for testing (not in ZIP)
backend-example.php WordPress REST API endpoint example
README.md Technical documentation
INTEGRATION-GUIDE.html This file

Questions?

Contact Zach - we can quickly clarify any integration questions and provide detailed guidance.