Skip to content

Commit 66a1b71

Browse files
twlitetwlite
committed
docs: document analytics
1 parent f8756f2 commit 66a1b71

File tree

5 files changed

+542
-0
lines changed

5 files changed

+542
-0
lines changed

‎apps/website/docs/guide/06-plugins/official-plugins/05-analytics.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: Analytics Plugin
3+
description: The analytics plugin for CommandKit enables analytics in your project. It provides a simple and efficient way to track events and metrics.
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
# Analytics Plugin
10+
11+
The analytics plugin for CommandKit enables analytics in your project. It provides a simple and efficient way to track events and metrics.
12+
13+
## Installation
14+
15+
<Tabs>
16+
<TabItem value="npm" label="npm">
17+
18+
```bash
19+
npm install @commandkit/analytics
20+
```
21+
22+
</TabItem>
23+
<TabItem value="yarn" label="yarn">
24+
25+
```bash
26+
yarn add @commandkit/analytics
27+
```
28+
29+
</TabItem>
30+
<TabItem value="pnpm" label="pnpm">
31+
32+
```bash
33+
pnpm add @commandkit/analytics
34+
```
35+
36+
</TabItem>
37+
</Tabs>
38+
39+
## Usage
40+
41+
This plugin automatically registers the analytics provider with your CommandKit instance.
42+
43+
```js
44+
import { defineConfig } from 'commandkit';
45+
import { umami } from '@commandkit/analytics/umami';
46+
47+
export default defineConfig({
48+
plugins: [umami({...})],
49+
});
50+
```
51+
52+
To understand more about analytics, check out the [Analytics in CommandKit](../../10-analytics/01-analytics-in-commandkit.mdx) guide.

‎apps/website/docs/guide/10-analytics/01-analytics-in-commandkit.mdx‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: Analytics in CommandKit
3+
description: Learn how to use the analytics plugin in CommandKit to track events and metrics.
4+
---
5+
6+
# Analytics in CommandKit
7+
8+
The analytics plugin for CommandKit enables analytics in your project. It provides a simple and efficient way to track events and metrics. CommandKit itself does not store any analytics data - it acts as a bridge between your application and your chosen analytics provider.
9+
10+
## How it Works
11+
12+
CommandKit's analytics system is designed to be provider-agnostic. This means:
13+
14+
1. CommandKit doesn't store any analytics data itself
15+
2. All data is sent directly to your configured analytics provider
16+
3. You can easily switch between different providers or use multiple providers
17+
4. The system is extensible, allowing you to create custom providers
18+
19+
## Automatic Tracking
20+
21+
CommandKit automatically tracks various anonymous metrics:
22+
23+
- Command execution counts and success rates
24+
- Feature flag usage statistics
25+
- Cache performance metrics
26+
- Guild count changes
27+
- Anonymous interaction patterns
28+
29+
## Installation
30+
31+
```sh
32+
npm install @commandkit/analytics
33+
```
34+
35+
## Basic Usage
36+
37+
To track custom events in your Discord bot:
38+
39+
```ts
40+
import { track } from 'commandkit/analytics';
41+
42+
// Track a custom event with anonymous data
43+
await track({
44+
name: 'button_interaction',
45+
data: {
46+
buttonType: 'verification',
47+
// Use hashed or anonymous identifiers if needed
48+
interactionType: 'button',
49+
// Track timing for performance metrics
50+
responseTime: 150,
51+
},
52+
});
53+
```
54+
55+
## Filtering Events
56+
57+
You can filter out specific events using the `setFilter` function:
58+
59+
```ts
60+
import { useAnalytics } from 'commandkit/analytics';
61+
62+
const analytics = useAnalytics();
63+
64+
// Filter out events based on anonymous criteria
65+
analytics.setFilter((engine, event) => {
66+
// Skip events from development environments
67+
if (process.env.NODE_ENV === 'development') {
68+
return true; // true means skip this event
69+
}
70+
71+
// Skip specific event types
72+
if (event.name === 'debug_event') {
73+
return true;
74+
}
75+
76+
return false; // false means track this event
77+
});
78+
```
79+
80+
## Available Providers
81+
82+
CommandKit comes with built-in support for popular analytics providers:
83+
84+
- [PostHog](./02-posthog.mdx)
85+
- [Umami](./03-umami.mdx)
86+
87+
## Creating Custom Providers
88+
89+
You can create your own analytics provider by implementing the `AnalyticsProvider` interface. See our [Custom Providers](./04-custom-providers.mdx) guide for detailed instructions.
90+
91+
## Disabling Analytics
92+
93+
You can disable analytics for specific requests (i.e. command or event scoped) using the `noAnalytics` function:
94+
95+
```ts
96+
import { noAnalytics } from 'commandkit/analytics';
97+
98+
// Disable analytics for specific commands or events
99+
if (interaction.commandName === 'debug') {
100+
noAnalytics();
101+
}
102+
```
103+
104+
## Privacy Considerations
105+
106+
When implementing analytics in your bot, consider:
107+
108+
1. Only track anonymous, aggregated data
109+
2. Avoid storing personal information
110+
3. Use hashed identifiers when necessary
111+
4. Be transparent about what data you collect
112+
5. Respect user privacy and Discord's Terms of Service
113+
114+
## Next Steps
115+
116+
- Learn how to [set up PostHog](./02-posthog.mdx)
117+
- Learn how to [set up Umami](./03-umami.mdx)
118+
- Learn how to [create custom providers](./04-custom-providers.mdx)

