# Simply English Adaptive Assessment Plugin Setup Guide
## Overview
Step-by-step instructions for installing the adaptive English assessment plugin on your WordPress site hosted on Google Cloud.
---
## Prerequisites
- WordPress admin access
- Ability to upload files via Media Library or FTP
- Basic knowledge of WordPress plugin structure
---
## Installation Steps
### Step 1: Create Plugin Directory Structure
Create a new directory in your WordPress plugins folder:
```
wp-content/plugins/simply-english-assessment/
├── simply-english-assessment.php (main plugin file)
├── js/
│ └── assessment.js (frontend logic)
├── templates/
│ └── question-pool.json (question database)
└── templates/
└── assessment-page.php (page template)
```
### Step 2: Set Up Assessment Page Template
Save the following PHP template as `templates/assessment-page.php`:
```php
English Assessment
```
### Step 3: Create Question Pool JSON
Save this as `templates/question-pool.json`:
```json
[
{
"id": 1,
"level": "A1",
"question": "Select the correct article: ___ apple is red.",
"options": [
{"label": "A", "value": "a"},
{"label": "B", "value": "an"},
{"label": "C", "value": "the"}
],
"answer": "an"
},
{
"id": 2,
"level": "A1",
"question": "What is the plural of 'mouse'?",
"options": [
{"label": "A", "value": "mouses"},
{"label": "B", "value": "mice"},
{"label": "C", "value": "mouse"}
],
"answer": "mice"
}
]
```
### Step 4: Implement Branching Logic
The assessment should:
1. Present 5 questions per stage
2. Count correct answers after each batch
3. Request the next set via AJAX based on performance
4. Map total correct answers to CEFR levels
---
## Implementation Features
### Geolocation Filtering (Hong Kong/China Users)
Add this before rendering questions:
```javascript
// Use ipinfo.io API to detect location
fetch('https://ipinfo.io/json')
.then(response => response.json())
.then(data => {
const country = data.country;
if (country === 'HK' || country === 'CN') {
// Show local content or redirect
}
});
```
### Result Calculation
- Total correct answers mapped to CEFR levels:
- 0-5: A1 (Beginner)
- 6-10: A2 (Elementary)
- 11-15: B1 (Intermediate)
- 16-20: B2 (Upper Intermediate)
- 21-25: C1 (Advanced)
- 26-30: C2 (Proficiency)
### Data Collection
Include GDPR-compliant email form after assessment completion:
- Explicit consent checkbox
- Optional contact information field
- Session data stored in WP transients
---
## Best Practices
1. **Script Enqueuing**: Always use `wp_enqueue_script` for CSS/JS files
2. **Security**: Sanitize all POST data with `sanitize_text_field` and verify nonces
3. **AJAX**: Use WordPress REST API or `wp_ajax` endpoints for question loading
4. **Performance**: Cache question lists to reduce database load
5. **Privacy**: Respect GDPR - ask for explicit consent before collecting user data
---
## Common Pitfalls
- **CSRF Issues**: Always add nonces to AJAX requests
- **Race Conditions**: Load next question batch only after prior batch completes
- **Email Privacy**: Implement double opt-in and clear privacy policy
- **Geolocation API Limits**: Cache results per IP and have fallback logic
---
## Files to Upload to WordPress
1. `simply-english-assessment.php` - Main plugin file
2. `js/assessment.js` - Frontend JavaScript logic
3. `templates/question-pool.json` - Question database
4. `templates/assessment-page.php` - Page template
Upload via:
- WordPress Admin → Plugins → Add New → Upload Plugin
- Or via FTP/SFTP to `wp-content/plugins/` directory
---
## Post-Installation
1. Activate plugin in WordPress Admin
2. Create a new page using "Adaptive Assessment" template
3. Test geolocation filtering with Hong Kong/China IPs
4. Verify question branching works correctly
5. Check email collection form appears after completion
---
*Generated: ${new Date().toLocaleDateString()}*
*Source: wordpress-assessment-builder skill*