placebo.mk/PLAY_STORE_GUIDE.md

# Google Play Store Publishing Guide

Complete step-by-step guide for publishing Placebo.mk PWA to Google Play Store using PWABuilder.

---

## Prerequisites Checklist

Before starting, ensure you have:

- [x] ✅ PWA deployed and accessible at `https://app.placebo.mk`
- [x] ✅ Privacy Policy accessible at `https://app.placebo.mk/privacy-policy`
- [x] ✅ PNG icons generated (72px - 512px)
- [x] ✅ Maskable icon (512x512)
- [x] ✅ Feature graphic (1024x500) at `pwa/public/assets/feature-graphic.png`
- [ ] ⏳ Screenshots captured (see `pwa/public/screenshots/README.md`)
- [x] ✅ Google Play Developer account ($25 one-time fee)

---

## Part 1: Capture Screenshots

**Time estimate:** 15-30 minutes

### Instructions:

1. Open Chrome browser
2. Navigate to `https://app.placebo.mk`
3. Press `F12` → Click device toolbar (or `Ctrl+Shift+M`)
4. Select device: **Pixel 5** (1080 x 2340)
5. Capture these screens:
   - Homepage (hero article + latest articles)
   - Article detail page
   - Archive page
   - Live blogs page
   - Category page (Sport/Art/Science)
   - Any other unique feature

6. Click three dots in device toolbar → "Capture screenshot"
7. Save as `screenshot-1.png`, `screenshot-2.png`, etc.
8. Place in `pwa/public/screenshots/`

**Requirements:**
- Minimum 2 screenshots
- Recommended 4-8 screenshots
- Format: PNG
- Portrait orientation (1080x2340)

---

## Part 2: Generate Android App with PWABuilder

**Time estimate:** 20-30 minutes

### Step 1: Access PWABuilder

1. Go to https://www.pwabuilder.com/
2. Enter your PWA URL: `https://app.placebo.mk`
3. Click "Start"

### Step 2: Review PWA Score

PWABuilder will analyze your PWA and show a score. You should see:
- ✅ Manifest detected
- ✅ Service Worker registered
- ✅ HTTPS enabled
- ✅ Icons present

If any checks fail, fix them before proceeding.

### Step 3: Package for Android

1. Click "Package For Stores"
2. Select **Android** platform
3. Click "Generate Package"

### Step 4: Configure Android Settings

Fill in the following:

| Field | Value |
|-------|-------|
| **App Name** | `Placebo.mk` |
| **Package ID** | `mk.placebo.app` |
| **Launch URL** | `https://app.placebo.mk/` |
| **Display Mode** | `standalone` |
| **Theme Color** | `#000000` |
| **Background Color** | `#ffffff` |
| **Orientation** | `portrait` |
| **Icon URL** | `https://app.placebo.mk/icons/icon-512.png` |
| **Maskable Icon URL** | `https://app.placebo.mk/icons/icon-512-maskable.png` |
| **Shortcuts** | Leave empty (optional) |
| **Splash Screen** | Auto-generated from icon |

### Step 5: Signing Options

Choose **one** of these options:

#### Option A: Use PWABuilder Cloud Signing (Recommended)

✅ **Pros:** Easy, no setup, signing key managed for you
❌ **Cons:** Key stored by PWABuilder (trusted service)

1. Select "Use new signing key"
2. PWABuilder will generate and store your key
3. Download the signing details (keep secure!)

#### Option B: Use Your Own Signing Key

✅ **Pros:** Full control over signing key
❌ **Cons:** More complex, must manage keystore securely

1. Generate keystore locally:
```bash
keytool -genkey -v -keystore placebo-release.keystore \
  -alias placebo-key -keyalg RSA -keysize 2048 -validity 10000
```

2. Upload keystore to PWABuilder
3. Enter keystore password and alias

### Step 6: Generate Package

1. Click "Generate Package"
2. Wait 2-5 minutes for build to complete
3. Download the generated package (AAB or APK)

### Step 7: Extract SHA256 Fingerprint

PWABuilder will show your SHA256 fingerprint. It looks like:
```
14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E3:6D:3A:AE:4E:9F:5F:E8:E3:91:A0:7E
```

**IMPORTANT:** Copy this fingerprint - you'll need it for Digital Asset Links.

---

## Part 3: Update Digital Asset Links

**Time estimate:** 5-10 minutes

### Step 1: Update assetlinks.json

1. Open `pwa/public/.well-known/assetlinks.json`
2. Replace `PLACEHOLDER_SHA256_FINGERPRINT_FROM_PWABUILDER` with your actual fingerprint
3. Save the file

