Lab Analytics Backend

A TypeScript backend server that collects analytics data and stores it in Google BigQuery.

Schema

The BigQuery table has the following schema:

| Column | Type | Nullable | | --------------- | --------- | -------- | | event_timestamp | TIMESTAMP | NULLABLE | | event_name | STRING | NULLABLE | | session_id | STRING | NULLABLE | | user_id | STRING | NULLABLE | | client_name | STRING | NULLABLE | | page_url | STRING | NULLABLE | | referer_url | STRING | NULLABLE | | event_data | JSON | NULLABLE | | event_item | STRING | NULLABLE | | user_agent | STRING | NULLABLE |

Setup

1. Clone this repository
2. Install dependencies:

   npm install

3. Create a .env file based on .env.example:

   cp .env.example .env

4. Update the environment variables in .env with your Google Cloud project details:
   • GCP_PROJECT_ID: Your Google Cloud project ID
   • GCP_KEY_FILE: Path to your service account key file (JSON) with BigQuery permissions
   • BQ_DATASET_ID: BigQuery dataset ID where your analytics table is located
   • BQ_TABLE_ID: BigQuery table ID for your analytics data

Google Cloud Setup

1. Create a service account in the Google Cloud Console
2. Grant it BigQuery Data Editor permissions
3. Download the service account key (JSON file)
4. Place the key file in a secure location and update the GCP_KEY_FILE path in your .env

Firebase Authentication Setup

This server uses Firebase Authentication to verify user tokens for secure API access.

1. Create a Firebase project in the Firebase Console
2. Enable Authentication in your Firebase project and set up your preferred authentication methods
3. Generate a Firebase Admin SDK service account key:
   • Go to Project Settings > Service accounts
   • Click "Generate new private key" for Firebase Admin SDK
   • Save the JSON file securely
4. Update your .env file with Firebase configuration:
   • Set FIREBASE_PROJECT_ID to your Firebase project ID
   • Set GOOGLE_APPLICATION_CREDENTIALS to the path of your Firebase service account key

Note: You can use the same service account key for both GCP and Firebase if they're in the same Google Cloud project, but make sure it has the required permissions.

Running the Server

Build the TypeScript code:

npm run build

Development mode with auto-reload:

npm run dev

Production mode:

npm start

API Endpoints

POST /api/analytics

Accepts analytics data and inserts it into BigQuery.

Request Body Example:

{
  "event_name": "page_view",
  "session_id": "sess_123456",
  "user_id": "user_789",
  "client_name": "web",
  "page_url": "https://example.com/products",
  "referer_url": "https://example.com",
  "event_data": {
    "productId": "prod_123",
    "category": "electronics"
  },
  "event_item": "product_page"
}

Note: If event_timestamp is not provided, the current server timestamp will be used. If user_agent is not provided, it will be extracted from the request headers.

GET /health

Health check endpoint that returns a 200 status with a JSON response of {"status": "OK"}.

Client Integration

To send analytics data from a client (e.g., browser), you can use a simple fetch request with Firebase authentication:

// First authenticate with Firebase and get the ID token
firebase
  .auth()
  .currentUser.getIdToken(/* forceRefresh */ true)
  .then((idToken) => {
    // Send the token with your analytics request
    fetch("https://your-analytics-server.com/api/analytics", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${idToken}`,
      },
      body: JSON.stringify({
        event_name: "button_click",
        session_id: "user_session_id",
        // ... other analytics data
      }),
    })
      .then((response) => response.json())
      .catch((error) => console.error("Analytics error:", error));
  })
  .catch((error) => {
    console.error("Error getting auth token:", error);
  });