@proveanything/smartlinks 1.7.10 → 1.8.1
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 +579 -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 +577 -40
- package/dist/docs/analytics-metadata-conventions.md +84 -0
- package/dist/docs/analytics.md +687 -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 +308 -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 +577 -40
- package/docs/analytics-metadata-conventions.md +84 -0
- package/docs/analytics.md +687 -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,84 @@
|
|
|
1
|
+
# Analytics Metadata Conventions
|
|
2
|
+
|
|
3
|
+
Use these as the recommended standard analytics keys.
|
|
4
|
+
|
|
5
|
+
Some of these are now promoted top-level analytics fields. Others remain good metadata keys for custom dimensions.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Recommended Keys
|
|
10
|
+
|
|
11
|
+
### Promoted top-level fields
|
|
12
|
+
|
|
13
|
+
- `visitorId`
|
|
14
|
+
- `referrerHost`
|
|
15
|
+
- `entryType`
|
|
16
|
+
- `pageId`
|
|
17
|
+
- `scanMethod`
|
|
18
|
+
|
|
19
|
+
These should be sent as top-level analytics fields, not inside `metadata`.
|
|
20
|
+
|
|
21
|
+
### Metadata-friendly keys
|
|
22
|
+
|
|
23
|
+
- `referrer`
|
|
24
|
+
- `utmSource`
|
|
25
|
+
- `utmMedium`
|
|
26
|
+
- `utmCampaign`
|
|
27
|
+
- `utmContent`
|
|
28
|
+
- `utmTerm`
|
|
29
|
+
- `group`
|
|
30
|
+
- `tag`
|
|
31
|
+
- `campaign`
|
|
32
|
+
- `placement`
|
|
33
|
+
- `linkGroup`
|
|
34
|
+
- `linkPlacement`
|
|
35
|
+
- `linkPosition`
|
|
36
|
+
- `linkTitle`
|
|
37
|
+
- `destinationDomain`
|
|
38
|
+
- `pagePath`
|
|
39
|
+
- `qrCodeId`
|
|
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
|
+
- Send promoted fields at top level.
|
|
60
|
+
- Keep values flat and scalar where possible so they are easier to filter and break down later.
|
|
61
|
+
- Promote a field to a first-class backend column only when it becomes a hot platform-wide dimension.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Example
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
analytics.collection.track({
|
|
69
|
+
sessionId: 1234567890,
|
|
70
|
+
eventType: 'click_link',
|
|
71
|
+
collectionId: 'demo-collection',
|
|
72
|
+
visitorId: 'visitor_123',
|
|
73
|
+
linkId: 'hero-cta',
|
|
74
|
+
href: 'https://example.com/buy',
|
|
75
|
+
referrerHost: 'instagram.com',
|
|
76
|
+
placement: 'hero',
|
|
77
|
+
campaign: 'summer-launch',
|
|
78
|
+
utmSource: 'email',
|
|
79
|
+
pageId: 'QR123',
|
|
80
|
+
metadata: {
|
|
81
|
+
pagePath: '/c/demo-collection',
|
|
82
|
+
},
|
|
83
|
+
})
|
|
84
|
+
```
|