zentap/docs/GOOGLE_PLAY_GAMES.md

Google Play Games Integration for ZenTap

This document outlines the Google Play Games Services integration added to the ZenTap Flutter Flame game.

Features Implemented

🏆 Achievements

• First Bubble: Pop your first bubble
• 100 Bubbles: Pop 100 bubbles in total
• 1000 Bubbles: Pop 1,000 bubbles in total
• 5000 Bubbles: Pop 5,000 bubbles in total
• Zen Master: Play in Zen mode for 10 minutes
• Speed Demon: Reach 1,000 points in under 2 minutes
• Perfect Session: Complete a session without missing any bubbles (minimum 50 bubbles)

📊 Leaderboards

• High Score: Highest score in regular mode
• Zen Mode Duration: Longest time spent in Zen mode
• Total Bubbles Popped: Lifetime bubble count
• Longest Session: Longest single game session

🎮 Game Integration

• Automatic tracking of bubble pops, session time, and scores
• Real-time achievement checking
• Automatic submission of scores to leaderboards
• Session statistics tracking (perfect sessions, streaks, etc.)

Setup Required

1. Google Play Console Configuration

1. Create Google Play Games Project:

   • Go to Google Play Console
   • Create a new game or link to existing app
   • Note down the App ID

2. Configure Achievements:

   Achievement ID: achievement_first_bubble
   Name: First Bubble
   Description: Pop your first bubble
   Points: 5
   Type: Standard
      
   Achievement ID: achievement_100_bubbles
   Name: Bubble Rookie
   Description: Pop 100 bubbles
   Points: 10
   Type: Standard
      
   Achievement ID: achievement_1000_bubbles
   Name: Bubble Master
   Description: Pop 1,000 bubbles
   Points: 25
   Type: Standard
      
   Achievement ID: achievement_5000_bubbles
   Name: Bubble Legend
   Description: Pop 5,000 bubbles
   Points: 50
   Type: Standard
      
   Achievement ID: achievement_zen_master
   Name: Zen Master
   Description: Meditate for 10 minutes in Zen mode
   Points: 30
   Type: Standard
      
   Achievement ID: achievement_speed_demon
   Name: Speed Demon
   Description: Score 1,000 points in under 2 minutes
   Points: 25
   Type: Standard
      
   Achievement ID: achievement_perfect_session
   Name: Perfect Session
   Description: Complete a session without missing any bubbles
   Points: 20
   Type: Standard
   

3. Configure Leaderboards:

   Leaderboard ID: leaderboard_high_score
   Name: High Score
   Order: Larger is better
   Score Format: Numeric
      
   Leaderboard ID: leaderboard_zen_mode
   Name: Zen Mode Duration
   Order: Larger is better
   Score Format: Time (seconds)
      
   Leaderboard ID: leaderboard_total_bubbles
   Name: Total Bubbles Popped
   Order: Larger is better
   Score Format: Numeric
      
   Leaderboard ID: leaderboard_longest_session
   Name: Longest Session
   Order: Larger is better
   Score Format: Time (seconds)
   

2. Android App Configuration

1. Update App ID:

   • Replace YOUR_GOOGLE_PLAY_GAMES_APP_ID in android/app/src/main/res/values/strings.xml with your actual App ID from Google Play Console

2. App Signing:

   • Ensure your app is signed with the same certificate used in Google Play Console
   • Upload your SHA-1 fingerprint to Google Play Console

3. Testing

1. Internal Testing:

   • Add test accounts in Google Play Console
   • Use internal testing track to test Google Play Games integration

2. Debug Mode:

   • Use debug keystore for development testing
   • Add debug SHA-1 to Google Play Console for testing

Usage

For Players

1. Sign In: Go to Settings and tap "Sign In" under Google Play Games
2. View Achievements: Tap "Achievements" to see progress
3. View Leaderboards: Tap "Leaderboards" to compete with others
4. Automatic Tracking: All game progress is automatically tracked when signed in

For Developers

• All Google Play Games functionality is handled automatically
• Statistics are tracked during gameplay
• Results are submitted when game sessions end
• UI provides sign-in/sign-out and access to achievements/leaderboards

File Structure

lib/
├── utils/
│   └── google_play_games_manager.dart    # Main Google Play Games service
├── ui/
│   └── google_play_games_widget.dart     # UI component for settings
└── game/
    └── zentap_game.dart                  # Game integration (updated)

android/
├── app/
│   ├── build.gradle.kts                  # Added Google Play Services dependencies
│   └── src/main/
│       ├── AndroidManifest.xml          # Added Google Play Games permissions
│       └── res/values/
│           └── strings.xml               # App ID configuration

Dependencies Added

• games_services: ^4.0.0 - Flutter plugin for Google Play Games Services

Notes

• Google Play Games Services is only available on Android
• iOS Game Center integration would require additional setup
• All achievement and leaderboard IDs must match exactly between code and Google Play Console
• Test thoroughly before production release

Troubleshooting

Common Issues

1. App ID Mismatch: Ensure the App ID in strings.xml matches Google Play Console
2. SHA-1 Fingerprint: Make sure the app's SHA-1 is added to Google Play Console
3. Achievement IDs: Verify all achievement IDs match between code and console
4. Permissions: Ensure INTERNET and ACCESS_NETWORK_STATE permissions are added

Debug Tips

• Check Android logs for Google Play Games errors
• Use Google Play Console's testing tools
• Verify app is properly signed for production