{"id":"posthog/posthog-roblox","name":"posthog-roblox","scope":"posthog","platform":"roblox","description":"PostHog analytics SDK for Roblox. Capture events, identify players, evaluate feature flags, and track errors.","version":"0.1.7","latest":"0.1.7","versions":["0.1.5","0.1.6","0.1.7"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"25cadc50fa6c454a79ac6af30531e556b3aaa341ab6dcc165a3cd1514847290e","likes":0,"downloads":0,"install":"forest install posthog/posthog-roblox","url":"https://forest.dev/p/roblox/posthog/posthog-roblox","files":"https://api.forest.dev/ai/package/roblox/posthog/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## Installation\n\nThe SDK must end up at `ReplicatedStorage > PostHog`, where both the server and client code load it\nfrom. There are two ways to install it and **you only need one.** Pick whichever matches how you\nbuild your game:\n\n- **Option A (Wally)** if you manage dependencies with Wally and build with Rojo.\n- **Option B (model file)** if you build directly in Roblox Studio with no external tooling.\n\n### Option A: Wally (Rojo projects)\n\nAdd the dependency to your `wally.toml`:\n\n```toml\n[dependencies]\nPostHog = \"posthog/posthog-roblox@0.1.7\"\n```\n\nRun `wally install`, then map the package into `ReplicatedStorage` in your Rojo project file (for\nexample `default.project.json`) so it replicates to clients:\n\n```json\n\"ReplicatedStorage\": {\n  \"$className\": \"ReplicatedStorage\",\n  \"PostHog\": { \"$path\": \"Packages/PostHog\" }\n}\n```\n\n### Option B: Model file (Roblox Studio, no tooling)\n\nDownload the latest `posthog-roblox.rbxm` from the\n[releases page](https://github.com/PostHog/posthog-roblox/releases). In Studio, right-click\n`ReplicatedStorage` -> **Insert from File**, select the file, and make sure the inserted instance is\nnamed `PostHog`.\n\n## Enable HTTP requests\n\nWhichever option you picked above, the SDK sends events over HTTP, which only the Roblox server can\ndo, and only once you allow it: **Game Settings -> Security -> Allow HTTP Requests -> On**.\n\n## Quick start\n\nWith `ReplicatedStorage > PostHog` in place and HTTP enabled, initialize on the server and start\ncapturing. Lifecycle events like `server_started` and `player_joined` are captured automatically, so\nyou have data the moment you press **Play**.\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\nNew to the SDK? The **[getting started guide](docs/getting-started.md)** walks through the whole\nflow end to end: installing, initializing, verifying your first events in PostHog, and adding\nidentity and feature flags.\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 `rokit install`,\nrun the test suite with `lune run tests/runTests.luau`. See **[DEVELOPMENT.md](DEVELOPMENT.md)** for\nthe full guide: toolchain, tests and the coverage gate, linting and formatting, building the model\nfile, and running the example in Roblox Studio.\n\nReleases are automated on tag push; see [RELEASING.md](RELEASING.md).\n\n## License\n\n[MIT](LICENSE)\n","readmeTruncated":false}