managarten/maerchenzauber/apps/landing/DEPLOYMENT.md

Landing Page Deployment Guide

Build Complete ✅

The landing page has been successfully built with universal links support!

What's Included

• ✅ Static character sharing page (character.html)
• ✅ Apple App Site Association file (iOS universal links)
• ✅ Digital Asset Links file (Android App Links)
• ✅ URL rewrite configurations for all major hosting providers

Deployment Options

Option 1: Netlify (Recommended for ease)

1. Deploy to Netlify:

   # Install Netlify CLI if you haven't
   npm install -g netlify-cli
   
   # Deploy
   cd landingpage
   netlify deploy --prod --dir=dist
   

2. Configure custom domain:

   • Go to Netlify dashboard → Domain settings
   • Add märchen-zauber.de as custom domain
   • Update DNS to point to Netlify

3. Verify universal links:

   curl https://märchen-zauber.de/.well-known/apple-app-site-association
   curl https://märchen-zauber.de/.well-known/assetlinks.json
   

The _redirects file will automatically handle URL rewrites!

Option 2: Vercel

1. Deploy to Vercel:

   # Install Vercel CLI if you haven't
   npm install -g vercel
   
   # Deploy
   cd landingpage
   vercel --prod
   

2. Configure custom domain:

   • Go to Vercel dashboard → Settings → Domains
   • Add märchen-zauber.de

The vercel.json file will automatically handle URL rewrites!

Option 3: Traditional Web Hosting (Apache/Nginx)

1. Upload the dist/ folder to your web server

2. Verify .htaccess is working (for Apache):

   • The .htaccess file should handle URL rewrites automatically
   • Test: https://märchen-zauber.de/character/test123/abc456
   • Should serve the character.html page

3. For Nginx, add this to your config:

   location ~ ^/character/([^/]+)/([^/]+)/?$ {
       rewrite ^/character/([^/]+)/([^/]+)/?$ /character.html last;
   }
   
   location /.well-known/apple-app-site-association {
       default_type application/json;
   }
   

Testing After Deployment

Test 1: Verify .well-known files are accessible

# iOS Universal Links
curl https://märchen-zauber.de/.well-known/apple-app-site-association

# Should return JSON with applinks configuration
# Content-Type should be application/json

# Android App Links
curl https://märchen-zauber.de/.well-known/assetlinks.json

# Should return JSON with Android package info

Test 2: Test character page

# Should serve the character.html page
curl https://märchen-zauber.de/character/test123/abc456

# Should return HTML content with the character sharing page

Test 3: Test on mobile devices

1. Create a test character in the app
2. Share it - should generate a link like: https://märchen-zauber.de/character/{id}/{shareCode}
3. Send link to yourself via WhatsApp/SMS
4. Click the link:
   • Should be clickable (not grayed out)
   • Should open the app if installed
   • Should show web preview if app not installed

Important URLs to Verify

After deployment, these URLs MUST work:

1. https://märchen-zauber.de/.well-known/apple-app-site-association

   • Must return JSON (no 404)
   • Must have Content-Type: application/json header

2. https://märchen-zauber.de/.well-known/assetlinks.json

   • Must return JSON (no 404)
   • Must have Content-Type: application/json header

3. https://märchen-zauber.de/character/abc/123

   • Must return the character sharing page (not 404)
   • Must work even with arbitrary IDs (JavaScript will fetch real data)

Troubleshooting

Universal links not working?

iOS:

• Clear Safari cache
• Reinstall the app
• Wait a few minutes after deployment (Apple caches the association file)
• Test with: https://branch.io/resources/aasa-validator/

Android:

• Check the SHA-256 fingerprint matches in assetlinks.json
• Clear app data: Settings → Apps → Märchenzauber → Storage → Clear Data
• May take 24-48 hours for Google to verify

Character page shows 404?

• Check URL rewrites are working
• Netlify: Verify _redirects file is deployed
• Vercel: Verify vercel.json is in project root
• Apache: Verify .htaccess is enabled (AllowOverride All)

.well-known files not found?

• Some hosts block .well-known by default
• Check your hosting provider's settings
• May need to explicitly allow serving these files

Next Steps

1. ✅ Build complete
2. 🚀 Deploy to hosting provider
3. ✅ Verify .well-known files are accessible
4. ✅ Test character sharing link
5. 📱 Rebuild mobile app with universal links enabled
6. 🧪 Test on real devices

Support

If you encounter issues:

1. Check the browser console for errors
2. Verify network requests in DevTools
3. Test the backend endpoint directly:

   curl https://storyteller-backend-111768794939.europe-west3.run.app/characters/public/{id}/{shareCode}