API reference

Every function of the Roblox module: players, events, properties, purchases, credits, creator codes and staff notices.

Updated September 15, 20261 min read

All examples assume analyse is the value returned by Analyse.new (see Install the module).

Players

Most functions take a player reference, not a Roblox Player. Make one with Analyse.player:

Luau

local who = Analyse.player(player) -- { id = tostring(player.UserId), kind = "platform" }

Custom events

Luau

analyse:track("quest_completed", Analyse.player(player), {
	quest = "dragon",
	reward = 250,
	hard_mode = true,
})

analyse:track(name, player?, props?). The player is optional for server-wide events. Property values can be strings, numbers or booleans. Names starting with $ are reserved.

Robux purchases

Record developer product and game pass purchases, typically from ProcessReceipt:

Luau

local MarketplaceService = game:GetService("MarketplaceService")
local Players = game:GetService("Players")

MarketplaceService.ProcessReceipt = function(receipt)
	local player = Players:GetPlayerByUserId(receipt.PlayerId)
	if player then
		analyse:purchase(Analyse.player(player), receipt.CurrencySpent, "ROBUX", {
			purchaseId = receipt.PurchaseId,
			itemId = tostring(receipt.ProductId),
			itemName = "Starter Pack", -- optional
			quantity = 1, -- optional
		})
	end
	-- grant the product, then:
	return Enum.ProductPurchaseDecision.PurchaseGranted
end

analyse:purchase(player, amount, currency, details). details.purchaseId is required; pass the receipt's id so a retried receipt is not counted twice.

In-game credits

Track a virtual currency being spent or earned, per item:

Luau

analyse:creditSpend(Analyse.player(player), "kit_miner", 250)
analyse:creditEarn(Analyse.player(player), "daily_reward", 100)

Group items into categories so the revenue page can show where credits go:

Luau

analyse:syncCategories({
	{ id = "kits", name = "Kits", order = 1, items = { "kit_miner", "kit_archer" } },
	{ id = "cosmetics", name = "Cosmetics", order = 2 },
})

Send the whole list on startup and whenever it changes: the list is authoritative, so a category you stop sending is switched off (not deleted) and comes back when you list it again. syncCategories yields and returns true when the list was accepted.

Creator codes

When a player enters a creator code in your UI:

Luau

analyse:creatorCode(Analyse.player(player), "stevebuilds")

The rest of their session is attributed to that code. Codes are matched to campaigns without regard to case.

Joins and leaves by hand

Only needed when you start with autoTrackPlayers = false:

Luau

analyse:join(Analyse.player(player), Analyse.joinSignals(player))
analyse:leave(Analyse.player(player), "quit") -- "quit" | "kick" | "ban" | "timeout" | "transfer"

Analyse.joinSignals(player) collects the name, country and join data. With autoHeartbeat = false, call analyse:heartbeat(#Players:GetPlayers()) yourself.

Staff notices

Receive dashboard alerts in game when In-game staff message is on under Settings, Alerts & digests:

Luau

analyse:onNotice(function(notice)
	-- notice.id, notice.title, notice.detail, notice.urgent, notice.createdAt, notice.url
	print("[Analyse]", notice.title, notice.detail)
end, 60) -- check every 60 seconds (minimum 15)

It is up to you who sees them, for example only group staff.

Experiments

If you run experiments from the dashboard:

Luau

local variant = analyse:variant(Analyse.player(player), experimentId) -- "control", "b", or nil
local config = analyse:variantConfig(Analyse.player(player), experimentId) -- the variant's settings table
analyse:assign(Analyse.player(player), experimentId, "b") -- force a variant

Lifecycle

Function	What it does
`analyse:flush()`	Send everything queued now
`analyse:refresh()`	Re-check the key and fetch the latest config
`analyse:stats()`	Delivery counters: `enqueued`, `sent`, `dropped`, `retried`, `lastStatus`, `queueDepth`
`analyse:close()`	Leave everyone, send shutdown and flush. Runs on `BindToClose` automatically