{"id":"charlesvien/posthog-roblox","name":"posthog-roblox","scope":"charlesvien","platform":"roblox","description":"PostHog analytics SDK for Roblox. Capture events, identify players, evaluate feature flags, and track errors.","version":"0.1.0","latest":"0.1.0","versions":["0.1.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"ba46269f068c76242535da77a4ab034cc01651cb31aa1df8adac849d80b2aec3","likes":0,"downloads":0,"install":"forest install charlesvien/posthog-roblox","url":"https://forest.dev/p/roblox/charlesvien/posthog-roblox","files":"https://api.forest.dev/ai/package/roblox/charlesvien/posthog-roblox/files","readme":"# 🦔 PostHog Roblox SDK (BETA)\n\nThe [PostHog](https://posthog.com) analytics SDK for Roblox. Capture events, identify players,\nevaluate feature flags, and track errors from your Roblox experiences.\n\n- **Server-authoritative.** All HTTP and batching happen on the server (the only place Roblox\n  allows outbound requests). A thin client module relays calls to the server.\n- **Per-player.** Each player is a PostHog user, keyed by their `UserId`.\n- **Batteries included.** Events, identity, groups, feature flags, error tracking, and lifecycle\n  autocapture that records meaningful session metrics out of the box, so you can chart real player\n  behavior before writing a single manual event.\n\n> **Note:** This SDK is in **beta**. It's ready to try, but the API may still change before a\n> stable release. If you hit a bug or have feedback, please\n> [open an issue](https://github.com/PostHog/posthog-roblox/issues). We'd love to hear from you.\n\n## Requirements\n\n- HTTP requests enabled for your experience (Game Settings → Security → **Allow HTTP Requests**).\n- A PostHog project API key (starts with `phc_`).\n\n## Quick look\n\nThe [getting started guide](docs/getting-started.md) is the place to begin: it covers installation\n(Wally or a model file), enabling HTTP, and verifying your first events in PostHog. Once\n`ReplicatedStorage > PostHog` is in place, an integration looks like this.\n\nServer (a `Script` in `ServerScriptService`):\n\n```lua\nlocal Players = game:GetService(\"Players\")\nlocal PostHog = require(game.ReplicatedStorage:WaitForChild(\"PostHog\"))\n\nPostHog:Init({ apiKey = \"phc_YOUR_PROJECT_API_KEY\" })\n\nPlayers.PlayerAdded:Connect(function(player)\n    PostHog:Capture(player, \"hello_world\") -- attributed to a player\nend)\n```\n\nClient (a `LocalScript`):\n\n```lua\nlocal PostHog = require(game.ReplicatedStorage:WaitForChild(\"PostHog\"))\n\nPostHog:Capture(\"button_clicked\", { button = \"play\" }) -- relayed to the server\n```\n\n## Documentation\n\n| Guide | What it covers |\n| ----- | -------------- |\n| [Getting started](docs/getting-started.md) | **Start here.** Install, initialize, and see your first events in PostHog. |\n| [Capturing events](docs/capturing-events.md) | `Capture` and `Screen`, server subjects, the client relay, event properties, super properties, opt-out. |\n| [Autocapture](docs/autocapture.md) | Events and context captured automatically, and how to build a dashboard with zero manual events. |\n| [Identifying users and groups](docs/identify-and-groups.md) | `Identify`, person properties, `Alias`, person profiles, and `Group` analytics. |\n| [Feature flags](docs/feature-flags.md) | Boolean and multivariate flags, payloads, reloading, and targeting. |\n| [Error tracking](docs/error-tracking.md) | Automatic and manual exception capture on the server and client. |\n| [Sessions and teleports](docs/sessions.md) | How sessions work and how to continue them across teleports. |\n| [Configuration](docs/configuration.md) | Every `Init` option explained. |\n| [API reference](docs/api-reference.md) | The complete server and client API. |\n\n## Architecture\n\n```\nClient (LocalScript)                 Server (Script)\n  PostHog:Capture(name, props)          PostHog:Init(config)\n  PostHog:Screen(name)          --->    autocapture, identity, feature flags\n  unhandled errors          RemoteEvent  event queue + HTTP  (/batch, /flags)\n        |                      relay      game:BindToClose (final flush)\n        '------ FireServer ----------------->\n```\n\nThe server owns the event queue, identity, feature flags, error tracking, and all HTTP. The client\nnever holds the API key and is treated as untrusted: relayed messages are validated, rate-limited,\nand always attributed to the firing player. See\n[Capturing events](docs/capturing-events.md#client) for the relay's security model.\n\n## Development\n\nThis repo uses [Rokit](https://github.com/rojo-rbx/rokit) to manage tooling. After\n`rokit install`:\n\n```sh\n# Run the unit test suite (pure-logic modules) with a 100% function-coverage gate.\nlune run tests/runTests.luau\n\n# Lint and format.\nselene src tests\nstylua src tests ExampleProject\n\n# Serve to Roblox Studio.\nrojo serve\n```\n\nThe [`ExampleProject`](ExampleProject) directory is a runnable demo that maps the SDK from `../src`.\nOpen it with `rojo serve`, connect from Studio, set your API key in `PostHogDemo.server.luau`, and\npress Play to see autocaptured and demo events appear in your PostHog project.\n\nReleases are automated on tag push; see [RELEASING.md](RELEASING.md).\n\n## License\n\n[MIT](LICENSE)\n","readmeTruncated":false}