Takt Laravel Laravel Package

Getting Started

This package is a thin Laravel wrapper around vskstudio/takt-core-php; all the real tracking logic lives in the core library, so most "why did this break?" questions are answered by the core's changelog, not this repo's.

1. composer require vskstudio/takt (v0.7.1 pulls vskstudio/takt-core-php 0.7.3 or later).
2. Publish the config (config/takt.php) and set your credentials in .env:
   • TAKT_API_KEY — the key that gets sent to the ingest endpoint.
   • TAKT_ENDPOINT — must be https://…, including in local dev and Sail/Herd setups.
   • TAKT_ROUTE_TEMPLATES (config key route_templates) — optional map for template-mode URL normalisation.
3. Drop the @takt directive into your layout <head>, before your app JS, so the browser tracker is registered once per page.
4. First use case: pageview tracking in the root Blade layout, then a single server-side event from a controller via the Takt service (Takt::event('Signup', [...])) to confirm key + endpoint wiring end-to-end.

Where to look first when something is off: composer show vskstudio/takt-core-php (confirm you are on ≥ 0.7.3), then the rendered @takt output in view-source: — that inline bundle is where both of the 0.7.x regressions lived.

Implementation Patterns

Client-side first, server-side for trusted events. Use the @takt directive for pageviews and UI interactions (it captures the URL and referrer for you), and reserve the Takt service for events that must not be spoofable — signups, subscription changes, webhook-triggered conversions.

Upgrade discipline for the core bump. v0.7.1 is a patch release, but it carries a transitive minor bump (takt-core-php 0.7.3). Add vskstudio/takt-core-php to your composer.json constraints (or at least pin the lockfile) so a future composer update in CI cannot silently move you across core's 0.7 behaviour changes:

composer update vskstudio/takt-core-php --with-dependencies
php artisan view:clear   # the inline snippet is compiled into Blade views

Template mode as your default for multi-tenant apps. With route_templates enabled, dynamic segments collapse to route patterns and unresolvable URLs are masked as /[redacted]. That is what you want for any app with IDs, slugs, or user-generated paths in the URL — pair it with redact_routes for admin/account areas so those prefixes never leave the app:

// config/takt.php
'route_templates' => true,
'redact_routes'   => ['admin/*', 'account/*', 'invite/*'],

Server-side events should mirror the client shape. Keep event names and property keys identical between @takt calls and Takt::event() calls so reports join cleanly; the package does not normalise names for you.

Local dev without a real endpoint. Because http:// and scheme-less //host endpoints now throw, don't stub TAKT_ENDPOINT=http://localhost:8080. Either point at a TLS terminator/ngrok URL or leave the directive disabled in local via a config/env gate and let Takt::event() no-op in tests.

Testing. Bind a fake/spy around the Takt service in your test suite rather than hitting the network, and add one feature test asserting your layout renders the @takt snippet exactly once — that guards against double inclusion when a layout is nested.

Gotchas and Tips

• window.takt being clobbered. The v0.7.1 fix addresses the inline bundle starting with var takt=(function(exports){...})({}), which reassigned the global and made takt('Event') throw. If you have a local copy of the snippet, or a CSP-compatible vendored build, you must apply the same fix yourself — the package only fixes the rendered bundle. Check for window.takt existing before your own calls if you still see takt is not a function.
• Empty URL → 400 from ingest. Since core 0.6.1 every event after the first pageview was being sent with an empty URL and rejected with a 400. If your dashboards show a sharp drop in events after the first pageview on a page, verify the core version before you debug your own code.
• http:// endpoints now throw. A trailing-slash or env-parsing mistake that yields http://… or //host produces an InvalidArgumentException from both the directive and the Takt service. This is deliberate — it prevents the API key leaking in clear — but it surfaces at render/request time, so a stale .env in a deploy can take a page down. Validate the scheme in a config test.
• Referrer is origin-only in template mode. Don't build attribution reporting that depends on full referrer paths while route_templates is on, and expect non-http(s) referrers (native apps, android-app://, local file opens) to be dropped entirely.
• Redacted routes are silent. An unresolvable page URL becomes /[redacted] (or your redact_routes pattern). Analytics for those pages will look like one giant bucket — intentional, but confusing if you didn't realise you enabled template mode.
• Compiled views cache the snippet. After upgrading, run php artisan view:clear (and your OPcache/FPM reload in production); otherwise you can still be serving the broken global-reassigning bundle and conclude the patch didn't work.
• Single responsibility boundary. Anything about the wire format, endpoint validation, or redaction is core behaviour; file issues against takt-core-php. This package mostly owns the Blade directive, the container binding, and config plumbing — that is your extension point if you need custom snippet wrapping.
• Pin the core in CI. A regression test in this package fails if the bundle reassigns the global — mirror that with your own smoke test asserting window.takt is a function after load, so a future core bump can't silently regress your instrumentation.