@typetorch/framework 0.6.2 → 0.6.3

package/README.md

@@ -490,7 +490,7 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   economy are server-authoritative): on the client they warn once and send nothing, and the server refuses them from
   clients.
 - **Options** (all on by default): `sessions` (joins, leaves, device, join source, account age bucket, Premium,
-  country, friends in the server, first-ever vs returning, days since the last visit), `tech` (FPS, ping, memory, load
+  country, the player policy, device trust, friends in the server, first-ever vs returning, days since the last visit), `tech` (FPS, ping, memory, load
   time, client and server errors, swaps and rollbacks, leaves within 60 s of a swap), `zones` (parts or models tagged
   `TTZone`, named by a `Name` attribute or the instance name), `screens` (ScreenGuis in PlayerGui, GuiObjects tagged
   `TTScreen`), `recording` (the first-ever session in detail), `fleet` (kernel 0.3.2 heartbeats and deploy reports),

package/out/analytics/SCHEMA.md

@@ -57,12 +57,12 @@ First-ever-session detail, one row per packed chunk.
 
 | kind | name | props |
 |---|---|---|
-| session | `join` | `from`: `direct` (Home, search, sorts: Roblox doesn't say), `teleport` (same game), `teleport_game` (another game), `referral` (invite/referral link), `notification` (a TypeTorch notification's launch data verified), `share` (other launch data), `follow` (followed someone); join metadata (plans/29): `src_place?`, `src_game?` (SourcePlaceId / SourceGameId), `ref?` / `follow?` (the referrer / followed user as their pid when this game knows them, else `"other"`: never a UserId; players in the server are free, others cost one DataStore read each, at most 2 per join and only with read budget to spare), `party?` (players teleported along) + `party_pids?` (the pids of those this game knows, at most 10), `ctx?`, `ctx_item?`, `ctx_asset?`, `ctx_outfit?`, `ctx_asset_type?` (GameJoinContext JoinSource / ItemType / AssetId / OutfitId / AssetType), `launch?` (`notification` + `nid`, `nk` (kind); `tt_bad` + `launch_bad` (`format`, `sig`, `user`, `old`); or the game's own launch data: `launch_len`, plus its first 32 chars in `launch` only with the settings' `joinLaunchPrefix`), `tp?` + `tp_bytes?` (TeleportData present, its JSON size; never the content), `age_days` (exact account age), `locale?`, `verified?` (HasVerifiedBadge), `membership` (MembershipType name); `age` (account age: `<1d`, `1-7d`, `7-30d`, `30-90d`, `90-365d`, `1-3y`, `3y+`); `prem` (Premium); `country?` (ISO code); `friends` (how many of the player's friends are in the server: one friend-list lookup per join, at most 10 pages, `0` when it fails); `ret` (days since the last visit, `-1` first visit or unknown); `late?` (the engine started over 60 s after the join); `jd?` (plans/30, with the settings' `joinData` `"full"`, the default: the raw join data, below). With `joinData` `"off"` only `from`, `ctx`, `tp`, `party`, `age`, `prem`, `country`, `friends`, `ret`, `late` are written. `t` is the join time |
+| session | `join` | `from`: `direct` (Home, search, sorts: Roblox doesn't say), `teleport` (same game), `teleport_game` (another game), `referral` (invite/referral link), `notification` (a TypeTorch notification's launch data verified), `share` (other launch data), `follow` (followed someone); join metadata (plans/29): `src_place?`, `src_game?` (SourcePlaceId / SourceGameId), `ref?` / `follow?` (the referrer / followed user as their pid when this game knows them, else `"other"`: never a UserId; players in the server are free, others cost one DataStore read each, at most 2 per join and only with read budget to spare), `party?` (players teleported along) + `party_pids?` (the pids of those this game knows, at most 10), `ctx?`, `ctx_item?`, `ctx_asset?`, `ctx_outfit?`, `ctx_asset_type?` (GameJoinContext JoinSource / ItemType / AssetId / OutfitId / AssetType), `launch?` (`notification` + `nid`, `nk` (kind); `tt_bad` + `launch_bad` (`format`, `sig`, `user`, `old`); or the game's own launch data: `launch_len`, plus its first 32 chars in `launch` only with the settings' `joinLaunchPrefix`), `tp?` + `tp_bytes?` (TeleportData present, its JSON size; never the content), `age_days` (exact account age), `locale?`, `verified?` (HasVerifiedBadge), `membership` (MembershipType name); `age` (account age: `<1d`, `1-7d`, `7-30d`, `30-90d`, `90-365d`, `1-3y`, `3y+`); `prem` (Premium); `country?` (ISO code); `pol` (the player policy, PolicyService:GetPolicyInfoForPlayerAsync with a 5 s deadline: `ok`, `failed`, `timeout`) and with `ok` `pol_ads`, `pol_rand` (ArePaidRandomItemsRestricted), `pol_trade` (IsPaidItemTradingAllowed), `pol_share` (IsContentSharingAllowed), `pol_subs` (IsEligibleToPurchaseSubscription), `pol_cn` (IsSubjectToChinaPolicies), `pol_links` (AllowedExternalLinkReferences, comma separated); `trust?` (Player.DeviceTrustLevel at the join, usually `Pending`: the leave row has the settled level); `friends` (how many of the player's friends are in the server: one friend-list lookup per join, at most 10 pages, `0` when it fails); `ret` (days since the last visit, `-1` first visit or unknown); `late?` (the engine started over 60 s after the join); `jd?` (plans/30, with the settings' `joinData` `"full"`, the default: the raw join data, below). With `joinData` `"off"` only `from`, `ctx`, `tp`, `party`, `age`, `prem`, `country`, `friends`, `ret`, `late` are written. `t` is the join time |
 | session | `device` (src client) | `dev?` (the device class, as the `dev` column; frameworks after 0.4.2, older ones leave it out), `input` (`kbm`, `touch`, `gamepad`, `vr`, `unknown`), `w`, `h` (viewport points), `touch`, `kb`, `mouse`, `pad`, `vr`. Once per session. The class (Roblox gives game scripts no OS): `vr` when VRService.VREnabled; `console` when GuiService:IsTenFootInterface(); touch without a keyboard: `tablet` when the viewport's short side is 600 points or more, else `phone` (the first hello waits up to 2 s for a real viewport); a keyboard or mouse: `desktop` (touch laptops, tablets with a keyboard); else `unknown` |
 | notify | `want`, `drop` | Notifications (plans/29), written by the game server: `k` (kind), `key?` (first 12 hex of SHA-256 of the intent's key; never the key), `at?`, `until?`, `offline` (want: the user isn't in this server; the row then has no pid), `why?` (drop) |
 | notify | `optin_check`, `optin_shown`, `optin_closed` | The client's opt-in prompt, checked and written by the server (at most 3 of each per session): `where`, `can` (check), `err?` (`timeout`, `swap` or the error's first 64 chars), `secs` (closed: how long it was up) |
 | notify | `open`, `open_bad`, `played` | A join from a notification: `open` (`nid`, `k`, `age` (secs since sent), `first`), `open_bad` (`why`: `format`, `sig`, `user`, `old`), `played` (`nid`, `k`, `secs`: the opened session's length, at its end). Backend rows of the same kind (`planned`, `sent`, ...) come from `src = "backend"` |
-| session | `leave` | `secs` (session length), `why`: `left`, `shutdown`, `gone` (left while no generation ran the engine), `swap60?` (left within 60 s of a hot swap) |
+| session | `leave` | `secs` (session length), `why`: `left`, `shutdown`, `gone` (left while no generation ran the engine), `swap60?` (left within 60 s of a hot swap), `trust?` (Player.DeviceTrustLevel at the leave: `Pending` (never settled; always in Studio), `Unknown`, `None`, `Standard`, `Full`; missing on engines without it) |
 | tech | `server` | Every `techEvery` s: `fps` (physics), `hb` (Heartbeat rate), `mem` (MB, 10s), `players`, `ping50?`, `ping90?` (ms), `q`, `qr` (queued events, recordings), `dropped`, `sent`, `fails`, `health?`, `errors?` (kernel 0.3.2 health) |
 | tech | `client` (src client) | Every `techEvery` s: `fps`, `mem` (MB, 10s), `ping?` (ms) |
 | tech | `load` (src client) | `secs`: from the client starting to the engine starting (first client generation only) |

package/out/analytics/server.d.ts

@@ -144,6 +144,13 @@ export declare class ServerAnalytics {
      * stopped. No call when the player is alone; a failed call counts what it read (0 at first).
      */
     private friendsHere;
+    /**
+     * The join's player policy (PolicyService:GetPolicyInfoForPlayerAsync): `pol` = `ok`, `failed` or `timeout` (no answer in
+     * POLICY_WAIT s), and with `ok` the answer: `pol_ads`, `pol_rand` (paid random items restricted), `pol_trade` (paid
+     * item trading allowed), `pol_share` (content sharing allowed), `pol_subs` (eligible to buy a subscription), `pol_cn`
+     * (China policies), `pol_links` (the allowed external link references, comma separated, "" = none).
+     */
+    private policyProps;
     private emitJoin;
     private onPlayer;
     private leave;

package/out/analytics/server.luau

@@ -6,6 +6,7 @@ local DataStoreService = _services.DataStoreService
 local HttpService = _services.HttpService
 local LocalizationService = _services.LocalizationService
 local Players = _services.Players
+local PolicyService = _services.PolicyService
 local RunService = _services.RunService
 local Stats = _services.Stats
 local Workspace = _services.Workspace
@@ -130,8 +131,22 @@ local RECORDING_MAX_CHUNKS = 80
 local RECORDING_MAX_SECONDS = 900
 --* The join event waits this long for the client's device info. 
 local DEVICE_WAIT = 8
+--* The join event waits this long for PolicyService's answer (GetPolicyInfoForPlayerAsync has no timeout of its own). 
+local POLICY_WAIT = 5
 local ZONE_INTERVAL = 0.5
 local ZONE_TAG = "TTZone"
+--[[
+	*
+	 * Player.DeviceTrustLevel's name (Pending, Unknown, None, Standard, Full; Roblox sets it once, some time after the join,
+	 * and Studio never does), or undefined on an engine without the property. Roblox acts on none of it: data only.
+	 
+]]
+local function deviceTrust(player)
+	local ok, level = pcall(function()
+		return player.DeviceTrustLevel
+	end)
+	return if ok and typeof(level) == "EnumItem" then level.Name else nil
+end
 --* One player's session. Plain data (persist), keyed by tostring(UserId). 
 local function nowMs()
 	return DateTime.now().UnixTimestampMillis
@@ -563,7 +578,7 @@ do
 	end
 	function ServerAnalytics:track(player, kind, name, props)
 		if not isEventName(name) then
-			warn("[src/analytics/server.ts:505]", `[analytics] {kind} event name must be 1-64 characters: {string.sub(tostring(name), 1, 80)}`)
+			warn("[src/analytics/server.ts:517]", `[analytics] {kind} event name must be 1-64 characters: {string.sub(tostring(name), 1, 80)}`)
 			return nil
 		end
 		local session = if player then self:sessionOf(player) else nil
@@ -671,7 +686,7 @@ do
 		end
 		local control = _condition
 		if not isExperimentName(name) or not isVariantList(variants) then
-			warn("[src/analytics/server.ts:557]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
+			warn("[src/analytics/server.ts:569]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
 			return control
 		end
 		local session = self:sessionOf(player)
@@ -736,7 +751,7 @@ do
 	function ServerAnalytics:applySettings(parsed)
 		local errorsText = table.concat(parsed.errors, "; ")
 		if errorsText ~= table.concat(self.settingsErrors, "; ") and errorsText ~= "" then
-			warn("[src/analytics/server.ts:592]", `[analytics] the sink settings (settings.backend or settings.analytics): {errorsText}`)
+			warn("[src/analytics/server.ts:604]", `[analytics] the sink settings (settings.backend or settings.analytics): {errorsText}`)
 		end
 		self.settingsErrors = parsed.errors
 		local hadSettings = self.settings ~= nil
@@ -766,7 +781,7 @@ do
 		-- `new AnalyticsEngine({ settings })`.
 		if not settingsSupported() then
 			if self.kernel ~= nil and self.kernel.test ~= true then
-				warn("[src/analytics/server.ts:619]", `[analytics] no sink settings: they come from the signed settings record (kernel 0.3.8+, "typetorch backend setup"); this server runs kernel {self.kernel.kernelVersion}. Or pass new AnalyticsEngine(\{ settings \})`)
+				warn("[src/analytics/server.ts:631]", `[analytics] no sink settings: they come from the signed settings record (kernel 0.3.8+, "typetorch backend setup"); this server runs kernel {self.kernel.kernelVersion}. Or pass new AnalyticsEngine(\{ settings \})`)
 			end
 			self.settingsTried = true
 			return nil
@@ -1290,6 +1305,39 @@ do
 		end
 		return count
 	end
+	function ServerAnalytics:policyProps(player, props)
+		local info
+		local failed = false
+		task.spawn(function()
+			local ok, result = pcall(function()
+				return PolicyService:GetPolicyInfoForPlayerAsync(player)
+			end)
+			if ok and type(result) == "table" then
+				info = result
+			else
+				failed = true
+			end
+		end)
+		local deadline = os.clock() + POLICY_WAIT
+		while info == nil and not failed and os.clock() < deadline and player.Parent ~= nil and not self.stopped do
+			task.wait(0.1)
+		end
+		local answer = info
+		if answer == nil then
+			props.pol = if failed then "failed" else "timeout"
+			return nil
+		end
+		props.pol = "ok"
+		props.pol_ads = answer.AreAdsAllowed == true
+		props.pol_rand = answer.ArePaidRandomItemsRestricted == true
+		props.pol_trade = answer.IsPaidItemTradingAllowed == true
+		props.pol_share = answer.IsContentSharingAllowed == true
+		props.pol_subs = answer.IsEligibleToPurchaseSubscription == true
+		props.pol_cn = answer.IsSubjectToChinaPolicies == true
+		local _allowedExternalLinkReferences = answer.AllowedExternalLinkReferences
+		local links = if type(_allowedExternalLinkReferences) == "table" then (answer.AllowedExternalLinkReferences) else {}
+		props.pol_links = string.sub(table.concat(links, ","), 1, 120)
+	end
 	function ServerAnalytics:emitJoin(player, session)
 		local deadline = os.clock() + DEVICE_WAIT
 		while session.device == nil and os.clock() < deadline and player.Parent ~= nil and not self.stopped do
@@ -1310,6 +1358,8 @@ do
 		if countryOk then
 			props.country = country
 		end
+		self:policyProps(player, props)
+		props.trust = deviceTrust(player)
 		props.friends = self:friendsHere(player)
 		props.ret = session.ret
 		-- The engine started after this player joined (created later, or added by a deploy).
@@ -1383,6 +1433,7 @@ do
 			self:emit(session, "session", "leave", encodeProps({
 				secs = math.floor((now - session.joinedAt) / 1000),
 				why = why,
+				trust = deviceTrust(player),
 				swap60 = if lastSwap ~= nil and os.time() - lastSwap <= 60 then true else nil,
 			}))
 		end
@@ -1751,7 +1802,7 @@ do
 				end
 			end)
 			if not ok then
-				warn("[src/analytics/server.ts:1198]", `[analytics] client message failed: {string.sub(tostring(err), 1, 200)}`)
+				warn("[src/analytics/server.ts:1245]", `[analytics] client message failed: {string.sub(tostring(err), 1, 200)}`)
 			end
 		end)
 		self.trove:add(function()
@@ -2034,7 +2085,7 @@ do
 		self.lastWarnAt = now
 		local more = if self.suppressed > 0 then ` (+{self.suppressed} more in the last minute)` else ""
 		self.suppressed = 0
-		warn("[src/analytics/server.ts:1393]", `[analytics] {message}{more}`)
+		warn("[src/analytics/server.ts:1440]", `[analytics] {message}{more}`)
 		return true
 	end
 	function ServerAnalytics:noteSuccess()

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@typetorch/framework",
-	"version": "0.6.2",
+	"version": "0.6.3",
 	"description": "TypeTorch framework for roblox-ts: hot-swappable modules (dependency injection, lifecycle, troves), guarded networking, hot assets and the in-game dev menu. Ships inside every TypeTorch artifact.",
 	"license": "MIT",
 	"author": "TypeTorch",