Unity SDK · In-Game Messages

Design pop-ups on the dashboard, render them inside Unity with UI Toolkit (default), uGUI or IMGUI. Target everyone, a segment, a percentage rollout, or a list of player ids - no rebuild required.

Overview

KalmForge.InGameMessages is a static class that talks to a hidden InGameMessagesController MonoBehaviour spawned on first show. There are two delivery modes:

Auto-queue - messages with no trigger_key are fetched and queued by SyncAsync().
Trigger-keyed - messages with a trigger_key only render when you call TryShow(key).

The server filters by language, platform, segment, max-views and cooldown, so the same player won't see the same message too often.

Quick start

exampleC#

1using KalmForge;
2
3async void Start() {
4    await KalmForgeClient.Init();
5
6    InGameMessages.SetButtonHandler((messageId, action) => {
7        if (action.Type == "reward") GrantReward(action.Value);
8    });
9
10    await InGameMessages.SyncAsync();        // queue all auto-show messages
11    await InGameMessages.TryShow("first_run"); // show the "first_run" trigger if eligible
12}

Auto-queue messages

SyncAsync() requests every message without a trigger key and enqueues them. The controller drains the queue one at a time - each dismiss starts the next one. Safe to call repeatedly; the server de-duplicates per max_views_per_player and cooldown_seconds.

Trigger-keyed messages

exampleC#

1bool shown = await InGameMessages.TryShow("level_failed_3x");
2// false → no eligible message (already shown / segment mismatch / capability off)

Button actions

Each button on a message has an action Type + Value. The SDK auto-handles url and deep_link via Application.OpenURL; everything else is forwarded to your handler:

Name	Type	Description
"close"	string	Just dismiss the message. (Default for auto-synthesised OK.)
"url"	string	Value is a URL. SDK calls Application.OpenURL(value).
"deep_link"	string	Value is a deep link. Same handling as "url".
"reward"	string	Custom - your handler grants the reward.
"dismiss_forever"	string	Custom - your handler should mark this message as never-show-again.

Settings asset

Default theme, render backend, font source and panel scale are configured under Window → KalmForge → In-Game Messages (creates Resources/InGameMessagesSettings.asset). Pick:

UIToolkit (default) - uses your project's PanelSettings.
UGUI - Canvas + Image + Text. Supports legacy fonts and (with TMP installed) TMP_Text.
IMGUI - fallback for editor / debug overlays.

Tip

InGameMessages.AlwaysOnTop = true (default) guarantees the popup paints above every other Unity surface, including Screen-Space-Overlay uGUI canvases, by spawning a high-depth camera and temporarily switching competing canvases to ScreenSpace-Camera.

Events

Name	Type	Description
OnMessageShown	event Action<string>	Fires with the message id when it becomes visible.
OnMessageDismissed	event Action<string>	Fires with the message id when it dismisses.

API reference

InGameMessages - static API

Name	Type	Description
SyncAsync()	Task	Fetch + queue all auto-show messages.
TryShow(triggerKey)	Task<bool>	Show the next eligible trigger-keyed message.
SetButtonHandler(Action<id, ButtonAction>)	void	Receive non-url/deep_link button actions.
ReportAsync(messageId, action)	Task	Manually report a custom interaction (e.g. "shown", "clicked").
AlwaysOnTop	bool	Default true. See callout above.

REST endpoint

examplebash

1# Fetch eligible messages
2GET /api/public/sdk/in-game-messages
3  ?player_id=...&install_id=...&lang=en&platform=ios
4  [&trigger=level_failed_3x]
5Headers: X-API-Key: kf_xxx_yyy
6
7# Report an interaction
8POST /api/public/sdk/in-game-messages
9{ "message_id": "...", "player_id": "...", "install_id": "...", "action": "shown" }