Skip to content

Commit 2e075c6

Browse files
alex72508alex72508
committed
Updating Hall integration
1 parent 268bc31 commit 2e075c6

File tree

4 files changed

+179
-60
lines changed

4 files changed

+179
-60
lines changed

‎amplify-hall-setup.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Hall Analytics Setup for AWS Amplify
2+
3+
## Environment Variable Setup
4+
5+
Since AWS Amplify doesn't support server-side middleware, we've implemented client-side analytics tracking. You need to set the environment variable in your Amplify console:
6+
7+
### 1. Set Environment Variable in Amplify
8+
9+
1. Go to your AWS Amplify Console
10+
2. Navigate to your app → **Environment variables**
11+
3. Add a new environment variable:
12+
- **Key**: `PUBLIC_HALL_API_KEY`
13+
- **Value**: Your Hall API key
14+
4. **Redeploy** your application
15+
16+
### 2. Verify the Setup
17+
18+
After redeploying, you should see:
19+
20+
1. **Browser Console Logs**: Open browser dev tools and look for:
21+
```
22+
[Hall Analytics] Page view tracked: /get-started/guides/first-things-first/
23+
```
24+
25+
2. **Hall Dashboard**: Check your [Hall dashboard](https://app.usehall.com) for incoming data
26+
27+
### 3. Test the Integration
28+
29+
Visit your site and check:
30+
- Browser console for tracking messages
31+
- Hall dashboard for new visits
32+
- Network tab for requests to `analytics.usehall.com`
33+
34+
## How Client-Side Tracking Works
35+
36+
The client-side implementation:
37+
38+
- **Tracks page views** when users visit pages
39+
- **Captures browser data** (User-Agent, Referer, etc.)
40+
- **Sends data asynchronously** to Hall
41+
- **Works with static hosting** like Amplify
42+
- **Handles navigation** in single-page app style
43+
44+
## Differences from Server-Side
45+
46+
| Aspect | Server-Side | Client-Side |
47+
|--------|-------------|-------------|
48+
| **IP Address** | Real server IP | Client IP (127.0.0.1) |
49+
| **Hosting** | Requires server | Works with static hosting |
50+
| **Performance** | No client impact | Minimal client impact |
51+
| **Reliability** | Server-side execution | Depends on client JavaScript |
52+
53+
## Troubleshooting
54+
55+
### If no tracking appears:
56+
57+
1. **Check environment variable**: Ensure `PUBLIC_HALL_API_KEY` is set in Amplify
58+
2. **Check browser console**: Look for Hall Analytics messages
59+
3. **Check network tab**: Look for requests to `analytics.usehall.com`
60+
4. **Verify API key**: Test with curl command from earlier
61+
62+
### Common issues:
63+
64+
- **Environment variable not set**: Add `PUBLIC_HALL_API_KEY` to Amplify
65+
- **JavaScript disabled**: Client-side tracking won't work
66+
- **Ad blockers**: May block analytics requests
67+
- **CORS issues**: Should work with Hall's API
68+
69+
## Testing Commands
70+
71+
Test your API key manually:
72+
```bash
73+
curl -X POST https://analytics.usehall.com/visit \
74+
-H "Content-Type: application/json" \
75+
-H "Authorization: Bearer YOUR_API_KEY" \
76+
-d '{"request_path":"/test","request_method":"GET","request_ip":"127.0.0.1","request_headers":{"User-Agent":"Test"},"request_timestamp":1234567890}'
77+
```
78+
79+
## Next Steps
80+
81+
1. **Set the environment variable** in Amplify console
82+
2. **Redeploy** your application
83+
3. **Test by visiting** your site
84+
4. **Check Hall dashboard** for incoming data
85+
5. **Monitor browser console** for tracking messages

‎src/components/HallAnalytics.astro

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
// Client-side Hall Analytics Component
3+
// This works with static hosting like AWS Amplify
4+
const HALL_API_KEY = import.meta.env.HALL_API_KEY;
5+
---
6+
7+
{HALL_API_KEY && (
8+
<script define:vars={{ HALL_API_KEY }}>
9+
// Hall Analytics Client-Side Tracking
10+
(function() {
11+
'use strict';
12+
13+
const HALL_API_KEY = HALL_API_KEY;
14+
15+
if (!HALL_API_KEY) {
16+
console.warn('[Hall Analytics] No API key found');
17+
return;
18+
}
19+
20+
// Track page view when component loads
21+
function trackPageView() {
22+
const path = window.location.pathname + window.location.search;
23+
const method = 'GET';
24+
const timestamp = Date.now();
25+
26+
// Get IP from headers (will be client IP)
27+
const requestHeaders = {
28+
'User-Agent': navigator.userAgent,
29+
'Host': window.location.host,
30+
'Referer': document.referrer,
31+
'Accept-Language': navigator.language,
32+
'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8',
33+
'Sec-Ch-Ua': navigator.userAgent.includes('Chrome') ? '"Not_A Brand";v="8", "Chromium";v="120"' : '',
34+
'Sec-Ch-Ua-Mobile': /Mobile|Android|iPhone|iPad/.test(navigator.userAgent) ? '?1' : '?0',
35+
'Sec-Ch-Ua-Platform': `"${navigator.platform}"`
36+
};
37+
38+
const analyticsData = {
39+
request_path: path,
40+
request_method: method,
41+
request_ip: '127.0.0.1', // Client-side can't get real IP
42+
request_headers: requestHeaders,
43+
request_timestamp: timestamp
44+
};
45+
46+
// Send to Hall Analytics
47+
fetch('https://analytics.usehall.com/visit', {
48+
method: 'POST',
49+
headers: {
50+
'Content-Type': 'application/json',
51+
'Authorization': `Bearer ${HALL_API_KEY}`,
52+
},
53+
body: JSON.stringify(analyticsData),
54+
})
55+
.then(response => {
56+
if (response.ok) {
57+
console.log('[Hall Analytics] Page view tracked:', path);
58+
} else {
59+
console.error('[Hall Analytics] Failed to track:', response.status);
60+
}
61+
})
62+
.catch(error => {
63+
console.error('[Hall Analytics] Network error:', error);
64+
});
65+
}
66+
67+
// Track initial page load
68+
if (document.readyState === 'loading') {
69+
document.addEventListener('DOMContentLoaded', trackPageView);
70+
} else {
71+
trackPageView();
72+
}
73+
74+
// Track navigation (for SPA-like behavior)
75+
let currentPath = window.location.pathname;
76+
const observer = new MutationObserver(() => {
77+
if (window.location.pathname !== currentPath) {
78+
currentPath = window.location.pathname;
79+
setTimeout(trackPageView, 100); // Small delay to ensure new page is loaded
80+
}
81+
});
82+
83+
observer.observe(document.body, {
84+
childList: true,
85+
subtree: true
86+
});
87+
88+
})();
89+
</script>
90+
)}

‎src/middleware.ts

Lines changed: 0 additions & 60 deletions
This file was deleted.

‎src/starlight-overrides/Head.astro

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
import Default from "@astrojs/starlight/components/Head.astro";
33
import type {Props} from "@astrojs/starlight/props";
4+
import HallAnalytics from "../components/HallAnalytics.astro";
45
56
const hasCustomOGImage = Astro.props.entry.data.head.find((t) =>
67
t.attrs.property === "og:image" ? true : false
@@ -45,3 +46,6 @@ const frontmatter = entry.data;
4546
{frontmatter.complexity && (
4647
<meta name="complexity" content={frontmatter.complexity} />
4748
)}
49+
50+
{/* Hall Analytics */}
51+
<HallAnalytics />

0 commit comments

Comments
 (0)