UGC Analytics Dashboard

A powerful analytics dashboard for User Generated Content (UGC) campaigns that aggregates and displays ad performance metrics from multiple platforms including Meta (Facebook/Instagram), Google Ads, and TikTok Ads.

Features

• 🔐 Authentication - Secure user authentication with Firebase (Email/Password & Google Sign-In)
• 📊 Multi-Platform Integration - Connect Meta, Google Ads, and TikTok Ads accounts
• 📈 Aggregated Metrics - View combined performance metrics across all platforms
• 🎯 Service-Specific Analytics - Detailed breakdown by individual advertising platform
• 📱 Responsive Design - Works seamlessly on desktop, tablet, and mobile devices
• 🔄 Real-time Data - Firebase integration for real-time data synchronization
• 📉 Interactive Charts - Visualize performance trends with Recharts

Tech Stack

• Frontend: React 19 + Vite
• Authentication: Firebase Auth
• Database: Firebase Firestore
• Charts: Recharts
• Icons: Lucide React
• Styling: Custom CSS with responsive design
• Deployment: GitHub Pages

Getting Started

Prerequisites

• Node.js 18+ and npm
• Firebase account
• API credentials for Meta, Google Ads, and/or TikTok Ads (optional for testing)

Installation

1. Clone the repository

   git clone https://github.com/panteleimon-a/ugc_analytics.git
   cd ugc_analytics

2. Install dependencies

   npm install

3. Set up Firebase

   • Go to Firebase Console
   • Create a new project
   • Enable Authentication (Email/Password and Google provider)
   • Enable Firestore Database
   • Copy your Firebase configuration

4. Configure environment variables

   cp .env.example .env

   Edit .env and add your Firebase credentials:

   VITE_FIREBASE_API_KEY=your_api_key
   VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
   VITE_FIREBASE_PROJECT_ID=your_project_id
   VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
   VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
   VITE_FIREBASE_APP_ID=your_app_id
   

5. Run the development server

   npm run dev

   The app will be available at http://localhost:5173

Usage

Authentication

1. Visit the application
2. Sign up with email/password or Google account
3. You'll be redirected to the dashboard

Connecting Ad Platforms

Option 1: Direct Meta OAuth (Recommended)

1. Navigate to the Connections tab
2. Click "Connect with Meta"
3. Log in with your Facebook/Meta account
4. Authorize access to your ad accounts
5. Select which ad account to connect
6. Metrics will automatically populate on your dashboard

Benefits:

• ✅ No need to install Shopify Meta channel app
• ✅ Direct connection to your Meta Ads account
• ✅ Works for merchants selling on any platform
• ✅ Automatic metrics fetching

Option 2: Shopify Integration

1. Navigate to the Connections tab
2. Enter your Shopify store domain (e.g., mystore.myshopify.com)
3. Click "Connect with Shopify"
4. The app automatically detects which ad platforms are installed
5. Connected services will show with checkmarks

Works when you have:

• Shopify store
• Shopify Meta channel app installed
• Shopify Google channel app installed
• Shopify TikTok channel app installed

Option 3: Manual API Credentials

1. Navigate to the Connections tab → Connect Individual Platforms
2. Enter API credentials for each service:
   • Meta (Facebook): Get access token from Facebook Developers
   • Google Ads: Get API key from Google Ads API Center
   • TikTok Ads: Get access token from TikTok Marketing API
3. Click Connect for each service

Viewing Analytics

• Overview Tab: See aggregated metrics across all connected platforms

  • Total spend, impressions, clicks, and CTR
  • Performance trends over time
  • Comparison charts by platform

• By Service Tab: Detailed metrics for each connected platform

  • Platform-specific performance data
  • Campaign-level breakdowns
  • Visual comparisons

API Integration

Current Implementation

The current version includes a UI framework with mock data for demonstration purposes. To integrate real API data:

1. Meta (Facebook) Ads API

   • Documentation: https://developers.facebook.com/docs/marketing-apis
   • Required: Access token with ads_read permission

2. Google Ads API

   • Documentation: https://developers.google.com/google-ads/api/docs/start
   • Required: Developer token, OAuth2 credentials

3. TikTok Ads API

   • Documentation: https://ads.tiktok.com/marketing_api/docs
   • Required: Access token with appropriate permissions

Extending the Application

To add real API integration, modify the following files:

• src/components/MetricsOverview.jsx - Replace mock data with API calls
• src/components/ServiceMetrics.jsx - Implement service-specific data fetching
• src/components/ServiceConnections.jsx - Add API credential validation

Deployment

GitHub Pages

1. Configure GitHub repository

   • Go to repository Settings → Pages
   • Enable GitHub Actions as the source

2. Add Firebase secrets

   • Go to Settings → Secrets and variables → Actions
   • Add the following secrets:
     • VITE_FIREBASE_API_KEY
     • VITE_FIREBASE_AUTH_DOMAIN
     • VITE_FIREBASE_PROJECT_ID
     • VITE_FIREBASE_STORAGE_BUCKET
     • VITE_FIREBASE_MESSAGING_SENDER_ID
     • VITE_FIREBASE_APP_ID

3. Deploy

   • Push to the main branch
   • GitHub Actions will automatically build and deploy
   • Your app will be available at https://panteleimon-a.github.io/ugc_analytics/

Manual Build

npm run build
npm run preview

Documentation

Complete documentation is organized in the /docs folder:

• Getting Started: Installation & Setup
• OAuth & Authentication: Meta OAuth Guide, Shopify Integration
• Deployment: Quick Deploy Guide, Full Checklist
• Security: Security Best Practices, Token Encryption
• Testing: Testing Guide

👉 View all documentation →

Project Structure

ugc_analytics/
├── .github/
│   └── workflows/
│       └── deploy.yml          # GitHub Actions deployment workflow
├── src/
│   ├── components/
│   │   ├── Auth.jsx            # Authentication component
│   │   ├── Dashboard.jsx       # Main dashboard layout
│   │   ├── MetricsOverview.jsx # Aggregated metrics view
│   │   ├── ServiceMetrics.jsx  # Per-service metrics
│   │   └── ServiceConnections.jsx # Platform connection management
│   ├── firebase.js             # Firebase configuration
│   ├── App.jsx                 # Main app component
│   ├── App.css                 # Main styles
│   ├── index.css               # Global styles
│   └── main.jsx                # App entry point
├── .env.example                # Environment variables template
├── package.json                # Dependencies and scripts
├── vite.config.js              # Vite configuration
└── README.md                   # This file

Development

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build
• npm run lint - Run ESLint

Code Style

The project uses ESLint for code quality. Run npm run lint before committing.

Contributing

1. Fork the repository
2. Create a 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

Security Notes

• Never commit API keys or credentials to the repository
• Use environment variables for sensitive data
• The .env file is gitignored by default
• Use GitHub Secrets for deployment credentials

License

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

Support

For issues, questions, or contributions, please open an issue on GitHub.

Roadmap

• Real API integration for Meta, Google, and TikTok
• Advanced filtering and date range selection
• Export reports to PDF/CSV
• Email notifications for performance alerts
• Custom dashboard widgets
• Multi-user account management
• Budget tracking and forecasting
• A/B testing comparison tools

Acknowledgments

• Built with Vite
• UI powered by React
• Charts by Recharts
• Icons from Lucide
• Backend by Firebase