Template analytics and in-game notifications

How server-decided events reach Roblox analytics, how economy events are batched, how transient toasts reach players on each device, and how Roblox experience notifications bring players back.

Roblox Template / Template systems catalogue

The Template sends analytics from the server that decided an outcome and shows in-game feedback as temporary toasts. AnalyticsService wraps Roblox analytics; NotificationService sends the player-facing fact. Neither system saves an inbox or an event history in the player's data.

Which analytics call to use

Only src/core/server/Services/AnalyticsService.luau may call Roblox's AnalyticsService; the boundary linter enforces that ownership. Its analytics feature switch is on by default. Off, logging returns immediately and the Loader skips its batching timer and unload listener.

What may be sent is registered in Config/Analytics (a game adds its own in Config/Overrides/Analytics.luau): the funnels and their steps (funnels), economy reason prefixes and the transaction type each maps to (economy), and custom event names (events; the Template uses 33 of Roblox's 100). AnalyticsService.coverage.spec fails CI for a CurrencyService or ClaimService.claim reason whose prefix is not registered, an unlisted name in a logCustom or logServer call, and a listed event nothing sends.

logEconomy(player, flow, currencyId, amount, endingBalance, reason)

Source for a gain and Sink for a spend. CurrencyService already calls this for actual balance changes, so gameplay usually needs only a specific currency reason such as shop:sword. The reason's prefix picks the transaction type from Config/Analytics.economy, one of six categories (IAP, Shop, TimedReward, Gameplay, Admin, Refund), and the reason up to its second colon is the item SKU (season_pass:s1:4:free is season_pass:s1). An unlisted prefix is still sent, as itself, with a warning. Do not double-log the same change.

logFunnelStep(player, funnelName, stepName)

A step of a funnel registered in Config/Analytics.funnels, from the service that verified the player reached it. Its number is its place in that funnel's list, so two steps never share one; an unregistered funnel or step is warned about and not sent. Once live, add steps only at the end.

logProgression(player, path, status, level, levelName?, fields?)

A player starting, completing or failing (Start, Complete, Fail) a level of a progression path, a stable lowercase name such as level, prestige or tutorial. Capped per player (Config/Analytics.progression). Progression and the tutorial send these; quests do not.

logOnboardingStep(player, step, stepName)

Roblox's separate onboarding funnel. DemoService uses the first demo click as an example; a real game supplies its own onboarding milestones.

logCustom(player, eventName, value?, fields?)

A stable lowercase_snake event name listed in Config/Analytics.events (an unlisted one is warned about and not sent), a quantity defaulting to 1, and up to three short custom-field strings. Extra supplied fields are ignored. Put the varying item or category in a field, rather than creating an event name per item.

logServer(eventName, value?, fields?)

A count about the whole server rather than one player. Roblox ties every custom event to a player, so the first player in real play in the server carries it. It returns false when nobody can (an empty server, only test-mode players, analytics off): keep the count and try again. ErrorReportService uses it for script_error.

From the service that decided the outcome
AnalyticsService.logFunnelStep(player, "shop_visit", "shop_opened") -- registered in Config/Overrides/AnalyticsAnalyticsService.logProgression(player, "level", "Complete", 4)AnalyticsService.logCustom(player, "boss_defeated", 1, { bossId }) -- listed in its eventsNotificationService.notify(player, "success", "shop.notice.unlocked", {	title = "shop.notice.title",	args = { name = upgrade.title },})

Calls to Roblox are protected with pcall; failures warn rather than break gameplay. Analytics functions other than logServer take Player first, so Roblox associates the user without adding an identifying custom field. No client remote accepts analytics events.

Why economy events are batched for 30 seconds

logEconomy accumulates by player, flow, currency, transaction type and optional item SKU. Every 30 seconds it sends the sum of the amounts with the latest ending balance. It also flushes when DataService.unloading fires; the unload flush is deferred so other unload listeners can contribute their final events.

Purchases (the IAP transaction type, iap: reasons) send immediately. Whether an event belongs to real play is checked when it happens, so changing test mode before the next flush does not reclassify a real earlier gain. Robux itself is not an in-game economy event: a developer product logs the currency its reward grants, while Roblox reports Robux revenue separately.

A currency change reaches analytics and the player. The owning server service changes currency through CurrencyService. The changed save is synced to the player's interface. AnalyticsService combines ordinary economy events for 30 seconds or until unload, while purchase reasons beginning iap: send immediately to Roblox. The owning service can separately send a notification, which the client turns into a timed toast.

What Studio and test mode send

Events reach Roblox when Features.analytics is enabled. Economy events are batched except for immediate iap: transactions.

Which gameplay events already exist

The first_session funnel (SessionService) follows an account's first visit, each step once: joined (the save loaded), spawned (the first character ready), first_action (the game's core action, logged by game code with SessionService.firstSessionStep(player, "first_action"); the demo logs its first click), first_reward (currency earned in play, not IAP, Admin or Refund), purchase_prompt (a product or pass prompt closed) and first_purchase (a real product or pass grant). It shows where new players drop off whether or not the tutorial is on.