‎apps/website/docs/guide/10-analytics/02-posthog.mdx‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: PostHog Analytics
3+
description: Learn how to set up and use PostHog analytics with CommandKit.
4+
---
5+
6+
# PostHog Analytics
7+
8+
PostHog is an open-source product analytics platform that helps you understand user behavior. CommandKit provides a simple way to integrate PostHog into your Discord bot.
9+
10+
## Setup
11+
12+
1. First, install the analytics package:
13+
14+
```sh
15+
npm install @commandkit/analytics
16+
```
17+
18+
2. Configure PostHog in your CommandKit config:
19+
20+
```ts
21+
import { posthog } from '@commandkit/analytics/posthog';
22+
23+
export default defineConfig({
24+
plugins: [
25+
posthog({
26+
posthogOptions: {
27+
apiKey: 'YOUR_POSTHOG_API_KEY',
28+
},
29+
}),
30+
],
31+
});
32+
```
33+
34+
## Usage
35+
36+
Once configured, you can track anonymous events using the `track` function:
37+
38+
```ts
39+
import { track } from 'commandkit/analytics';
40+
41+
// Track a custom event with anonymous data
42+
await track({
43+
name: 'command_executed',
44+
data: {
45+
commandName: 'ban',
46+
// Track performance metrics
47+
executionTime: 150, // ms
48+
// Track anonymous usage patterns
49+
timeOfDay: new Date().getHours(),
50+
dayOfWeek: new Date().getDay(),
51+
},
52+
});
53+
```
54+
55+
## Identifying Anonymous Sessions
56+
57+
You can identify anonymous sessions in PostHog using the `identify` function:
58+
59+
```ts
60+
import { useAnalytics } from 'commandkit/analytics';
61+
62+
const analytics = useAnalytics();
63+
await analytics.identify({
64+
// Use a hashed or anonymous identifier
65+
distinctId: 'session_' + Math.random().toString(36).substring(7),
66+
properties: {
67+
// Track anonymous session properties
68+
sessionStart: Date.now(),
69+
environment: process.env.NODE_ENV,
70+
version: '1.0.0',
71+
},
72+
});
73+
```
74+
75+
## Automatic Events
76+
77+
CommandKit automatically tracks the following anonymous events in PostHog:
78+
79+
- `command_executed`: Command execution counts and success rates
80+
- `command_error`: Error rates and types (without personal data)
81+
- `guild_count`: Changes in total guild count
82+
- `feature_flag_used`: Feature flag usage statistics
83+
- `cache_operation`: Cache performance metrics
84+
85+
## Best Practices
86+
87+
1. Use consistent event names across your bot
88+
2. Only track anonymous, aggregated data
89+
3. Avoid storing personal information
90+
4. Use hashed identifiers when necessary
91+
5. Be transparent about what data you collect
92+
6. Respect user privacy and Discord's Terms of Service
93+
94+
## Next Steps
95+
96+
- Learn about [Umami analytics](./03-umami.mdx)
97+
- Learn how to [create custom providers](./04-custom-providers.mdx)

‎apps/website/docs/guide/10-analytics/03-umami.mdx‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Umami Analytics
3+
description: Learn how to set up and use Umami analytics with CommandKit.
4+
---
5+
6+
# Umami Analytics
7+
8+
Umami is a simple, fast, privacy-focused alternative to Google Analytics. CommandKit provides seamless integration with Umami for tracking anonymous bot metrics.
9+
10+
## Setup
11+
12+
1. First, install the analytics package:
13+
14+
```sh
15+
npm install @commandkit/analytics
16+
```
17+
18+
2. Configure Umami in your CommandKit config:
19+
20+
```ts
21+
import { umami } from '@commandkit/analytics/umami';
22+
23+
export default defineConfig({
24+
plugins: [
25+
umami({
26+
umamiOptions: {
27+
hostUrl: 'YOUR_UMAMI_HOST_URL',
28+
websiteId: 'YOUR_UMAMI_WEBSITE_ID',
29+
// Optional: Additional configuration
30+
sessionId: 'YOUR_UMAMI_SESSION_ID',
31+
userAgent: 'YOUR_UMAMI_USER_AGENT',
32+
},
33+
}),
34+
],
35+
});
36+
```
37+
38+
## Usage
39+
40+
Once configured, you can track anonymous events using the `track` function:
41+
42+
```ts
43+
import { track } from 'commandkit/analytics';
44+
45+
await track({
46+
name: 'guild_event',
47+
data: {
48+
eventType: 'member_count_change',
49+
// Track anonymous metrics
50+
memberCount: guild.memberCount,
51+
// Track timing patterns
52+
timeOfDay: new Date().getHours(),
53+
// Track performance
54+
processingTime: 100, // ms
55+
},
56+
});
57+
```
58+
59+
## Automatic Events
60+
61+
CommandKit automatically tracks the following anonymous events in Umami:
62+
63+
- Command execution counts and success rates
64+
- Guild count changes
65+
- Feature flag usage statistics
66+
- Cache performance metrics
67+
- Anonymous interaction patterns
68+
69+
## Best Practices
70+
71+
1. Keep event names simple and descriptive
72+
2. Only track anonymous, aggregated data
73+
3. Avoid storing personal information
74+
4. Use hashed identifiers when necessary
75+
5. Be transparent about what data you collect
76+
6. Respect user privacy and Discord's Terms of Service
77+
78+
## Next Steps
79+
80+
- Learn about [PostHog analytics](./02-posthog.mdx)
81+
- Learn how to [create custom providers](./04-custom-providers.mdx)

0 commit comments

Comments
 (0)