docs: add Roblox SDK (#17343)

Author: charlesvien

contents/docs/error-tracking/installation/roblox.mdx

@@ -0,0 +1,112 @@
+---
+title: Roblox error tracking installation
+platformLogo: roblox
+showStepsToc: true
+---
+
+import { Steps, Step } from 'components/Docs/Steps'
+import { CalloutBox } from 'components/Docs/CalloutBox'
+
+<Steps>
+
+<Step title="Install the Roblox SDK" badge="required">
+
+PostHog is available for Roblox through [Wally](https://wally.run) or as a model file you import in Studio.
+
+Via Wally, add the dependency to your `wally.toml`, run `wally install`, and map the package into `ReplicatedStorage`:
+
+```toml
+[dependencies]
+PostHog = "posthog/posthog-roblox@0.1.0"
+```
+
+You can also download the latest `posthog-roblox.rbxm` from the [releases page](https://github.com/PostHog/posthog-roblox/releases) and insert it into `ReplicatedStorage` in Studio. Either way you should end up with `ReplicatedStorage > PostHog`.
+
+Make sure HTTP requests are enabled for your experience: **Game Settings > Security > Allow HTTP Requests**.
+
+</Step>
+
+<Step title="Configure PostHog" badge="required">
+
+Initialize PostHog once from a server `Script` (for example in `ServerScriptService`), keeping error capture enabled:
+
+```lua
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local PostHog = require(ReplicatedStorage:WaitForChild("PostHog"))
+
+PostHog:Init({
+    apiKey = "<ph_project_token>",
+    host = "<ph_client_api_host>",
+    captureErrors = true,
+    errorDebounceSeconds = 1,
+})
+```
+
+You can find your project token and instance address in the [project settings](https://app.posthog.com/project/settings) page in PostHog.
+
+</Step>
+
+<Step title="Capture exceptions" badge="required">
+
+The Roblox SDK captures exceptions automatically by default. On the server it listens to `ScriptContext.Error`; requiring the module from a `LocalScript` captures unhandled client errors and relays them to the server.
+
+Captured events include the error message, the stack trace when available, and SDK metadata.
+
+For handled errors, call `CaptureException` manually with a subject, message, and optional trace and properties:
+
+```lua
+local ok, err = pcall(function()
+    saveGame(player)
+end)
+
+if not ok then
+    PostHog:CaptureException(player, err, debug.traceback(), {
+        flow = "save_game",
+    })
+end
+```
+
+<CalloutBox icon="IconInfo" title="Identified users" type="fyi">
+
+Server events are already attributed to the player you pass as the subject (by their `UserId`), so exceptions are linked to known users in PostHog automatically.
+
+</CalloutBox>
+
+</Step>
+
+<Step title="Configure error tracking options" badge="optional">
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `captureErrors` | boolean | `true` | Enables automatic exception capture. |
+| `errorDebounceSeconds` | number | `1` | Minimum seconds between automatic server error captures. |
+
+To disable automatic exception capture:
+
+```lua
+PostHog:Init({
+    apiKey = "<ph_project_token>",
+    captureErrors = false,
+})
+```
+
+</Step>
+
+<Step checkpoint title="Verify error tracking" badge="recommended">
+
+Trigger a test exception and confirm it appears in the [Error tracking](https://app.posthog.com/error_tracking) tab.
+
+```lua
+PostHog:CaptureException(nil, "Test exception from Roblox", debug.traceback())
+PostHog:Flush()
+```
+
+To test automatic capture, raise an unhandled error from a server `Script`:
+
+```lua
+error("Automatic test exception from Roblox")
+```
+
+</Step>
+
+</Steps>

contents/docs/error-tracking/references.mdx

@@ -13,6 +13,7 @@ If you're looking for detailed reference documentation for the PostHog SDKs and
 - [Python SDK](/docs/references/posthog-python?filter=error-tracking)
 - [.NET SDK](/docs/libraries/dotnet#error-tracking)
 - [Unity SDK](/docs/libraries/unity#error-tracking)
+- [Roblox SDK](/docs/libraries/roblox#error-tracking)
 
 ## API references
 

contents/docs/getting-started/_snippets/install.mdx

@@ -11,7 +11,7 @@ import { WebsiteJSHtmlSnippet } from '../../product-analytics/installation/_snip
     <Tab.List>  
         <Tab>AI wizard</Tab>
         <Tab>JS snippet</Tab>
-        <Tab count="15">Libraries</Tab>
+        <Tab count="16">Libraries</Tab>
         <Tab count="22">Framework guides</Tab>
         <Tab>API</Tab>
     </Tab.List>

contents/docs/integrate/_snippets/install-roblox.mdx

@@ -0,0 +1,88 @@
+PostHog is available for Roblox through [Wally](https://wally.run) (the Roblox package manager), or as a model file you import in Studio. The SDK is server-authoritative: the server owns all batching and HTTP, and each player is a PostHog user keyed by their Roblox `UserId`.
+
+### Requirements
+
+- HTTP requests enabled for your experience: **Game Settings > Security > Allow HTTP Requests**. Only the Roblox server can make outbound HTTP requests, and only when this is on.
+- A PostHog project API key (starts with `phc_`).
+
+### Via Wally (recommended)
+
+Add the dependency to your `wally.toml`:
+
+```toml
+[dependencies]
+PostHog = "posthog/posthog-roblox@0.1.0"
+```
+
+Run `wally install`, then map the installed package into `ReplicatedStorage` in your [Rojo](https://rojo.space) project file so it replicates to clients:
+
+```json
+"ReplicatedStorage": {
+  "$className": "ReplicatedStorage",
+  "PostHog": { "$path": "Packages/PostHog" }
+}
+```
+
+### Via model file
+
+Download the latest `posthog-roblox.rbxm` from the [releases page](https://github.com/PostHog/posthog-roblox/releases). In Studio, right-click `ReplicatedStorage`, choose **Insert from File**, and select the file. Make sure the inserted instance is named `PostHog`.
+
+Either way, you should end up with `ReplicatedStorage > PostHog`, which both server and client code require.
+
+### Initialize on the server
+
+Initialize PostHog once from a server `Script` (for example in `ServerScriptService`):
+
+```lua
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local PostHog = require(ReplicatedStorage:WaitForChild("PostHog"))
+
+PostHog:Init({
+    apiKey = "<ph_project_token>",
+    host = "<ph_client_api_host>", -- usually https://us.i.posthog.com or https://eu.i.posthog.com
+})
+```
+
+> **Note:** `Init` must run on the server. Calling it from a `LocalScript` is ignored. Requiring the same module from a `LocalScript` gives you a thin client relay instead (see [Capturing events](#capturing-events)).
+
+### Configuration options
+
+Pass any of these to `PostHog:Init`. Only `apiKey` is required; everything else has a sensible default.
+
+```lua
+PostHog:Init({
+    -- Required
+    apiKey = "<ph_project_token>",
+
+    -- Connection
+    host = "https://us.i.posthog.com",
+
+    -- Event queue
+    flushAt = 20,                  -- Flush once this many events are queued (default: 20)
+    flushIntervalSeconds = 30,     -- Flush at least this often (default: 30)
+    maxQueueSize = 1000,           -- Drop the oldest events past this size (default: 1000)
+    maxBatchSize = 50,             -- Maximum events per HTTP request (default: 50)
+
+    -- Feature flags
+    preloadFeatureFlags = true,    -- Fetch a player's flags when they join (default: true)
+    sendFeatureFlagEvents = true,  -- Emit $feature_flag_called when a flag is read (default: true)
+    sendDefaultPersonPropertiesForFlags = true,
+
+    -- Autocapture and error tracking
+    captureLifecycleEvents = true, -- player_joined/left/idle, server_started/shutdown (default: true)
+    captureErrors = true,          -- Capture unhandled errors as $exception events (default: true)
+    errorDebounceSeconds = 1,      -- Minimum gap between auto-captured server errors (default: 1)
+
+    -- Identity
+    personProfiles = "identified_only", -- "identified_only" | "always" | "never"
+    serverDistinctId = "server",        -- distinct_id used for server-scoped (nil subject) events
+
+    -- Client relay
+    enableClientRelay = true,        -- Create the RemoteEvent that lets clients relay events (default: true)
+    clientRateLimitPerSecond = 20,   -- Per-player rate limit for relayed messages (default: 20)
+    maxClientPropertyCount = 100,    -- Maximum properties accepted from one client message (default: 100)
+
+    -- Diagnostics
+    logLevel = "warn",               -- "debug" | "info" | "warn" | "error" | "none"
+})
+```

contents/docs/integrate/feature-flags-code/_snippets/feature-flags-code-roblox.mdx

@@ -0,0 +1,78 @@
+Feature flags in the Roblox SDK are evaluated **per player**, so each flag call takes the player (or another subject) as its first argument. When `preloadFeatureFlags` is enabled (the default), a player's flags are fetched automatically when they join, so they're ready to read for the rest of the session.
+
+### Boolean feature flags
+
+```lua
+if PostHog:IsFeatureEnabled(player, "flag-key") then
+    -- Do something differently for this player
+end
+```
+
+`IsFeatureEnabled` accepts an optional default that's returned when the flag hasn't loaded yet:
+
+```lua
+if PostHog:IsFeatureEnabled(player, "flag-key", false) then
+    -- ...
+end
+```
+
+### Multivariate feature flags
+
+`GetFeatureFlag` returns a table with the flag's `value`, `isEnabled`, `variant`, and `payload`:
+
+```lua
+local flag = PostHog:GetFeatureFlag(player, "flag-key")
+if flag.isEnabled then
+    if flag.variant == "variant-key" then -- Replace with your variant key
+        -- Do something for this variant
+    end
+end
+```
+
+### Feature flag payloads
+
+Read the JSON payload attached to a flag with `GetFeatureFlagPayload`:
+
+```lua
+local payload = PostHog:GetFeatureFlagPayload(player, "shop-config")
+if payload then
+    print(payload.theme, payload.maxItems)
+end
+```
+
+The payload is also available on the flag object returned by `GetFeatureFlag`:
+
+```lua
+local flag = PostHog:GetFeatureFlag(player, "shop-config")
+local theme = flag.payload and flag.payload.theme
+```
+
+### Ensuring flags are loaded before use
+
+When a player joins, the SDK fetches their flags in the background (unless you set `preloadFeatureFlags = false`). For most of a session the flags are available immediately, but the very first read right after a player joins can race the network request.
+
+To force a fresh fetch and wait for it, call `ReloadFeatureFlags`. It **yields** until the request completes and returns whether it succeeded:
+
+```lua
+local ok = PostHog:ReloadFeatureFlags(player)
+if ok then
+    local enabled = PostHog:IsFeatureEnabled(player, "flag-key")
+end
+```
+
+### Overriding properties for flag evaluation
+
+Set the person or group properties used to evaluate a player's flags. By default this reloads their flags; pass `false` as the final argument to skip the reload:
+
+```lua
+-- Person properties for targeting
+PostHog:SetPersonPropertiesForFlags(player, {
+    level = 12,
+    is_vip = true,
+})
+
+-- Group properties for targeting
+PostHog:SetGroupPropertiesForFlags(player, "guild", {
+    member_count = 42,
+})
+```

contents/docs/integrate/send-events/_snippets/send-events-roblox.mdx

@@ -0,0 +1,63 @@
+import SettingProperties from "./setting-properties-text.mdx"
+import Intro from "./intro.mdx"
+
+<Intro />
+
+On the server, every capture call takes a **subject** as its first argument so you can attribute the event to a specific player. Pass a `Player` and it resolves to their `UserId`:
+
+```lua
+local Players = game:GetService("Players")
+
+Players.PlayerAdded:Connect(function(player)
+    PostHog:Capture(player, "game_joined")
+end)
+```
+
+> **Tip:** We recommend naming events in an `[object] [verb]` format, where `[object]` is the entity the behavior relates to, and `[verb]` is the behavior itself. For example, `level completed`, `item purchased`, or `quest started`.
+
+The subject can be a `Player`, a numeric `UserId`, a string distinct ID, or `nil` for a server-scoped event that isn't attributed to any player:
+
+```lua
+PostHog:Capture(player, "level_completed")  -- a Player
+PostHog:Capture(123456, "level_completed")  -- a UserId
+PostHog:Capture(nil, "shop_restocked")      -- server-scoped, no person profile
+```
+
+<SettingProperties />
+
+```lua
+PostHog:Capture(player, "level_completed", {
+    level = 5,
+    duration_seconds = 92,
+    used_powerup = true,
+})
+```
+
+### Capturing from the client
+
+The same `PostHog` module works in a `LocalScript`, where it acts as a thin relay: calls are sent to the server over a `RemoteEvent` and attributed to the firing player. There's no API key on the client, and no subject argument:
+
+```lua
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local PostHog = require(ReplicatedStorage:WaitForChild("PostHog"))
+
+PostHog:Capture("button_clicked", { button = "play" })
+```
+
+The server validates, rate-limits, and attributes every relayed event, so a client can't spoof another player or send reserved (`$`-prefixed) event names.
+
+### Capturing screen views
+
+Track which screens or menus a player views:
+
+```lua
+PostHog:Screen(player, "Main Menu")
+
+-- With additional properties
+PostHog:Screen(player, "Level Select", {
+    unlocked_levels = 5,
+})
+
+-- From a LocalScript (relayed, no subject)
+PostHog:Screen("Shop")
+```