ga_sync 0.1.0

Sync Google Analytics event definitions between Google Sheets and your codebase. Generate type-safe Dart code from spreadsheet-managed GA events.

ga_sync

Sync Google Analytics event definitions between Google Sheets and your codebase.

ga_sync is a CLI tool that generates type-safe Dart code from spreadsheet-managed GA event definitions, and syncs your route definitions back to the spreadsheet. Perfect for teams who manage analytics events in spreadsheets but want type-safe code.

Features

• 📊 Spreadsheet → Code: Generate Dart event classes from Google Sheets
• 🛣️ Code → Spreadsheet: Sync go_router routes to Google Sheets
• 🔄 Two-way sync: Keep spreadsheet and code always in sync
• ✅ Validation: Catch errors before they reach production
• 🤖 CI/CD Ready: Auto-generate PRs when spreadsheet changes

Quick Start

Installation

dart pub global activate ga_sync

Setup

1. Create a Google Cloud service account and download the JSON key
2. Share your spreadsheet with the service account email
3. Initialize config:

ga_sync init

4. Edit ga_sync.yaml:

version: 1

spreadsheet:
  id: "YOUR_SPREADSHEET_ID"  # From spreadsheet URL
  credentials: "credentials.json"

events:
  sheet_name: "Events"
  output: "lib/analytics/ga_events.g.dart"

routes:
  sheet_name: "Routes"
  source:
    - "lib/router/app_router.dart"
  parser: go_router

5. Generate code:

ga_sync generate events

Usage

Spreadsheet Format

Your "Events" sheet should have this structure:

event_name	parameters	param_types	description	category
screen_view	screen_name,screen_class	string,string	Screen viewed	navigation
button_click	button_id,screen_name	string,string	Button clicked	interaction
purchase	item_id,price,currency	string,double,string	Purchase completed	conversion

Generated Code

// lib/analytics/ga_events.g.dart
// GENERATED CODE - DO NOT MODIFY BY HAND

enum GaEventName {
  screenView,
  buttonClick,
  purchase,
}

class ScreenViewEvent {
  final String screenName;
  final String screenClass;

  const ScreenViewEvent({
    required this.screenName,
    required this.screenClass,
  });

  String get eventName => 'screen_view';

  Map<String, dynamic> toParameters() => {
    'screen_name': screenName,
    'screen_class': screenClass,
  };
}

// ... more event classes

Route Sync

Add @ga_description comments to your routes:

GoRoute(
  path: '/home',
  name: 'home',
  // @ga_description: Home screen
  builder: (context, state) => const HomeScreen(),
),

Then sync to spreadsheet:

ga_sync sync routes

Commands

Command	Description
ga_sync init	Create config file
ga_sync generate events	Generate Dart code from spreadsheet
ga_sync sync routes	Sync routes to spreadsheet
ga_sync sync all	Run both commands
ga_sync check	Check if code is up to date (for CI)

Options

• --dry-run, -d - Preview changes without writing
• --config, -c - Specify config file path
• --force, -f - Overwrite existing files (init only)

GitHub Actions Integration

Automatically create PRs when your spreadsheet is updated.

1. Add Secret

Go to Settings > Secrets and variables > Actions and add:

• Name: GOOGLE_CREDENTIALS
• Value: Your service account JSON key content

2. Add Workflow

Create .github/workflows/ga-sync.yaml:

name: GA Sync

on:
  workflow_dispatch:  # Manual trigger
  # schedule:
  #   - cron: '0 0 * * *'  # Or daily

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dart-lang/setup-dart@v1

      - run: dart pub global activate ga_sync

      - name: Setup credentials
        run: echo "${{ secrets.GOOGLE_CREDENTIALS }}" > credentials.json

      - run: ga_sync generate events
      - run: rm -f credentials.json

      - uses: peter-evans/create-pull-request@v7
        with:
          commit-message: 'chore: update GA event definitions'
          title: 'chore: update GA event definitions'
          branch: ga-sync/update-events

3. Enable Permissions

Go to Settings > Actions > General > Workflow permissions and select Read and write permissions.

Supported Types

Spreadsheet Type	Dart Type
string	String
int, integer	int
double, float, number	double
bool, boolean	bool
map	Map<String, dynamic>
list	List<dynamic>

Environment Variables

For CI/CD, you can use environment variables instead of config file:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
ga_sync generate events

Contributing

Contributions are welcome! Please read our Contributing Guide first.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• googleapis - Google APIs client
• code_builder - Dart code generation
• analyzer - Dart code analysis