Skip to content

Commit 42fa125

Browse files
paulpopuspaulpopus
committed
Add documentation
1 parent 71ab3d7 commit 42fa125

File tree

1 file changed

+238
-7
lines changed

1 file changed

+238
-7
lines changed

‎README.md‎

Lines changed: 238 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
1-
# Payload Dashboard Analytics Plugin (ALPHA)
2-
3-
**Expect breaking changes.**
1+
# Payload Dashboard Analytics Plugin
42

53
A plugin for [Payload CMS](https://github.com/payloadcms/payload) to connect analytics data to your Payload dashboard.
64

7-
Roadmap to stable release:
5+
Features:
86

9-
- Support for GA
10-
- Support for Plausible
7+
- Chart widgets on collections, globals and dashboard
8+
- Live users indicator in sidebar
9+
- Aggregate data widgets on collections and globals
10+
- Basic report widgets on dashboard
11+
- Support for Plausible and Google Analytics
1112

1213
## Installation
1314

@@ -22,9 +23,235 @@ Roadmap to stable release:
2223
In the `plugins` array of your [Payload config](https://payloadcms.com/docs/configuration/overview), call the plugin with [options](#options):
2324

2425
```ts
25-
// add example
26+
// ...
27+
payloadDashboardAnalytics({
28+
provider: {
29+
source: "plausible",
30+
apiSecret: PLAUSIBLE_API_KEY,
31+
siteId: PLAUSIBLE_SITE_ID,
32+
host: PLAUSIBLE_HOST, // optional, for self-hosted instances
33+
},
34+
access: (user: any) => {
35+
return Boolean(user);
36+
},
37+
navigation: {
38+
afterNavLinks: [
39+
{
40+
type: "live",
41+
},
42+
],
43+
},
44+
dashboard: {
45+
beforeDashboard: ["viewsChart"],
46+
afterDashboard: ["topPages"],
47+
},
48+
globals: [
49+
{
50+
slug: "homepage",
51+
widgets: [
52+
{
53+
type: "info",
54+
label: "Page data",
55+
metrics: ["views", "sessions", "sessionDuration"],
56+
timeframe: "currentMonth",
57+
idMatcher: () => `/`,
58+
},
59+
],
60+
},
61+
],
62+
collections: [
63+
{
64+
slug: Posts.slug,
65+
widgets: [
66+
{
67+
type: "chart",
68+
label: "Views and visitors",
69+
metrics: ["views", "visitors", "sessions"],
70+
timeframe: "30d",
71+
idMatcher: (document: any) => `/articles/${document.slug}`,
72+
},
73+
],
74+
},
75+
],
76+
}),
77+
78+
// ...
2679
```
2780

81+
## Configuration
82+
83+
- `provider` | required
84+
85+
Configuration for a [supported provider](#providers).
86+
87+
- `access` | optional
88+
89+
Accepts a function that takes in the req.user object to determine access to the API routes. **By default the routes are unprotected.**
90+
91+
Example to allow only authenticated users:
92+
93+
```ts
94+
access: (user: any) => Boolean(user);
95+
```
96+
97+
- `navigation` | optional
98+
99+
Object of either `beforeNavLinks` `afterNavLinks` which are arrays of [navigation widgets](#navigation).
100+
101+
- `dashboard` | optional
102+
103+
Object of either `beforeDashboard` `afterDashboard` which are arrays of [dashboard widgets](#dashboard).
104+
105+
- `globals` | optional
106+
107+
Array of global configurations requiring a slug and an array of [page widgets](#page).
108+
109+
- `collections` | optional
110+
111+
Array of collection configurations requiring a slug and an array of [page widgets](#page).
112+
113+
## Widgets
114+
115+
A full list of supported widgets. Due to some time limitations or API constraints the selection may be limited.
116+
117+
### Navigation
118+
119+
Navigation widgets have no configuration.
120+
121+
#### Live visitors
122+
123+
**type** `live`
124+
125+
```ts
126+
{
127+
type: "live";
128+
}
129+
```
130+
131+
### Dashboard
132+
133+
Dashboard widgets have no configuration.
134+
135+
#### Views chart
136+
137+
**type** `viewsChart`
138+
139+
```ts
140+
["viewsChart"];
141+
```
142+
143+
#### Top pages
144+
145+
**type** `topPages`
146+
147+
```ts
148+
["topPages"];
149+
```
150+
151+
### Page
152+
153+
Page widgets have more configuration available with custom timeframes and metrics. These are usable on both globals and collections.
154+
155+
#### Page chart
156+
157+
- **type** | `chart` | required
158+
159+
- **label** | string or `hidden` | optional
160+
Sets a custom label for the component in the frontend, defaults to a list of metrics and it's accompanied by the timeframe.
161+
If `hidden` then the label is not displayed.
162+
163+
- **metrics** | metric[] | required
164+
Array of metrics to fetch data for. See list of [available metrics](#metrics).
165+
166+
- **timeframe** | timeframe | optional
167+
Defaults to `30d`. See list of [available timeframes](#timeframes).
168+
169+
- **idMatches** | function | required
170+
A function that takes in the published document from the React hook `useDocument` and returns a string that matches the current page to a page in the analytics data.
171+
172+
```ts
173+
{
174+
type: "chart",
175+
label: "Views and visitors",
176+
metrics: ["views", "visitors", "sessions"],
177+
timeframe: "30d",
178+
idMatcher: (document: any) => `/blog/${document.slug}`,
179+
}
180+
```
181+
182+
#### Page info
183+
184+
- **type** | `info` | required
185+
186+
- **label** | string or `hidden` | optional
187+
Sets a custom label for the component in the frontend, defaults to a list of metrics and it's accompanied by the timeframe.
188+
If `hidden` then the label is not displayed.
189+
190+
- **metrics** | metric[] | required
191+
Array of metrics to fetch data for. See list of [available metrics](#metrics).
192+
193+
- **timeframe** | timeframe | optional
194+
Defaults to `30d`. See list of [available timeframes](#timeframes).
195+
196+
- **idMatches** | function | required
197+
A function that takes in the published document from the React hook `useDocument` and returns a string that matches the current page to a page in the analytics data.
198+
199+
```ts
200+
{
201+
type: "info",
202+
label: "Views and visitors",
203+
metrics: ["views", "visitors", "sessions"],
204+
timeframe: "7d",
205+
idMatcher: (document: any) => `/blog/${document.slug}`,
206+
}
207+
```
208+
209+
### Timeframes
210+
211+
Currently supported timeframes.
212+
213+
- `12mo`
214+
- `6mo`
215+
- `30d`
216+
- `7d`
217+
- `currentMonth` limits the data period to the current month
218+
219+
### Metrics
220+
221+
A full list of currently supported metrics, each provider will map these on their own internally to the API they communicate with.
222+
223+
- `views`
224+
- `visitors`
225+
- `sessions`
226+
- `sessionDuration`
227+
- `bounceRate`
228+
229+
### Properties
230+
231+
Properties are used to generate reports, currently the widgets are limited in configuration but these should be fully supported via the API routes.
232+
233+
- `page`
234+
- `source`
235+
- `entryPoint`
236+
- `exitPoint`
237+
- `country`
238+
239+
## Providers
240+
241+
### Plausible
242+
243+
### Google Analytics
244+
245+
tbd
246+
247+
## API
248+
249+
To do, add API documentation.
250+
251+
## Known issues
252+
253+
Multi-metric charts have a floating tooltip in the wrong position, this is a problem upstream.
254+
28255
## Development
29256

30257
For development purposes, there is a full working example of how this plugin might be used in the [demo](./demo) of this repo. Then:
@@ -37,3 +264,7 @@ git clone [email protected]:NouanceLabs/payload-dashboard-analytics.git \
37264
vim .env \ # add your API creds to this file
38265
yarn dev
39266
```
267+
268+
### Add custom provider
269+
270+
Tbd

0 commit comments

Comments
 (0)