383 lines
8.4 KiB
Markdown
383 lines
8.4 KiB
Markdown
# Persona Engine - Quick Reference Guide
|
||
|
||
## 🚀 Quick Start
|
||
|
||
The Persona Engine automatically classifies leads into tourist personas based on trip characteristics. No manual configuration needed!
|
||
|
||
---
|
||
|
||
## 📊 7 Persona Types
|
||
|
||
| Persona | Emoji | Spend | Key Indicators |
|
||
|---------|-------|-------|----------------|
|
||
| Romantic Couple | 💑 | Very High | 2 travelers + balloon/wine |
|
||
| Luxury Traveler | ✨ | Very High | Private tours + luxury interests |
|
||
| Budget Backpacker | 🎒 | Low | Budget interests + group tours |
|
||
| Content Creator | 📸 | High | Photography + drone + viewpoints |
|
||
| Family Explorer | 👨👩👧👦 | Medium | 3-6 travelers + family activities |
|
||
| Solo Adventurer | 🧗 | Medium | 1 traveler + adventure activities |
|
||
| Group Tour | 👥 | High | 8+ travelers + group activities |
|
||
|
||
---
|
||
|
||
## 🎯 For Providers
|
||
|
||
### Viewing Persona Information
|
||
|
||
**On Lead Cards:**
|
||
- Persona badge shows emoji + label
|
||
- Hover for tooltip with details
|
||
- Color-coded spend potential
|
||
- Confidence score percentage
|
||
|
||
**In Lead Detail Modal:**
|
||
- Full "Turist Profili" section
|
||
- Detected signals list
|
||
- Recommended services
|
||
- Detailed description
|
||
|
||
### Using Persona Insights
|
||
|
||
1. **Prioritize High-Value Leads**
|
||
- Focus on "Very High" spend potential (purple)
|
||
- Target "High" spend potential (green) next
|
||
|
||
2. **Tailor Your Pitch**
|
||
- Use recommended services as talking points
|
||
- Reference detected signals in communication
|
||
- Match your offerings to persona needs
|
||
|
||
3. **Quick Response**
|
||
- High confidence (>70%) = reliable classification
|
||
- AI-recommended leads = hot prospects
|
||
- Fast response increases conversion
|
||
|
||
### Example Approaches
|
||
|
||
**Romantic Couple (💑):**
|
||
```
|
||
"Merhaba! Kapadokya'da romantik bir kaçamak için harika bir plan hazırlamışsınız.
|
||
Özel balon turumuz ve gün batımı şarap tadımımız tam size göre olabilir..."
|
||
```
|
||
|
||
**Luxury Traveler (✨):**
|
||
```
|
||
"Hello! We noticed you're planning a premium Cappadocia experience.
|
||
Our VIP private guide service and exclusive fine dining options would be perfect..."
|
||
```
|
||
|
||
**Content Creator (📸):**
|
||
```
|
||
"Hi! We see you're interested in capturing Cappadocia's beauty.
|
||
Our sunrise balloon tour with drone permit and professional photo shoot package..."
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 For Developers
|
||
|
||
### Using PersonaBadge Component
|
||
|
||
```tsx
|
||
import { PersonaBadge } from '@/components/PersonaBadge';
|
||
|
||
// Compact mode (for cards)
|
||
<PersonaBadge
|
||
persona={lead.tourist_persona}
|
||
confidence={lead.persona_confidence}
|
||
language="tr"
|
||
compact
|
||
/>
|
||
|
||
// Inline mode (for lists)
|
||
<PersonaBadge
|
||
persona={lead.tourist_persona}
|
||
confidence={lead.persona_confidence}
|
||
language="en"
|
||
/>
|
||
|
||
// Detailed mode (for modals)
|
||
<PersonaBadge
|
||
persona={lead.tourist_persona}
|
||
confidence={lead.persona_confidence}
|
||
language="tr"
|
||
showDetails
|
||
/>
|
||
```
|
||
|
||
### Querying High-Value Leads
|
||
|
||
```typescript
|
||
// Using Supabase RPC
|
||
const { data, error } = await supabase.rpc('get_high_value_leads');
|
||
|
||
// Returns leads with:
|
||
// - spend_potential: 'high' or 'very_high'
|
||
// - persona_confidence >= 0.7
|
||
// - status: 'new'
|
||
// Sorted by spend potential and confidence
|
||
```
|
||
|
||
### Getting Persona Statistics
|
||
|
||
```typescript
|
||
// Using Supabase RPC
|
||
const { data, error } = await supabase.rpc('get_persona_statistics');
|
||
|
||
// Returns:
|
||
// - persona_type
|
||
// - count
|
||
// - avg_confidence
|
||
// - avg_travelers
|
||
```
|
||
|
||
### Manual Persona Detection
|
||
|
||
```typescript
|
||
import { detectPersona } from '@/utils/persona-detection';
|
||
|
||
const result = detectPersona({
|
||
number_of_travelers: 2,
|
||
interests: ['balloon', 'wine tasting'],
|
||
planned_activities: [...],
|
||
start_date: '2026-03-01',
|
||
end_date: '2026-03-05',
|
||
email: 'user@example.com',
|
||
country: 'USA'
|
||
});
|
||
|
||
// result.persona - Full persona object
|
||
// result.confidence - 0-1 confidence score
|
||
```
|
||
|
||
---
|
||
|
||
## 📈 For Admins
|
||
|
||
### Accessing Analytics
|
||
|
||
1. Navigate to **Admin Panel** → **Persona Analytics**
|
||
2. Or go directly to `/admin/persona-analytics`
|
||
|
||
### Understanding Charts
|
||
|
||
**Pie Chart - Persona Distribution:**
|
||
- Shows percentage of each persona type
|
||
- Larger slices = more common personas
|
||
- Click legend to filter
|
||
|
||
**Bar Chart - Spend Potential:**
|
||
- Compares total spend potential by persona
|
||
- Higher bars = more valuable segment
|
||
- Use for marketing prioritization
|
||
|
||
**Bar Chart - Confidence Scores:**
|
||
- Shows average detection confidence
|
||
- Higher = more reliable classifications
|
||
- Monitor for quality assurance
|
||
|
||
**Statistics Table:**
|
||
- Detailed breakdown per persona
|
||
- Lead count, confidence, travelers
|
||
- Export for reporting
|
||
|
||
### Key Metrics to Monitor
|
||
|
||
1. **High-Value Lead Percentage**
|
||
- Target: >30% high/very_high spend
|
||
- Action: Adjust marketing if too low
|
||
|
||
2. **Average Confidence Score**
|
||
- Target: >0.6 overall
|
||
- Action: Review detection logic if low
|
||
|
||
3. **Persona Distribution**
|
||
- Look for unexpected patterns
|
||
- Adjust offerings to match demand
|
||
|
||
4. **Conversion by Persona**
|
||
- Track which personas convert best
|
||
- Optimize pricing and services
|
||
|
||
---
|
||
|
||
## 🎨 Color Coding
|
||
|
||
### Spend Potential Colors
|
||
|
||
- 🟣 **Very High** - Purple - Premium leads
|
||
- 🟢 **High** - Green - Valuable leads
|
||
- 🔵 **Medium** - Blue - Standard leads
|
||
- ⚫ **Low** - Gray - Budget leads
|
||
|
||
### Badge Styles
|
||
|
||
- **Primary** - Persona label
|
||
- **Outline** - Spend potential
|
||
- **Secondary** - Confidence score
|
||
- **Gradient** - AI recommendations
|
||
|
||
---
|
||
|
||
## 🔍 Detection Signals
|
||
|
||
### What Triggers Each Persona?
|
||
|
||
**Romantic Couple:**
|
||
- 2 travelers
|
||
- Balloon tours (especially dawn)
|
||
- Wine tasting
|
||
- Sunset viewpoints
|
||
- "Romantic" in interests
|
||
|
||
**Luxury Traveler:**
|
||
- Private tours
|
||
- "Luxury" in interests
|
||
- High activity density
|
||
- Premium services
|
||
- Small group (2-4)
|
||
|
||
**Budget Backpacker:**
|
||
- "Budget" in interests
|
||
- Group tours
|
||
- Hiking activities
|
||
- Long trip, few paid activities
|
||
- Solo or large group
|
||
|
||
**Content Creator:**
|
||
- "Photography" in interests
|
||
- "Drone" in interests
|
||
- Many viewpoints (3+)
|
||
- Sunrise activities
|
||
- Instagram/social media
|
||
|
||
**Family Explorer:**
|
||
- 3-6 travelers
|
||
- Family-friendly activities
|
||
- Not budget-focused
|
||
- Moderate spend
|
||
|
||
**Solo Adventurer:**
|
||
- 1 traveler
|
||
- Adventure activities
|
||
- Hiking/trekking
|
||
- Local experiences
|
||
|
||
**Group Tour:**
|
||
- 8+ travelers
|
||
- Group activities
|
||
- Organized tours
|
||
- Bus transfers
|
||
|
||
---
|
||
|
||
## 💡 Best Practices
|
||
|
||
### For Providers
|
||
|
||
1. **Check Persona First**
|
||
- Review before contacting lead
|
||
- Tailor your message
|
||
- Reference relevant services
|
||
|
||
2. **Use Recommended Services**
|
||
- Start with suggested offerings
|
||
- Highlight matching features
|
||
- Build custom packages
|
||
|
||
3. **Monitor Confidence**
|
||
- High confidence (>70%) = reliable
|
||
- Medium confidence (40-70%) = likely
|
||
- Low confidence (<40%) = uncertain
|
||
|
||
4. **Track Conversion**
|
||
- Note which personas convert
|
||
- Adjust approach by persona
|
||
- Share insights with team
|
||
|
||
### For Admins
|
||
|
||
1. **Regular Monitoring**
|
||
- Check analytics weekly
|
||
- Look for trends
|
||
- Identify opportunities
|
||
|
||
2. **Quality Assurance**
|
||
- Review low-confidence leads
|
||
- Validate persona accuracy
|
||
- Adjust detection if needed
|
||
|
||
3. **Strategic Planning**
|
||
- Align marketing with personas
|
||
- Develop persona-specific campaigns
|
||
- Optimize provider offerings
|
||
|
||
4. **Data Export**
|
||
- Export statistics regularly
|
||
- Share with stakeholders
|
||
- Track performance over time
|
||
|
||
---
|
||
|
||
## 🐛 Troubleshooting
|
||
|
||
### Persona Not Detected
|
||
|
||
**Possible Causes:**
|
||
- No activities added to trip
|
||
- Generic interests only
|
||
- Insufficient trip data
|
||
|
||
**Solution:**
|
||
- Ensure trip has activities
|
||
- Add specific interests
|
||
- Complete trip details
|
||
|
||
### Low Confidence Score
|
||
|
||
**Possible Causes:**
|
||
- Mixed signals
|
||
- Ambiguous trip characteristics
|
||
- Multiple persona indicators
|
||
|
||
**Solution:**
|
||
- Review detected signals
|
||
- Check for conflicting data
|
||
- Consider as "general traveler"
|
||
|
||
### Wrong Persona Detected
|
||
|
||
**Possible Causes:**
|
||
- Unusual trip combination
|
||
- Edge case scenario
|
||
- Detection logic needs tuning
|
||
|
||
**Solution:**
|
||
- Review signals in detail
|
||
- Report to development team
|
||
- Use confidence score as guide
|
||
|
||
---
|
||
|
||
## 📞 Support
|
||
|
||
For technical issues or questions:
|
||
- Check PERSONA_ENGINE_SUMMARY.md for details
|
||
- Review TODO.md for implementation status
|
||
- Contact development team for assistance
|
||
|
||
---
|
||
|
||
## 🎉 Success Tips
|
||
|
||
1. **Trust the System** - High confidence scores are reliable
|
||
2. **Personalize Outreach** - Use persona insights in communication
|
||
3. **Track Results** - Monitor conversion by persona
|
||
4. **Iterate** - Adjust approach based on data
|
||
5. **Share Feedback** - Help improve the system
|
||
|
||
---
|
||
|
||
*Quick Reference Guide v1.0*
|
||
*Last Updated: 2026-02-25*
|