Example:
```json
{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "mk.placebo.app",
    "sha256_cert_fingerprints": [
      "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E3:6D:3A:AE:4E:9F:5F:E8:E3:91:A0:7E"
    ]
  }
}
```

### Step 2: Deploy Updated PWA

Rebuild and deploy your PWA with the updated assetlinks.json:

```bash
cd pwa
npm run build
# Deploy to Coolify or your hosting platform
```

### Step 3: Verify Deployment

Check that the file is accessible:
```bash
curl https://app.placebo.mk/.well-known/assetlinks.json
```

Validate with Google:
```bash
curl "https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://app.placebo.mk"
```

You should see your statement without errors.

---

## Part 4: Test Locally (Optional but Recommended)

**Time estimate:** 15-20 minutes

### Step 1: Install APK

PWABuilder provides a test APK. Install it on your Android device:

```bash
adb install -r placebo-mk.apk
```

Or email the APK to yourself and install manually.

### Step 2: Test Functionality

Verify:
- ✅ App opens without browser UI (TWA verification)
- ✅ Icons display correctly
- ✅ Offline mode works
- ✅ Navigation works
- ✅ PostHog analytics fires
- ✅ Deep links work (if applicable)

### Step 3: Debug Issues

If TWA doesn't work (shows browser UI):
- Check assetlinks.json is accessible
- Verify SHA256 fingerprint matches
- Ensure package name is correct
- Wait 5-10 minutes for DNS/CDN propagation

---

## Part 5: Upload to Google Play Console

**Time estimate:** 30-60 minutes

### Step 1: Create App in Play Console

1. Go to https://play.google.com/console
2. Click "Create app"
3. Fill in details:
   - **App name:** Placebo.mk
   - **Default language:** Macedonian (mk-MK)
   - **App or game:** App
   - **Free or paid:** Free
4. Accept declarations
5. Click "Create app"

### Step 2: Complete Store Listing

Navigate to **Store presence → Main store listing**

Fill in:

**App Details:**
- **App name:** Placebo.mk
- **Short description:** (max 80 chars)
  ```
  Сатирични вести од Македонија - непристојно искрено и секогаш без филтер
  ```
- **Full description:** (max 4000 chars)
  ```
  Placebo.mk е платформа за сатирични вести и коментари за локални и глобални настани во Македонија.

  🎯 Што нудиме:
  • Свежи сатирични вести за тековни настани
  • Непристоен и директен коментар без филтер
  • Live блогови за разбивачки вести во реално време
  • Offline пристап до сите статии
  • Категории: Политика, Спорт, Уметност, Наука и повеќе

  ⚡ Карактеристики:
  • Брзо и лесно читање на статии
  • Работи offline - читајте и без интернет
  • Push известувања за нови статии
  • Делете статии на социјални медиуми
  • Темна и светла тема

  Затоа што понекогаш вистината боли повеќе од фикцијата.

  Следете не на web: https://placebo.mk
  ```

**Graphics:**
- Upload screenshots (2-8 images from `pwa/public/screenshots/`)
- Upload feature graphic (`pwa/public/assets/feature-graphic.png`)
- Upload app icon (512x512 from `pwa/public/icons/icon-512.png`)

**Categorization:**
- **App category:** News & Magazines
- **Tags:** news, satire, macedonia, politics (optional)

**Contact Details:**
- **Email:** privacy@placebo.mk (or your support email)
- **Website:** https://placebo.mk
- **Phone:** (optional)

**Privacy Policy:**
- **Privacy policy URL:** `https://app.placebo.mk/privacy-policy`

### Step 3: Set Up Content Rating

Navigate to **Policy → App content → Content rating**

1. Click "Start questionnaire"
2. Enter email address
3. Select category: **News & Reference**
4. Answer questions honestly:
   - Does app contain violence? → (Select based on your content)
   - Sexual content? → (Select based on your content)
   - Language? → (Select based on your content)
   - Drugs/alcohol references? → (Select based on your content)
5. Submit questionnaire
6. Apply ratings

### Step 4: Configure Target Audience

Navigate to **Policy → App content → Target audience and content**

1. **Target age:** 13+ (or 18+ if mature satire)
2. **App includes ads:** No (unless you add ads later)
3. Complete declaration

### Step 5: Select Countries

Navigate to **Release → Production → Countries/Regions**

1. Add countries:
   - ✅ North Macedonia (primary)
   - ✅ Other countries (optional - consider Albania, Serbia, Bulgaria, Greece for diaspora)
