# TestFlight Beta Testing Guide for BaoLife

Complete guide for running a successful beta test using Apple's TestFlight platform.

---

## Table of Contents

1. [Overview](#overview)
2. [TestFlight Setup](#testflight-setup)
3. [Internal Testing](#internal-testing)
4. [External Testing](#external-testing)
5. [Distributing to Testers](#distributing-to-testers)
6. [Managing Feedback](#managing-feedback)
7. [Beta Success Criteria](#beta-success-criteria)
8. [Common Issues](#common-issues)

---

## Overview

### What is TestFlight?

TestFlight is Apple's official beta testing platform that allows you to:
- Distribute pre-release builds to testers
- Collect feedback and crash reports
- Test IAPs in production environment
- Validate app before public release
- Gather analytics and metrics

### Why Beta Test BaoLife?

**Benefits:**
- Identify bugs before public launch
- Test server load and performance
- Validate AI conversation quality
- Gather user feedback on gameplay
- Test IAP purchase flow
- Build early user base and reviews
- Generate pre-launch buzz

### Beta Testing Timeline

**Recommended Schedule:**

```
Week 1-2: Internal Testing (team + close contacts)
Week 3-4: External Testing (closed beta, invited testers)
Week 5-6: Open Beta (public link, wider audience)
Week 7: Final polish based on feedback
Week 8: App Store submission
```

---

## TestFlight Setup

### Prerequisites

Before starting TestFlight:
- [ ] Apple Developer Program membership
- [ ] App uploaded to App Store Connect
- [ ] Build processed and available
- [ ] Test Information completed
- [ ] Export Compliance answered

### Step 1: Upload Your First Build

Follow the "Build Upload" section in `app-store-connect-guide.md`:

1. Archive app in Xcode
2. Validate archive
3. Distribute to App Store Connect
4. Wait for processing (10-60 minutes)
5. Build appears in "TestFlight" tab

### Step 2: Complete Test Information

In App Store Connect > TestFlight > Test Information:

**Beta App Name:** BaoLife
- Can differ from App Store name
- 30 character limit

**Beta App Description:**
```
BaoLife is an immersive life simulation game where you create a character and experience the full journey of human life.

BETA TESTING FOCUS:
We're looking for feedback on:
- Overall gameplay experience
- AI conversation quality and appropriateness
- Performance and stability
- UI/UX clarity and intuitiveness
- In-app purchase flow
- Tutorial effectiveness

KNOWN ISSUES:
- [List any known bugs]
- [Features in development]

Thank you for testing BaoLife!
```

**Feedback Email:** support@baolife.app
- Where testers can send feedback
- Must be monitored regularly

**Privacy Policy URL:** https://baolife.app/privacy

**Beta App Review Information:**

**Sign-in required:** Yes

**Test Account:**
- Username: betatester@baolife.app
- Password: BetaTest2025!

**Notes to Reviewer:**
```
BaoLife is a single-player life simulation game.

Test account includes:
- Pre-configured character at age 20
- Sufficient diamonds for IAP testing
- Multiple relationships established
- Access to all features

Testing guide:
1. Log in with provided credentials
2. Tap through tutorial (first launch)
3. Test conversations (tap character portraits)
4. Test activities (Activities tab)
5. Test IAPs (tap diamonds in header)

All AI content is filtered for appropriate content.
Response time for questions: <2 hours.
```

### Step 3: Submit for Beta App Review

**Important:** First TestFlight build requires App Review approval (24-48 hours)

1. Complete all Test Information fields
2. Click "Submit for Review"
3. Wait for approval email
4. Subsequent builds auto-approve unless major changes

---

## Internal Testing

### What is Internal Testing?

- Tests with team members (up to 100)
- No Beta App Review required
- Immediate distribution after upload
- 90-day expiration per build
- Ideal for quick iteration

### Step 1: Add Internal Testers

1. Go to App Store Connect > TestFlight > Internal Testing
2. Click "+" to add new internal group
3. Name: "Core Team"
4. Add testers by email (must be in App Store Connect team)
5. Select builds to test

### Internal Tester Roles

**Developer Account Required:** Yes
- All internal testers must be added to your App Store Connect team
- Roles: Admin, Developer, App Manager, Marketing, Sales

### Step 2: Enable Testing

1. Select build for internal testing
2. Testers receive email invitation
3. Install TestFlight app from App Store
4. Accept invitation
5. Install BaoLife beta

### Internal Testing Checklist

**Week 1-2 Focus Areas:**

**Functionality:**
- [ ] Character creation flows smoothly
- [ ] AI conversations working
- [ ] Activities can be selected and completed
- [ ] Relationships develop properly
- [ ] Time progression works
- [ ] Energy system balanced

**Technical:**
- [ ] No crashes on launch
- [ ] Smooth performance (60 FPS)
- [ ] Memory usage acceptable (<200 MB)
- [ ] Network requests succeed
- [ ] Data persists correctly
- [ ] Push notifications deliver

**IAP:**
- [ ] Store displays correctly
- [ ] Purchase flow completes
- [ ] Diamonds credited to account
- [ ] Restore purchases works
- [ ] Receipt validation successful

**UI/UX:**
- [ ] All text readable
- [ ] No UI overlaps or clipping
- [ ] Navigation intuitive
- [ ] Loading states clear
- [ ] Error messages helpful

### Internal Testing Goals

**Success Criteria:**
- Zero critical crashes
- <5 minor bugs
- All core features functional
- Positive feedback from team
- Ready for external testing

---

## External Testing

### What is External Testing?

- Tests with external users (up to 10,000)
- First build requires Beta App Review
- Public link or email invitations
- 90-day expiration per build
- Best for wider audience testing

### Step 1: Create External Test Group

1. Go to TestFlight > External Testing
2. Click "+" to add new group
3. Name: "BaoLife Beta Testers"
4. Add testers via:
   - Email invitations
   - Public link

### Step 2: Add External Testers via Email

**Individual Invitations:**

1. Click "Add Testers" in group
2. Enter email addresses (up to 10,000)
3. Testers receive email invitation
4. No Apple ID required until installation
5. Track acceptance status

**CSV Import:**
```csv
Email,First Name,Last Name
john@example.com,John,Doe
jane@example.com,Jane,Smith
```

1. Prepare CSV file
2. Click "Import Testers"
3. Upload file
4. Review and confirm

### Step 3: Create Public Link

**Public Link Benefits:**
- Share on social media
- Post in communities
- Include in blog posts
- No email required upfront

**Create Link:**
1. Enable "Public Link" in test group
2. Copy link (e.g., `https://testflight.apple.com/join/ABC123`)
3. Share link anywhere
4. Users install TestFlight + join automatically

**Public Link Best Practices:**
- Post on Twitter, Reddit, Discord
- Include in newsletter
- Add to website/landing page
- Monitor signup rate
- Close when limit reached

### External Testing Recruitment

**Where to Find Beta Testers:**

**Reddit Communities:**
- r/iosgaming
- r/gaming
- r/TestFlight
- r/BetaTest

**Discord Servers:**
- Gaming communities
- iOS development groups
- Life simulation fans

**Twitter/X:**
- Tweet with #TestFlight #LifeSimulator
- Tag gaming influencers
- Use beta testing hashtags

**Email List:**
- If you have existing contacts
- Personal network
- Friends and family

**Beta Testing Platforms:**
- BetaList.com
- BetaTesting.com
- UserTesting.com

### External Testing Communication

**Welcome Email Template:**

```
Subject: Welcome to BaoLife Beta! 🎮

Hi [Name],

Thank you for joining the BaoLife beta! You're among the first to experience our immersive life simulation game.

GETTING STARTED:
1. Install TestFlight from the App Store
2. Open your invitation email or link
3. Install BaoLife beta
4. Launch and create your character

WHAT WE'RE TESTING:
- Overall gameplay experience
- AI conversation quality
- Performance and stability
- Tutorial effectiveness
- In-app purchase flow

HOW TO SEND FEEDBACK:
- In TestFlight app: Shake device > Report Issue
- Email us: support@baolife.app
- Include: Device model, iOS version, description

KNOWN ISSUES:
- [List current issues]

REWARDS:
Beta testers who provide valuable feedback will receive:
- 1000 free diamonds at launch
- Early access to new features
- Credits in app
- Our eternal gratitude!

Thank you for helping make BaoLife amazing!

The BaoLife Team
support@baolife.app
```

### External Testing Checklist

**Week 3-6 Focus Areas:**

**User Experience:**
- [ ] New users understand onboarding
- [ ] Tutorial is clear and helpful
- [ ] Core mechanics are intuitive
- [ ] Progression feels rewarding
- [ ] No confusion about features

**Content Quality:**
- [ ] AI conversations feel natural
- [ ] No inappropriate AI responses
- [ ] Character personalities distinct
- [ ] Events are engaging
- [ ] Activities are fun and varied

**Performance at Scale:**
- [ ] Server handles concurrent users
- [ ] No slowdowns during peak times
- [ ] Database queries optimized
- [ ] WebSocket connections stable
- [ ] No rate limiting issues

**Monetization:**
- [ ] IAP value proposition clear
- [ ] Price points feel fair
- [ ] Free gameplay satisfying
- [ ] Premium features compelling
- [ ] No pay-to-win concerns

### External Testing Goals

**Success Criteria:**
- 100+ testers actively playing
- <1% crash rate
- 4.0+ average rating (internal metric)
- Positive qualitative feedback
- All critical bugs fixed
- IAP conversion >1%
- Retention: 30%+ Day 1, 10%+ Day 7

---

## Distributing to Testers

### TestFlight App

Testers must install TestFlight from App Store:
1. Download TestFlight (free)
2. Open invitation email or link
3. Tap "Start Testing" or "Install"
4. BaoLife appears in TestFlight
5. Tap to install beta

### Tester Invitation Email

Apple sends automatic email:
```
You're invited to test BaoLife - Life Simulator

[Your test account] invited you to test an app using TestFlight.

To get started:
1. Install TestFlight
2. Open this invitation
3. Install BaoLife

[Install Button]

Invitation expires in 90 days.
```

### Managing Test Builds

**Uploading New Builds:**

1. Archive new version in Xcode
2. Upload to App Store Connect
3. Wait for processing
4. Build appears in TestFlight automatically
5. Testers receive update notification

**Build Numbers:**
- Increment for each upload
- Version 1.0.0: Build 1, 2, 3...
- Version 1.1.0: Build 4, 5, 6...

**Update Frequency:**
- Critical fixes: Immediately
- Regular updates: Every 3-7 days
- Avoid daily updates (tester fatigue)

### Update Notifications

**What's New in This Build:**

Update this for each build:
```
Version 1.0.0 (Build 5) - Jan 15, 2025

NEW:
- Added 10 new career options
- Improved AI conversation quality
- Enhanced relationship system

FIXED:
- Fixed crash when opening Activities tab
- Fixed diamond purchase not crediting
- Fixed character portraits not loading

KNOWN ISSUES:
- Time speed slider occasionally resets
- Some Android users report lag (iOS only affected)

Thank you for testing! Keep the feedback coming!
```

Testers see this in TestFlight before updating.

---

## Managing Feedback

### Collecting Feedback

**TestFlight Feedback:**
- Testers shake device > Send Beta Feedback
- Includes device info, iOS version, logs
- Accessed in App Store Connect > TestFlight > Feedback

**Email Feedback:**
- support@baolife.app
- Direct tester communication
- More detailed reports

**Surveys:**
- Google Forms
- Typeform
- SurveyMonkey

**In-App Feedback (Optional):**
- Add feedback button in app
- Direct submission to your backend
- Category selection (bug/feature/other)

### Crash Reports

**Viewing Crashes:**
1. App Store Connect > TestFlight > Crashes
2. View crash rate by build
3. Download crash logs
4. Symbolicate in Xcode

**Analyzing Crashes:**
- Xcode > Window > Organizer > Crashes
- Import crash reports
- View stack traces
- Identify crash causes

**Crash Rate Goals:**
- Target: <0.1% crash rate
- Acceptable: <1% crash rate
- Concerning: >1% crash rate
- Critical: >5% crash rate

### Beta Metrics

**Key Metrics to Track:**

**Installation & Adoption:**
- Invitations sent
- Invitations accepted
- Installs completed
- Active testers (DAU)

**Engagement:**
- Session length
- Sessions per user
- Feature usage rates
- Retention (D1, D7, D30)

**Feedback Quality:**
- Number of feedback submissions
- Bug reports submitted
- Feature requests
- Positive vs critical feedback

**Technical:**
- Crash rate
- Average memory usage
- Average CPU usage
- Network request success rate

### Organizing Feedback

**Use a System:**

**Spreadsheet Tracking:**
```
| Date | Tester | Category | Priority | Description | Status | Build |
|------|--------|----------|----------|-------------|--------|-------|
| 1/15 | John   | Bug      | High     | Crash on... | Fixed  | 5     |
| 1/15 | Jane   | Feature  | Medium   | Add dark... | Future | 5     |
```

**Issue Tracker:**
- GitHub Issues
- Jira
- Trello
- Notion

**Categories:**
- Bug - Critical
- Bug - Major
- Bug - Minor
- Feature Request
- UI/UX Feedback
- Performance
- Content (AI, events)

**Priorities:**
- P0: Blocker (fix immediately)
- P1: Critical (fix before launch)
- P2: Important (fix soon)
- P3: Nice to have (future)

### Responding to Testers

**Acknowledge Quickly:**

```
Hi [Name],

Thank you for reporting this issue! We've logged it and our team is investigating.

Issue: [Brief description]
Priority: [P0-P3]
Expected fix: [Timeline]

We'll update you when it's resolved.

Thanks for helping improve BaoLife!
```

**When Fixed:**

```
Hi [Name],

Good news! The issue you reported has been fixed in Build [X].

Issue: [Description]
Fix: [What we did]

Please update to the latest build and let us know if you encounter any other issues.

Thank you for your valuable feedback!
```

---

## Beta Success Criteria

### Pre-Launch Goals

Before submitting to App Store, ensure:

**Technical Quality:**
- [ ] Crash rate <0.1%
- [ ] No critical bugs
- [ ] <5 minor bugs (non-blocking)
- [ ] Load time <3 seconds
- [ ] Smooth 60 FPS performance
- [ ] Memory usage <200 MB

**User Experience:**
- [ ] 4.0+ satisfaction rating
- [ ] Onboarding completion >80%
- [ ] Tutorial completion >70%
- [ ] Positive qualitative feedback
- [ ] No major UX complaints

**Content Quality:**
- [ ] AI conversations appropriate
- [ ] No offensive content reported
- [ ] Events engaging and varied
- [ ] Activities balanced
- [ ] Progression satisfying

**Monetization:**
- [ ] IAP flow tested thoroughly
- [ ] No purchase failures
- [ ] Restore purchases working
- [ ] Value proposition clear
- [ ] At least 1 beta purchase completed

**Engagement:**
- [ ] D1 retention >30%
- [ ] D7 retention >10%
- [ ] Average session >10 minutes
- [ ] >70% return for 2nd session

**Server & Infrastructure:**
- [ ] Backend stable under load
- [ ] WebSocket connections reliable
- [ ] Database queries optimized
- [ ] No server errors
- [ ] Backup systems tested

### Beta Testing Report

**Create Summary Report:**

```markdown
# BaoLife Beta Testing Report

## Overview
- Testing Period: Jan 1 - Feb 15, 2025
- Testers: 250 (50 internal, 200 external)
- Builds: 15 builds uploaded
- Feedback: 180 submissions

## Key Metrics
- Installs: 250
- Active Users (DAU): 120 average
- Crash Rate: 0.05%
- D1 Retention: 35%
- D7 Retention: 12%
- Average Session: 15 minutes

## Top Feedback Themes
1. AI conversations praised (95% positive)
2. Request for more career options (mentioned 45 times)
3. Energy system too restrictive (30 mentions) ✓ Adjusted
4. Tutorial helpful (92% found clear)
5. IAP pricing fair (85% agreed)

## Bugs Fixed
- Critical: 2
- Major: 8
- Minor: 23
- Total: 33

## Outstanding Issues
- Minor: 3 (non-blocking)
- Feature Requests: 12 (for post-launch)

## Recommendations
✓ Ready for App Store submission
- All critical bugs fixed
- Strong positive feedback
- Metrics meet success criteria
- Technical performance excellent

## Next Steps
1. Submit to App Store (target: Feb 20)
2. Plan post-launch update (March)
3. Implement top feature requests
```

---

## Common Issues

### Tester Can't Install

**Problem:** Tester says they can't install beta

**Solutions:**
1. Verify email invitation sent
2. Check tester accepted invitation
3. Confirm TestFlight installed
4. Verify device iOS version compatible
5. Check tester slots not full (10,000 max)
6. Ensure build not expired (90 days)

### Build Not Appearing

**Problem:** New build not showing for testers

**Solutions:**
1. Wait for processing (10-60 min)
2. Check "External Testing" groups have build enabled
3. Verify build didn't fail Beta App Review
4. Check for email about review rejection
5. Ensure build not expired

### Crash Reports Not Appearing

**Problem:** No crash data in App Store Connect

**Solutions:**
1. Enable crash reporting in Xcode
2. Wait 24 hours for aggregation
3. Check crashes in Xcode Organizer instead
4. Verify symbols uploaded with build
5. Ask testers to share crash logs manually

### Feedback Not Received

**Problem:** Testers submitting feedback but you don't receive it

**Solutions:**
1. Check spam folder for feedback emails
2. Verify correct email in Test Information
3. Check TestFlight > Feedback section
4. Ask testers to email directly
5. Set up in-app feedback as backup

### IAP Not Working in TestFlight

**Problem:** In-app purchases failing in beta

**Solutions:**
1. Verify IAPs created in App Store Connect
2. Check IAPs status is "Ready to Submit"
3. Clear "Cleared for Sale" checkbox
4. Use Sandbox Tester account
5. Verify SKU matches code
6. Check receipt validation

### TestFlight Expiration

**Problem:** Build expired after 90 days

**Solution:**
1. Upload new build with same version number
2. Increment build number only
3. Testers auto-update
4. No interruption in testing

---

## Beta Tester Rewards

### Incentivizing Testers

**Rewards for Beta Testers:**

1. **Free Diamonds:** 1000 diamonds at launch
2. **Early Access:** First to try new features
3. **Beta Badge:** In-app badge showing beta participation
4. **Credits:** Name in app credits
5. **Exclusive Item:** Beta-only cosmetic item
6. **Thank You Message:** Personal note in app

**Tracking Beta Testers:**

Store list of beta tester User IDs:
```swift
let betaTesters = [
    "user123",
    "user456",
    // ...
]

func isBetaTester(userId: String) -> Bool {
    return betaTesters.contains(userId)
}

// Grant rewards
if isBetaTester(userId: currentUser.id) {
    currentUser.diamonds += 1000
    currentUser.badges.append("beta_tester")
    showThankYouMessage()
}
```

---

## TestFlight Best Practices

### Do's

✅ **Test early and often**
✅ **Respond to feedback quickly**
✅ **Fix critical bugs immediately**
✅ **Update "What's New" for each build**
✅ **Thank testers regularly**
✅ **Share progress updates**
✅ **Be transparent about known issues**
✅ **Act on feedback (show you're listening)**
✅ **Monitor crash rates daily**
✅ **Test IAPs thoroughly**

### Don'ts

❌ **Don't upload daily builds** (tester fatigue)
❌ **Don't ignore feedback** (testers will stop reporting)
❌ **Don't submit with critical bugs** (bad first impression)
❌ **Don't skip internal testing** (catch easy bugs first)
❌ **Don't test without analytics** (need data to improve)
❌ **Don't launch with untested features**
❌ **Don't spam testers** (communicate purposefully)
❌ **Don't forget to thank testers**

---

## Transitioning to Launch

### Final Beta Build

**Pre-Launch Checklist:**

1. **Final Build Upload:**
   - Clean, well-tested code
   - All critical bugs fixed
   - Performance optimized
   - No test code or logging

2. **Communication:**
   - Thank beta testers
   - Announce launch date
   - Share how to leave reviews
   - Remind about beta rewards

3. **Wrap-Up:**
   - End external testing groups
   - Compile beta report
   - Document learnings
   - Plan post-launch updates

### Launch Day Email to Beta Testers

```
Subject: BaoLife is Live on the App Store! 🎉

Hi [Name],

Amazing news! BaoLife is now live on the App Store, and you helped make it happen!

YOUR BETA REWARDS:
- 1000 diamonds (already credited to your account)
- Beta Tester badge (check your profile!)
- Exclusive beta item (in your inventory)

PLEASE LEAVE A REVIEW:
Your review would mean the world to us:
[App Store Link]

Share your honest experience and help others discover BaoLife!

THANK YOU:
Your feedback was invaluable. Over 6 weeks of testing, you helped us:
- Fix 33 bugs
- Improve AI conversations
- Balance game mechanics
- Polish the experience

BaoLife is better because of you!

WHAT'S NEXT:
- Monthly content updates
- New careers and activities
- Continued improvements based on feedback

Stay tuned and thank you for being part of the journey!

The BaoLife Team
support@baolife.app

P.S. Keep that feedback coming! We're always listening.
```

---

## Resources

### TestFlight Documentation
- Apple TestFlight Guide: https://developer.apple.com/testflight/
- TestFlight FAQ: https://help.apple.com/app-store-connect/#/devfa7e5a471

### Tools
- TestFlight App: https://apps.apple.com/app/testflight/id899247664
- App Store Connect: https://appstoreconnect.apple.com

### Support
- BaoLife Support: support@baolife.app
- Apple Developer Support: https://developer.apple.com/support/

---

**Good luck with your beta test!** 🚀