Quick Start
1
Clone the template
2
Create virtual environment
3
Install dependencies
4
Configure environment
5
Update scenario ID
Edit
www/config.js:www/config.js
6
Run the app
Whatβs Included
Flask Backend
Secure API proxy routes to protect your API key
Preact Frontend
Lightweight React alternative, no build tools needed
Iframe Integration
Ready-to-use ToughTongue embed with event handling
Session Analysis
Built-in analysis endpoint integration
Project Structure
Core Integration Patterns
1. Embedding the Iframe
The iframe is embedded inwww/assessment.js:
2. Listening for Events
Handle iframe events inwww/assessment.js:
3. Analyzing Sessions
After a session completes, analyze it via the backend API: Frontend (www/assessment.js):
api/index.py):
API Endpoints
The Flask backend provides these API proxy routes:POST /api/analyze
Analyzes a completed session:
GET /api/sessions/<session_id>
Retrieves session details:
Customization
Changing the Scenario
Update the scenario ID inwww/config.js:
Styling
Modifywww/styles.css to customize appearance. The starter includes:
- Responsive layout
- Card-based UI components
- Smooth transitions
- CSS variables for theming
Adding New API Endpoints
Add routes inapi/index.py:
Adding New Components
Create files inwww/components/:
Environment Variables
Deployment
Vercel (Recommended)
The project includesvercel.json for serverless deployment:
1
Install Vercel CLI
2
Deploy
3
Add environment variables
In Vercel dashboard, add
TTAI_TOKEN to your projectβs environment variables.4
Deploy to production
Other Platforms
For other platforms (Heroku, Railway, etc.):- Ensure Python 3.9+ is available
- Set environment variables
- Configure start command:
python app.py - Ensure port is configurable via
PORTenvironment variable
Troubleshooting
API Token Issues
API Token Issues
Check:
- Verify
TTAI_TOKENis set correctly in.env - Check token hasnβt expired
- Ensure token has necessary permissions
Iframe Not Loading
Iframe Not Loading
Check: - Verify scenario ID is correct in
www/config.js - Check scenario is set to
is_public: true in ToughTongue AI dashboard - Review browser console for errors - Ensure HTTPS
is used in production (required for microphone access)Static Files Not Serving
Static Files Not Serving
Check: - Check
WWW_DIR path in app.py is correct - Verify files exist in www/ directory- Check file permissions
CORS Errors
CORS Errors
Flask-CORS is already configured in
api/index.py.
If issues persist, check API base URL is correct.Dependencies
- Flask 2.0+: Web framework
- requests: HTTP library for API calls
- flask-cors: CORS support
- python-dotenv: Environment variable management
- gunicorn: Production WSGI server (optional)
Learn More
API Reference
ToughTongue AI API documentation
Iframe Events
Complete iframe integration guide
Troubleshooting
Common issues and solutions