2. Click "Add countries/regions"

### Step 6: Upload AAB File

Navigate to **Release → Production → Create new release**

1. Click "Upload" and select the AAB file from PWABuilder
2. Wait for processing (may take 5-15 minutes)
3. Google Play will show:
   - ✅ APK size
   - ✅ Supported devices
   - ✅ Permissions required
4. Review and confirm

### Step 7: Add Release Notes

Add release notes for the first version:

**Macedonian:**
```
Прва верзија на Placebo.mk апликацијата!

• Читајте сатирични вести од Македонија
• Offline пристап до содржини
• Live блогови за разбивачки настани
• Брз и едноставен интерфејс
```

**English (optional):**
```
First version of Placebo.mk app!

• Read satirical news from Macedonia
• Offline access to content
• Live blogs for breaking news
• Fast and simple interface
```

### Step 8: Review and Publish

1. Click "Review release"
2. Google will check for issues:
   - ✅ All required fields complete
   - ✅ Content rating assigned
   - ✅ Target audience set
   - ✅ Privacy policy accessible
3. Fix any warnings
4. Click "Start rollout to Production"

---

## Part 6: Wait for Review

**Time estimate:** 1-7 days

### What Happens Next:

1. **Submitted:** Your app enters Google's review queue
2. **Under Review:** Google reviews your app (usually 1-3 days)
3. **Approved:** App goes live on Play Store 🎉
4. **Rejected:** Fix issues and resubmit

### Common Rejection Reasons:

- ❌ Privacy policy not accessible
- ❌ Content rating doesn't match app content
- ❌ Misleading app description
- ❌ Copyright/trademark issues
- ❌ Broken functionality

### Tracking Status:

- Check Play Console dashboard
- You'll receive email notifications for status changes
- View detailed feedback in "Policy status"

---

## Part 7: Post-Publication

### After Your App is Live:

1. **Share the News!**
   - Announce on your website
   - Share on social media
   - Email your users

2. **Monitor Performance:**
   - Track downloads in Play Console
   - Monitor crash reports
   - Review user feedback/ratings

3. **Set Up Store Listing Experiments (Optional):**
   - Test different screenshots
   - A/B test descriptions
   - Optimize icon designs

4. **Plan Updates:**
   - Regular feature updates
   - Bug fixes
   - New content

5. **Respond to Reviews:**
   - Reply to user reviews (especially negative ones)
   - Show you care about user feedback

---

## Troubleshooting

### PWA Score is Low
- Verify manifest.json is valid
- Check service worker is registered
- Ensure HTTPS is enabled
- Add required icons

### TWA Verification Fails
- Double-check SHA256 fingerprint
- Verify assetlinks.json is at correct URL
- Ensure package name matches exactly
- Wait for CDN cache to clear (5-10 mins)

### Upload Failed
- Check AAB file size (max 150MB)
- Verify signing key is valid
- Ensure version code is unique
- Try uploading again (sometimes glitches occur)

### App Rejected
- Read rejection reason carefully
- Fix issues listed
- Update AAB and resubmit
- Contact Google Play support if unclear

---

## Important Files Reference

| File | Location | Purpose |
|------|----------|---------|
| Icons (PNG) | `pwa/public/icons/icon-*.png` | App icons |
| Maskable Icon | `pwa/public/icons/icon-512-maskable.png` | Adaptive icon |
| Screenshots | `pwa/public/screenshots/` | Play Store listing |
| Feature Graphic | `pwa/public/assets/feature-graphic.png` | Store banner |
| Privacy Policy | `https://app.placebo.mk/privacy-policy` | Required legal doc |
| Asset Links | `pwa/public/.well-known/assetlinks.json` | TWA verification |
| Manifest | `https://app.placebo.mk/manifest.webmanifest` | PWA config |

---

## Support & Resources

- **PWABuilder Docs:** https://docs.pwabuilder.com/
- **Google Play Help:** https://support.google.com/googleplay/android-developer/
- **TWA Guide:** https://developers.google.com/web/android/trusted-web-activity
- **Digital Asset Links:** https://developers.google.com/digital-asset-links/

---

## Next Steps After This Guide

1. ✅ Complete all phases
2. ✅ Deploy updated PWA with assetlinks.json
3. ✅ Capture screenshots
4. ✅ Generate Android app with PWABuilder
5. ✅ Upload to Google Play Console
6. ⏳ Wait for approval
7. 🎉 Celebrate when live!

Good luck! 🚀