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:

• ✅ PWA deployed and accessible at https://app.placebo.mk
• ✅ Privacy Policy accessible at https://app.placebo.mk/privacy-policy
• ✅ PNG icons generated (72px - 512px)
• ✅ Maskable icon (512x512)
• ✅ Feature graphic (1024x500) at pwa/public/assets/feature-graphic.png
• ⏳ Screenshots captured (see pwa/public/screenshots/README.md)
• ✅ 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:

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:

{
  "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:

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

Step 3: Verify Deployment

Check that the file is accessible:

curl https://app.placebo.mk/.well-known/assetlinks.json

Validate with Google:

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:

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! 🚀