@proveanything/smartlinks 1.7.10 → 1.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -0
- package/dist/api/analytics.d.ts +57 -0
- package/dist/api/analytics.js +542 -0
- package/dist/api/auth.d.ts +23 -35
- package/dist/api/auth.js +104 -0
- package/dist/api/index.d.ts +1 -0
- package/dist/api/index.js +1 -0
- package/dist/docs/API_SUMMARY.md +575 -40
- package/dist/docs/analytics-metadata-conventions.md +80 -0
- package/dist/docs/analytics.md +690 -0
- package/dist/docs/interactions.md +2 -0
- package/dist/docs/overview.md +2 -1
- package/dist/index.d.ts +1 -1
- package/dist/openapi.yaml +856 -128
- package/dist/types/analytics.d.ts +307 -0
- package/dist/types/analytics.js +7 -1
- package/dist/types/auth.d.ts +67 -0
- package/dist/types/index.d.ts +1 -0
- package/dist/types/index.js +1 -0
- package/docs/API_SUMMARY.md +575 -40
- package/docs/analytics-metadata-conventions.md +80 -0
- package/docs/analytics.md +690 -0
- package/docs/interactions.md +2 -0
- package/docs/overview.md +2 -1
- package/openapi.yaml +856 -128
- package/package.json +1 -1
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Analytics Metadata Conventions
|
|
2
|
+
|
|
3
|
+
Use these as the recommended standard keys for analytics event metadata.
|
|
4
|
+
|
|
5
|
+
You can put them in `metadata` directly today. The public analytics ingestion endpoints also accept these as top-level convenience fields and mirror them into `metadata` on the backend.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Recommended Keys
|
|
10
|
+
|
|
11
|
+
### Traffic and attribution
|
|
12
|
+
|
|
13
|
+
- `referrer`
|
|
14
|
+
- `referrerHost`
|
|
15
|
+
- `utmSource`
|
|
16
|
+
- `utmMedium`
|
|
17
|
+
- `utmCampaign`
|
|
18
|
+
- `utmContent`
|
|
19
|
+
- `utmTerm`
|
|
20
|
+
- `entryType` — for example `direct`, `qr`, `nfc`, `social`, `email`, `paid`, or `organic`
|
|
21
|
+
|
|
22
|
+
### Link-tree and page analytics
|
|
23
|
+
|
|
24
|
+
- `group`
|
|
25
|
+
- `tag`
|
|
26
|
+
- `campaign`
|
|
27
|
+
- `placement`
|
|
28
|
+
- `linkGroup`
|
|
29
|
+
- `linkPlacement`
|
|
30
|
+
- `linkPosition`
|
|
31
|
+
- `linkTitle`
|
|
32
|
+
- `destinationDomain`
|
|
33
|
+
- `pagePath`
|
|
34
|
+
- `pageId`
|
|
35
|
+
- `qrCodeId`
|
|
36
|
+
|
|
37
|
+
### Physical scan analytics
|
|
38
|
+
|
|
39
|
+
- `scanMethod` — for example `nfc` or `qr`
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Why These Matter
|
|
44
|
+
|
|
45
|
+
These keys give teams a shared vocabulary for:
|
|
46
|
+
|
|
47
|
+
- inbound traffic attribution
|
|
48
|
+
- outbound link analysis
|
|
49
|
+
- link placement and link-tree performance
|
|
50
|
+
- QR and page-level traffic grouping
|
|
51
|
+
- physical scan source analysis
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Recommendation
|
|
56
|
+
|
|
57
|
+
- Treat these as reserved standard keys.
|
|
58
|
+
- Prefer these names before inventing custom alternatives.
|
|
59
|
+
- Keep values flat and scalar where possible so they are easier to filter and break down later.
|
|
60
|
+
- Promote a field to a first-class backend column only when it becomes a hot platform-wide dimension.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Example
|
|
65
|
+
|
|
66
|
+
```typescript
|
|
67
|
+
analytics.collection.track({
|
|
68
|
+
sessionId: 'sess_123',
|
|
69
|
+
eventType: 'click_link',
|
|
70
|
+
collectionId: 'demo-collection',
|
|
71
|
+
linkId: 'hero-cta',
|
|
72
|
+
href: 'https://example.com/buy',
|
|
73
|
+
placement: 'hero',
|
|
74
|
+
campaign: 'summer-launch',
|
|
75
|
+
utmSource: 'email',
|
|
76
|
+
metadata: {
|
|
77
|
+
pagePath: '/c/demo-collection',
|
|
78
|
+
},
|
|
79
|
+
})
|
|
80
|
+
```
|