🦔 PostHog Roblox SDK (BETA)

The PostHog analytics SDK for Roblox. Capture events, identify players, evaluate feature flags, and track errors from your Roblox experiences.

• Server-authoritative. All HTTP and batching happen on the server (the only place Roblox allows outbound requests). A thin client module relays calls to the server.
• Per-player. Each player is a PostHog user, keyed by their UserId.
• Batteries included. Events, identity, groups, feature flags, error tracking, and lifecycle autocapture that records meaningful session metrics out of the box, so you can chart real player behavior before writing a single manual event.

Note: This SDK is in beta. It's ready to try, but the API may still change before a stable release. If you hit a bug or have feedback, please open an issue. We'd love to hear from you.

Requirements

• HTTP requests enabled for your experience (Game Settings → Security → Allow HTTP Requests).
• A PostHog project API key (starts with phc_).

Quick look

The getting started guide is the place to begin: it covers installation (Wally or a model file), enabling HTTP, and verifying your first events in PostHog. Once ReplicatedStorage > PostHog is in place, an integration looks like this.

Server (a Script in ServerScriptService):

local Players = game:GetService("Players")
local PostHog = require(game.ReplicatedStorage:WaitForChild("PostHog"))

PostHog:Init({ apiKey = "phc_YOUR_PROJECT_API_KEY" })

Players.PlayerAdded:Connect(function(player)
    PostHog:Capture(player, "hello_world") -- attributed to a player
end)

Client (a LocalScript):

local PostHog = require(game.ReplicatedStorage:WaitForChild("PostHog"))

PostHog:Capture("button_clicked", { button = "play" }) -- relayed to the server

Documentation

Architecture

Client (LocalScript)                 Server (Script)
  PostHog:Capture(name, props)          PostHog:Init(config)
  PostHog:Screen(name)          --->    autocapture, identity, feature flags
  unhandled errors          RemoteEvent  event queue + HTTP  (/batch, /flags)
        |                      relay      game:BindToClose (final flush)
        '------ FireServer ----------------->

The server owns the event queue, identity, feature flags, error tracking, and all HTTP. The client never holds the API key and is treated as untrusted: relayed messages are validated, rate-limited, and always attributed to the firing player. See Capturing events for the relay's security model.

Development

This repo uses Rokit to manage tooling. After rokit install:

# Run the unit test suite (pure-logic modules) with a 100% function-coverage gate.
lune run tests/runTests.luau

# Lint and format.
selene src tests
stylua src tests ExampleProject

# Serve to Roblox Studio.
rojo serve

The ExampleProject directory is a runnable demo that maps the SDK from ../src. Open it with rojo serve, connect from Studio, set your API key in PostHogDemo.server.luau, and press Play to see autocaptured and demo events appear in your PostHog project.

Releases are automated on tag push; see RELEASING.md.

License

MIT