Analytics Provider Setup

Guide: Setting Up Analytics Providers

This guide details the steps to grant the correct permissions to your existing Firebase service account and configure the necessary data definitions to allow the server to sync analytics data.

---

Step 1: Identify Your Service Account Email

Your Firebase project has an automatically generated service account. Your server uses this account to authenticate with Google services.

1. Open your project's .env file.
2. Find the FIREBASE_CLIENT_EMAIL variable. It will look like this: firebase-adminsdk-xxxxx@your-project-id.iam.gserviceaccount.com
3. Copy this full email address. This is the identity you need to grant permissions to.

---

Step 2: Identify Your Analytics Property ID

Your server needs to know which Google Analytics property to read from.

1. Open your project's .env file.
2. Find the GOOGLE_ANALYTICS_PROPERTY_ID variable.
3. Copy this ID. This is the property you need to grant access to.

---

Step 3: Grant Permissions in Google Analytics

1. Navigate to your Google Analytics Dashboard.
2. In the bottom-left corner, click Admin (the gear icon).
3. look for the Property Details section in the Property column.
4. Verify that the Property ID displayed at the top right of the newly opened page exactly match the value of GOOGLE_ANALYTICS_PROPERTY_ID from your .env file.
   • If it does not match, use the dropdown menu at the top of the page to select the correct property before proceeding.
5. Once you are viewing the correct property, navigate back to the Admin main menu.
6. In the "Property" column, click on Property Access Management.
7. Click the blue + button in the top right and select "Add users".
8. In the "Email address" field, paste the service account email you copied in Step 1.
9. Under "Roles", select "Viewer".
10. Click the "Add" button in the top right to save the changes.

The service account now has the necessary permissions to read analytics data.

---

Step 4: Configure Custom Dimensions (Critical)

For the dashboard to function correctly, you must explicitly tell Google Analytics to track several event parameters as custom dimensions. This is critical for both "Ranked Lists" (e.g., Most Viewed Headlines) and the "Onboarding Funnels". Without these, the API will return errors or incomplete data.

You will need to repeat the creation process for each of the dimensions listed below.

1. Navigate to your Google Analytics Dashboard.
2. In the bottom-left corner, click Admin (the gear icon).
3. Click on Custom definitions in the "Data display" column.
4. Click the blue Create custom dimensions button.

Dimension 1: contentId

Fill in the form exactly as follows:

• Dimension name: contentId
• Scope: Event
• Description: The unique ID of the content item (e.g., headline).
• Event parameter: contentId (This must match the key sent by the app exactly). Click Save.

Dimension 2: step_index

Click Create custom dimensions again and fill in the form:

• Dimension name: step_index
• Scope: Event
• Description: The numerical index of a step in a multi-step flow (e.g., app tour).
• Event parameter: step_index Click Save.

Dimension 3: step_name

Click Create custom dimensions again and fill in the form:

• Dimension name: step_name
• Scope: Event
• Description: The string name of a step in a multi-step flow (e.g., initial personalization).
• Event parameter: step_name Click Save.

Note: It may take 24-48 hours for data to start populating in these new dimensions for API queries.