Pass purchases in game log gamepass_bought. With subscriptions on, a closed subscription prompt logs subscription_prompted, and a purchase, a paid renewal and a lapse seen during a session log subscription_started, subscription_renewed and subscription_lapsed with the subscription key only. The daily reward, code, quest, referral, badge and shop services log their own verified events. The community service logs community_prompt when it sends a favourite or group prompt, community_group_joined when it confirms a new member, and community_friend_joined when it sends a friend join. A favourite cannot be confirmed, so it is not counted. Rewarded ads log ad_shown and ad_rewarded. Every event and its sender is listed in the Template's docs/testing/Analytics Coverage.md.

The platform's feedback sender logs feedback_sent after success, with the category only. It never puts the player's feedback text in analytics. See The platform bridge. The Template has no player report of its own: Roblox's report in the Roblox menu covers it.

Error reports log script_error every five minutes per server, at most ten signatures: the new count as the value, and the side, top stack frame and message (numbers, ids and players' names taken out) as custom fields 1 to 3.

How in-game notifications reach the screen

NotificationService.notify(player, kind, message, options?) addresses one player; notifyAll(kind, message, options?) addresses everyone. options can contain title, args and durationSeconds; the default is Config/Notifications.defaultSeconds (4). Each notification has a GUID id, kind (info, success, warning, error), optional title, message, optional args and duration. The message and title are Config/Strings keys: the client translates them once with args filled in, so each player reads the toast in their own language; text that is not a key, such as a staff announcement, is shown as written (Text and languages).

The server fires notifications.pushed, a server-to-client fact. NotificationController.push adds the toast to the Charm ClientState.notifications list. At most Config/Notifications.maxVisible toasts (5) are on screen, or maxVisibleTouch (3) with touch input; the rest wait in arrival order, and nothing on screen is pushed off. When one leaves, the oldest waiting toast comes in. A toast's time starts when it shows, not when it arrives. At most maxQueued (10) wait: past that the oldest waiting toast is dropped, so a burst drains with the newest messages rather than stale ones. The same toast again (same kind, title and message) while it shows keeps its place and starts its time and bar over; while it waits, it is not queued twice. A game changes these values in Config/Overrides/Notifications.luau. A tap or click dismisses early. Toasts never become a gamepad selection target.

NotificationController.notify(kind, message, title?, args?) creates a local toast of defaultSeconds for client-only feedback. Outcomes the server knows about should be sent by the server. The controller's dismiss(id) keeps timers and state consistent; the screen alone retains a leaving toast for the exit animation.

Placement and transitions

UI/Screens/Notifications.luau draws the stack at the toasts layer where the HUD layout puts the toasts widget: at the top centre, under the event banner and the tutorial's panel, in the room the rest of the HUD leaves (with none, over the top centre rather than hide a message), and below the admin console while it is open. Newest at the bottom; a toast rises in and, leaving, rises a little and fades. UI/Components/Toast.luau draws the card and lifetime bar, which drains on one engine tween rather than a per-frame update; toasts that stay are not rebuilt when another leaves; Theme.toastExit controls the exit.

Sound

warning and error play the error sound, success plays success, and info is silent. All sound goes through SoundController at the player's volume.

Persistence

Toasts are transient client state. No inbox, receipt history or unread count is saved. Platform website notifications are a separate system described in Notifications and push.

Roblox experience notifications

ExperienceNotificationService (switch experienceNotifications, off by default) sends Roblox notifications that bring a player back, such as "your reward is ready". A game declares its kinds in Config/Overrides/ExperienceNotifications.luau: each is a notification string made in the Creator Dashboard (there is no API for it) and its asset id. Game code calls send(userId, kind, parameters) to send one now, or schedule(userId, kind, dueAt, parameters) and cancel(userId, kind) for later; one pending per player and kind.

Limits

Each player gets at most maxPerWindow notifications in windowSeconds (one a day by default), checked atomically across servers before every send; Roblox adds its own one a day per experience and delivers only to opted-in players 13 and over, in experiences with 100 visits.

Opt-in prompt

Game code calls offerOptIn(player, moment), or schedules a kind with prompt = true. The server refuses a first session and its own cooldown, then the client asks Roblox (CanPromptOptInAsync) and shows its standard prompt (PromptOptIn), which cannot be styled.

Setup

A key with only user.user-notification:write on the experience, stored as the secret NotificationsApiKey (domain apis.roblox.com), and Allow HTTP Requests. Without it the server warns once and every call answers unavailable.

Analytics

notification_prompt_offered (the moment) and notification_opened (the kind, from launch data; openedFrom(player) answers it too). Delivery and clicks per category are in the Creator Dashboard's notification analytics.

Developers test with pushnotify me prompt and pushnotify me send <kind>. Source note: docs/systems/Experience Notifications.md.

Adding an event or a notification

  1. Use the owner of the outcome

    Log after the server verifies the action. Prefer an existing currency reason to another custom event; a new reason prefix goes in Config/Analytics.economy, a new custom event or funnel in its registry. Follow the Template's analytics-event skill for event and funnel additions.

  2. Document the event's meaning

    Put stable event names, custom-field meanings and any funnel step numbers in the owning Template system note's Analytics section and in docs/testing/Analytics Coverage.md. The current source notes are docs/systems/Analytics.md and docs/systems/Notifications.md.

  3. Give the player useful feedback

    Call NotificationService for the server's outcome, with a clear message added to Config/Strings as a key and an appropriate kind. Check its length and stacking on touch as well as desktop during the playtest.

Updated