feat: whyrating - initial project from turbostarter boilerplate
This commit is contained in:
Alejandro Gutiérrez
@@ -0,0 +1,92 @@
|
||||
---
|
||||
title: Configuration
|
||||
description: Learn how to configure extension analytics in TurboStarter.
|
||||
url: /docs/extension/analytics/configuration
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
The `@turbostarter/analytics-extension` package offers a streamlined and flexible approach to tracking events in your TurboStarter extension using various analytics providers. It abstracts the complexities of different analytics services and provides a consistent interface for event tracking.
|
||||
|
||||
In this section, we'll guide you through the configuration process for each supported provider.
|
||||
|
||||
Note that the configuration is validated against a schema, so you'll see error messages in the console if anything is misconfigured.
|
||||
|
||||
## Providers
|
||||
|
||||
Below, you'll find detailed information on how to set up and use each supported provider. Choose the one that best suits your needs and follow the instructions in the respective accordion section.
|
||||
|
||||
<Accordions>
|
||||
<Accordion title="Google Analytics" id="google-analytics">
|
||||
To use Google Analytics as your analytics provider, you need to [create a Google Analytics account](https://analytics.google.com/) and [set up a property](https://support.google.com/analytics/answer/9304153).
|
||||
|
||||
Next, add a data stream in your Google Analytics account settings:
|
||||
|
||||
1. Navigate to [Google Analytics](https://analytics.google.com/).
|
||||
2. In the *Admin* section, under *Data collection and modification*, click on *Data Streams*.
|
||||
3. Click *Add stream*.
|
||||
4. Select *Web* as the platform.
|
||||
5. Enter the required details for the stream (at minimum, provide a name and website URL).
|
||||
6. Click *Create stream*.
|
||||
|
||||
After creating the stream, you'll need two pieces of information:
|
||||
|
||||
1. Your [Measurement ID](https://support.google.com/analytics/answer/12270356) (it should look like `G-XXXXXXXXXX`):
|
||||
|
||||
|
||||
|
||||
2. Your [Measurement Protocol API secret](https://support.google.com/analytics/answer/9814495):
|
||||
|
||||
|
||||
|
||||
Set these values in your `.env.local` file in the `apps/extension` directory and in your CI/CD provider secrets:
|
||||
|
||||
```dotenv
|
||||
VITE_GOOGLE_ANALYTICS_MEASUREMENT_ID="your-measurement-id"
|
||||
VITE_GOOGLE_ANALYTICS_SECRET="your-measurement-protocol-api-secret"
|
||||
```
|
||||
|
||||
Also, make sure to activate the Google Analytics provider as your analytics provider by updating the exports in:
|
||||
|
||||
```ts title="index.ts"
|
||||
// [!code word:google-analytics]
|
||||
export * from "./google-analytics";
|
||||
export * from "./google-analytics/env";
|
||||
```
|
||||
|
||||
To customize the provider, you can find its definition in `packages/analytics/extension/src/providers/google-analytics` directory.
|
||||
|
||||
For more information, please refer to the [Google Analytics documentation](https://developers.google.com/analytics).
|
||||
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="PostHog" id="posthog">
|
||||
<Callout type="info" title="You can also use it for monitoring!">
|
||||
PostHog is also one of pre-configured providers for [monitoring](/docs/extension/monitoring/overview) in TurboStarter. You can learn more about it [here](/docs/extension/monitoring/posthog).
|
||||
</Callout>
|
||||
|
||||
To use PostHog as your analytics provider, you need to configure a PostHog instance. You can obtain the [Cloud](https://app.posthog.com/signup) instance by [creating an account](https://app.posthog.com/signup) or [self-host](https://posthog.com/docs/self-host) it.
|
||||
|
||||
Then, create a project and, based on your [project settings](https://app.posthog.com/project/settings), fill the following environment variables in your `.env.local` file in `apps/extension` directory and your CI/CD provider secrets:
|
||||
|
||||
```dotenv
|
||||
VITE_POSTHOG_KEY="your-posthog-api-key"
|
||||
VITE_POSTHOG_HOST="your-posthog-instance-host"
|
||||
```
|
||||
|
||||
Also, make sure to activate the PostHog provider as your analytics provider by updating the exports in:
|
||||
|
||||
```ts title="index.ts"
|
||||
// [!code word:posthog]
|
||||
export * from "./posthog";
|
||||
export * from "./posthog/env";
|
||||
```
|
||||
|
||||
To customize the provider, you can find its definition in `packages/analytics/extension/src/providers/posthog` directory.
|
||||
|
||||
For more information, please refer to the [PostHog documentation](https://posthog.com/docs/advanced/browser-extension).
|
||||
|
||||
|
||||
</Accordion>
|
||||
</Accordions>
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Overview
|
||||
description: Get started with extension analytics in TurboStarter.
|
||||
url: /docs/extension/analytics/overview
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
When it comes to extension analytics, we can distinguish between two types:
|
||||
|
||||
* **Store listing analytics**: Used to track the performance of your extension's store listing (e.g., how many people have viewed your extension in the store or how many have installed it).
|
||||
* **In-extension analytics**: Tracks user actions within your extension (e.g., how many users triggered your popup, how many users modified extension settings, etc.).
|
||||
|
||||
The `@turbostarter/analytics-extension` package provides a set of tools to easily implement both types of analytics in your extension.
|
||||
|
||||
## Store listing analytics
|
||||
|
||||
Interpreting your extension's store listing metrics can help you evaluate how changes to your extension and store listing affect conversion rates. For example, you can identify countries with a high number of visitors to prioritize supporting languages for those regions.
|
||||
|
||||
While each store implements a different set of metrics, there are some common ones you should be aware of:
|
||||
|
||||
* **Active installs**: The number of users who have installed your extension.
|
||||
* **Active users**: The number of users who have used your extension.
|
||||
* **Page views**: The number of times users have viewed your extension's detail page on the respective store.
|
||||
|
||||
To track more detailed metrics, you can opt in to Google Analytics in the Chrome Web Store's developer dashboard.
|
||||
|
||||
You can find this option under *Additional metrics* on the *Store listing* tab of your extension's control panel:
|
||||
|
||||
|
||||
|
||||
<Callout>
|
||||
The Chrome Web Store manages the account for you and makes the data available
|
||||
in the Google Analytics dashboard.
|
||||
</Callout>
|
||||
|
||||
By enabling this feature, you can optimize your extension's store listing based on metrics such as bounce rate, time on page, and more. This can lead to more installs and ultimately more users for your extension.
|
||||
|
||||
To learn more about the limitations of this type of analytics and how to adjust event details, please refer to the following sections in the official documentation:
|
||||
|
||||
<Cards>
|
||||
<Card title="Analyze your store listing metrics" description="developer.chrome.com" href="https://developer.chrome.com/docs/webstore/metrics" />
|
||||
|
||||
<Card title="Use your Google Analytics account with the Chrome Web Store" description="developer.chrome.com" href="https://developer.chrome.com/docs/webstore/google-analytics" />
|
||||
</Cards>
|
||||
|
||||
## In-extension analytics
|
||||
|
||||
TurboStarter comes with built-in support for tracking in-extension analytics. To learn more about each supported provider and how to configure them, see their respective sections:
|
||||
|
||||
<Cards>
|
||||
<Card title="Google Analytics" href="/docs/extension/analytics/configuration#google-analytics" />
|
||||
|
||||
<Card title="PostHog" href="/docs/extension/analytics/configuration#posthog" />
|
||||
</Cards>
|
||||
|
||||
All configuration and setup is built-in with a unified API, allowing you to switch between providers by simply changing the exports. You can even introduce your own provider without breaking any tracking-related logic.
|
||||
|
||||
In the following sections, we'll cover how to set up each provider and how to track events in your extension.
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: Tracking events
|
||||
description: Learn how to track events in your TurboStarter extension.
|
||||
url: /docs/extension/analytics/tracking
|
||||
---
|
||||
|
||||
# Tracking events
|
||||
|
||||
The strategy for tracking events that every provider has to implement is extremely simple:
|
||||
|
||||
```ts
|
||||
export type AllowedPropertyValues = string | number | boolean;
|
||||
|
||||
type TrackFunction = (
|
||||
event: string,
|
||||
data?: Record<string, AllowedPropertyValues>,
|
||||
) => void;
|
||||
|
||||
export interface AnalyticsProviderStrategy {
|
||||
track: TrackFunction;
|
||||
}
|
||||
```
|
||||
|
||||
<Callout>
|
||||
You don't need to worry much about this implementation, as all the providers are already configured for you. However, it's useful to be aware of this structure if you plan to add your own custom provider.
|
||||
</Callout>
|
||||
|
||||
As shown above, each provider must supply the `track` function. This function is responsible for sending event data to the provider.
|
||||
|
||||
To track an event in any part of your extension, simply call the `track` method, passing the event name and an optional data object:
|
||||
|
||||
```tsx title="main.tsx"
|
||||
import { track } from "@turbostarter/analytics-extension";
|
||||
|
||||
const Popup = () => {
|
||||
return (
|
||||
<button onClick={() => track("popup.button.click", { country: "US" })}>
|
||||
Track event
|
||||
</button>
|
||||
);
|
||||
};
|
||||
|
||||
export default Popup;
|
||||
```
|
||||
|
||||
## Identifying users
|
||||
|
||||
Linking events to specific users enables you to build a full picture of how they're using your product across different sessions, devices, and platforms.
|
||||
|
||||
For identification purposes, we're extending the strategy with the `identify` and `reset` methods. They are optional and only needed if you want to identify users in your app and associate their actions with a specific user ID.
|
||||
|
||||
```ts
|
||||
type IdentifyFunction = (
|
||||
userId: string,
|
||||
traits?: Record<string, AllowedPropertyValues>,
|
||||
) => void;
|
||||
|
||||
export interface AnalyticsProviderClientStrategy {
|
||||
identify: IdentifyFunction;
|
||||
reset: () => void;
|
||||
}
|
||||
```
|
||||
|
||||
To identify users, call the `identify` method, passing the user's ID and an optional traits object:
|
||||
|
||||
```tsx
|
||||
import { identify } from "@turbostarter/analytics-extension";
|
||||
|
||||
identify("user-123", { name: "John Doe" });
|
||||
```
|
||||
|
||||
This will associate all future events with the user's ID, allowing you to track user behavior and gain valuable insights into your application's usage patterns.
|
||||
|
||||
<Callout title="Configured by default!">
|
||||
The `identify` method is configured out-of-the-box to react on changes to the user's authentication state.
|
||||
|
||||
When the user is authenticated, the `identify` method will be called with the user's ID and the user's traits. When the user is logged out, the `reset` method will be called to clear the existing user identification.
|
||||
</Callout>
|
||||
|
||||
Congratulations! You've now mastered event tracking in your TurboStarter extension. With this knowledge, you're well-equipped to analyze user behaviors and gain valuable insights into your extension's usage patterns. Happy analyzing! 📊
|
||||
Reference in New Issue
Block a user