1---2name: datafast3description: Accelerate adoption of DataFast analytics across any stack by codifying the installation, attribution, event, proxy, and API patterns that drive reliable conversion intelligence4---56## When to Use This Skill78- You need to instrument a website (static, SPA, Next.js, Astro, etc.) with DataFast tracking.9- Revenue needs to be attributed to marketing channels (Stripe, LemonSqueezy, Polar, custom providers).10- You want to record custom events/goals reliably despite ad blockers.11- You must proxy the tracker/script for increased data quality or hashed navigation.12- You want to export/import historical analytics or query DataFast APIs.1314## Quickstart (4 steps)15161. **Install the tracking script** inside `<head>`:17 ```html18 <script19 defer20 data-website-id="dfid_XXXX"21 data-domain="example.com"22 src="https://datafa.st/js/script.js"23 ></script>24 ```25 - Customize via `data-allow-localhost`, `data-api-url`, `data-debug`, `data-allowed-hostnames`, `data-disable-console`, `data-allow-file-protocol`.26 - Include the `datafast-queue` snippet to queue calls that happen before the library loads.272. **Connect payment providers** (Stripe, LemonSqueezy, Polar, Shopify, etc.) from the Revenue tab so DataFast auto-tracks revenue.283. **Add custom goals/events** with `window.datafast("my_goal")`, `data-fast-goal` attributes, or the server-side Goals API.294. **Optional proxy** to bypass ad blockers: rewrite `/js/script.js` and `/api/events` to your domain and forward visitor IP with `x-datafast-real-ip`.3031## Installation Reference3233- Scripts load via `<Script />` components in frameworks (Next.js App Router, React, Vue, Astro, etc.) or declaratively in `public/index.html`.34- For hash-based navigation, use the hash-enabled script `https://datafa.st/js/script.hash.js`.35- Use GTM, Shopify, Webflow, Wix, Podia, Kajabi, Ghost, Bubble, Framer, Astro, React Router, Laravel, Django, FastAPI, Flask, Express, PHP, Nginx, Firebase, Rocket, etc., by dropping the same script into the `<head>` or platform-specific head/custom code sections.3637## Revenue Attribution Best Practices3839- After the tracking script is live, go to **Website Settings → Revenue** and add each payment provider.40- Always pass `datafast_visitor_id` (and optionally `datafast_session_id`) when creating checkout sessions:41 - **Stripe Checkout / PaymentIntent**: read the cookies from `cookies()` or `request.cookies` and add them to `metadata`.42 - **LemonSqueezy**: include DataFast cookies under `custom`.43 - **Polar**: add cookies to `metadata`.44 - **Paddle / Dodo Payments / Easytool / Custom**: call the Payments API or trigger a `payment` goal with the customer email.45- For gateways where DataFast already pulls revenue (Shopify, Stripe, LemonSqueezy, Polar), keep the tracking snippet installed but omit redundant manual events.46- Document the metadata mapping and ensure downstream jobs read `datafast_visitor_id` for each financial event.4748## Custom Events & Goals4950### Method 1 – `window.datafast()` (client-side)51- Fire `window?.datafast("goal_name")` on clicks, success pages, or after API responses.52- Record parameters: `window.datafast("checkout", { price: "49", plan: "pro" })`.5354### Method 2 – HTML data attributes55- Add `data-fast-goal="goal_name"` to buttons/links.56- Enrich with `data-fast-goal-*` attributes (`data-fast-goal-price="49"` becomes `{ price: "49" }`).5758### Method 3 – Server-side Goals API59- POST to `https://datafa.st/api/v1/goals` with `datafast_visitor_id`, `name`, and optional `metadata`.60- Authenticate with `Authorization: Bearer YOUR_API_KEY`.61- Ensure the visitor already had at least one pageview (tracked via the script).6263## Funnels, Scrolls, & Filters6465- Use `data-fast-scroll` on critical sections (features, pricing, testimonials) to send scroll goals when 50% of the element is visible.66- Combine scroll goals with funnels (`landing page visit → feature scroll → CTA click`) to spot drop-offs.67- Track UTM/ref/via parameters automatically tracked by DataFast; encourage marketing links to include `?ref=`, `?utm_source=`, `?utm_medium=`, `?utm_campaign=`, `?utm_term=`, and `?utm_content`.68- Use filters to slice by country, device, campaign, URL path, or custom goals; hover charts expose filter shortcuts.69- Provide docs for `datafast_ignore` localStorage to exclude internal traffic.7071## Proxy & Hosting Guidance7273- Proxy requests so the script loads from `/js/script.js` and events post to `/api/events` on your domain.74- Forward the visitor IP with `x-datafast-real-ip` to keep geolocation accurate.75- Next.js rewrites, Express HTTP proxy, Flask/FastAPI routes, PHP scripts, Nginx/Caddy rules, Firebase Functions, and DigitalOcean/Nginx examples are ready-made patterns—adapt whichever matches your stack.76- Allowlist additional domains via `data-allowed-hostnames="app.io,shop.example.com"` and set `data-domain` to the root domain to share cookies across subdomains.77- Use `data-api-url` or `datafast_events` endpoints when custom routing is needed; the tracker auto-detects proxied setups.7879## API & Export/Import8081- DataFast APIs (Overview, Timeseries, Devices, Pages, Countries, Referrers, Campaigns, Goals, Payments, Visitors, Metadata, Realtime) all require `Authorization: Bearer <API_KEY>`.82- Use the **Payments API** to push revenue from unsupported providers: include `amount`, `currency`, `transaction_id`, and the visitor ID.83- Use the **Goals API** for server-side events (max 10 metadata keys).84- Import Plausible exports into DataFast to keep historical data; reference `Import your Plausible data`.85- Export to dashboards via the API Playground, Real-time endpoints, or custom scripts.8687## Mobile & Support8889- Install the DataFast mobile app (iOS/Android) to monitor metrics on the go; connect any site with an API key.90- Use Google Search Console integration for keyword influence; ensure your domain is verified and you have owner/full permissions.91- Track GitHub commits in your dashboard to correlate releases with revenue spikes.92- Reach out to `marc@datafa.st` or `https://feedback.datafa.st/` for help, feature requests, or troubleshooting.9394## Troubleshooting Checklist9596- Script not firing headers? Confirm the tag is inside `<head>` and the `data-website-id` domain matches `data-domain`.97- No revenue? Verify payment provider connection plus metadata cookies in Stripe/LemonSqueezy/Polar sessions.98- Goals not recorded? Ensure goal names use lowercase/underscores/hyphens and do not exceed 64 characters.99- Vercel preview showing no data? Enable `data-allow-localhost="true"` during staging or rely on proxied script in production.100- Proxy showing all visitors from server IP? Add `x-datafast-real-ip` or forward `X-Forwarded-For`.101102## References103104- Script configuration reference: `data-allowed-hostnames`, `data-api-url`, `data-allow-localhost`, `data-disable-console`, `data-debug`.105- Revenue attribution guides (Stripe Checkout, PaymentIntent, Checkout Links, LemonSqueezy, Polar, Paddle, Dodo Payments, Easytool).106- Technology-specific install docs for Shopify, Webflow, Wix, Ghost, Next.js, Astro, Laravel, React Router, Firebase, Astro middleware, Caddy, Nginx, DigitalOcean, etc.
blink-new