Which route fits a HaxeFlixel game?

haxe.Http from the Haxe standard library. setHeader() sets the two headers, setPostData() sets the JSON body, and request(true) sends a POST. onStatus() gives the status code on every target, so the code reads it from there and does not parse error text.

The same class runs on HTML5 and on native targets, with one difference: on hxcpp builds the request blocks, so the class runs it on sys.thread.Thread and hands the status back to the game loop.

Sources: Haxe API, haxe.Http, sys.Http, haxe.http.HttpJs and sys.thread.Thread.

What must every HaxeFlixel event contain?

One JSON envelope, the same one the Godot and Unity SDKs send. POST it to /v0/events on your collector with two headers: x-publishable-key and Content-Type: application/json. The body is {"events": [...]} with 1 to 50 events. A good request returns {"accepted":N}.

  • type "track", an event name in snake_case, channel "app" and version (your tracker version, up to 32 characters).
  • message_id: a new UUID version 4 for each event. Keep it on a retry. The collector counts each message_id once.
  • anonymous_id: one UUID version 4 per install, saved on the device. The collector checks the version digit, so a random hex string of the same length is refused.
  • session_id: 1 to 64 characters of letters, digits and . _ : -. Start a new one after 30 minutes without play.
  • original_timestamp: the time of the event in ISO 8601 UTC, such as 2026-11-09T10:00:00Z. It can be up to 7 days old, and at most 10 minutes in the future.
  • context.app.platform (windows, macos, linux, web, android, ios or other) and engine "other". Add storefront, app_version and build to filter reports by build.
  • properties: a flat object of strings, numbers, booleans or null.

Sources: Manalens app events documentation.

How do I send events from HaxeFlixel?

Add this class to your project. It uses its own FlxSave named analytics, because FlxG.save also holds HaxeFlixel settings such as sound preferences. FlxSave.flush() writes the save to disk at once. The UUID uses Std.random(), not FlxG.random, which is the seeded game generator meant for repeatable play.

Haxe has no ISO 8601 formatter, so now() builds the string from the getUTC getters of Date. The class checks the reply in FlxG.signals.postUpdate, once per frame.

Haxe (Analytics.hx)

package;

import flixel.FlxG;
import flixel.util.FlxSave;
import haxe.Http;
import haxe.Json;

class Analytics {
	static inline var URL = "https://YOUR_COLLECTOR_ENDPOINT/v0/events";
	static inline var KEY = "YOUR_PUBLISHABLE_KEY";
	static var save:FlxSave;
	static var queue:Array<Dynamic> = [];
	static var sessionId:String;
	static var startedAt = 0.0;
	static var busy = false;
	static var sent = 0;
	static var result:Null<Int> = null;
	static var nextAt = 0.0;
	static var backoff = 0.0;

	public static function init() {
		save = new FlxSave();
		save.bind("analytics");
		sessionId = uuid();
		startedAt = haxe.Timer.stamp();
		if (save.data.consent == true) {
			if (save.data.queue != null) queue = save.data.queue;
			setConsent(true);
		}
		FlxG.signals.postUpdate.add(update);
		FlxG.signals.focusLost.add(persist);
		lime.app.Application.current.onExit.add(function(_) track("session_end", {duration_s: Std.int(haxe.Timer.stamp() - startedAt)}));
	}

	public static function setConsent(on:Bool) {
		if (!on) {
			queue = [];
			save.data.consent = false; save.data.anonId = null; save.data.firstOpenAt = null; save.data.queue = null;
			save.flush();
			return;
		}
		save.data.consent = true;
		var first = save.data.anonId == null;
		if (first) { save.data.anonId = uuid(); save.data.firstOpenAt = now(); }
		save.flush();
		track("game_open", {is_first_open: first, first_open_at: save.data.firstOpenAt});
		track("session_start", {});
	}

	public static function track(event:String, props:Dynamic) {
		if (save.data.consent != true) return;
		queue.push({type: "track", event: event, channel: "app", version: "0.1.0",
			message_id: uuid(), anonymous_id: save.data.anonId, session_id: sessionId, original_timestamp: now(),
			context: {app: {platform: platform(), storefront: "itch", app_version: "1.4.0", build: "571", engine: "other"},
				locale: "en", library_name: "my-game", library_version: "1.4.0"},
			properties: props});
		persist();
	}

	static function persist() {
		if (save.data.consent == true) { save.data.queue = queue; save.flush(); }
	}

	static function update() {
		if (result != null) {
			var s:Int = result; result = null; busy = false;
			if ((s >= 200 && s < 300) || (s >= 400 && s < 500 && s != 408 && s != 429)) {
				queue.splice(0, sent); backoff = 0; persist();
			} else {
				backoff = Math.min(Math.max(backoff * 2, 5), 300); nextAt = haxe.Timer.stamp() + backoff;
			}
		}
		if (busy || queue.length == 0 || haxe.Timer.stamp() < nextAt || save.data.consent != true) return;
		busy = true;
		var batch = queue.slice(0, 50);
		sent = batch.length;
		var status = 0;
		var http = new Http(URL);
		http.setHeader("x-publishable-key", KEY);
		http.setHeader("Content-Type", "application/json");
		http.setPostData(Json.stringify({events: batch}));
		http.onStatus = function(s) status = s;
		http.onData = function(_) result = status;
		http.onError = function(_) result = status;
		#if sys
		sys.thread.Thread.create(function() http.request(true));
		#else
		http.request(true);
		#end
	}

	static function uuid():String {
		var h = "0123456789abcdef", s = "";
		for (i in 0...36) s += switch (i) {
			case 8 | 13 | 18 | 23: "-";
			case 14: "4";
			case 19: h.charAt(8 + Std.random(4));
			default: h.charAt(Std.random(16));
		}
		return s;
	}

	static function now():String {
		var d = Date.now();
		function p(n:Int) return StringTools.lpad(Std.string(n), "0", 2);
		return d.getUTCFullYear() + "-" + p(d.getUTCMonth() + 1) + "-" + p(d.getUTCDate()) + "T" + p(d.getUTCHours()) + ":"
			+ p(d.getUTCMinutes()) + ":" + p(d.getUTCSeconds()) + ".000Z";
	}

	static function platform():String {
		#if html5 return "web"; #elseif android return "android"; #elseif ios return "ios";
		#elseif windows return "windows"; #elseif mac return "macos"; #elseif linux return "linux";
		#else return "other"; #end
	}
}

Sources: HaxeFlixel API, FlxSave, FlxG and SignalFrontEnd; Haxe API, Date, Std, haxe.Json and haxe.Http.

How do I start the class and track gameplay?

Call Analytics.init() once, after the FlxGame exists, for example in the create() of your first state. init() also listens to lime.app.Application.current.onExit, which Lime dispatches when the application is exiting, and queues session_end there. The queue is saved, so the next launch sends it.

Use the event conventions, such as level_start, level_complete and resource, so the Game KPIs board reads them.

Haxe

// PlayState.hx (or your first state)
override public function create() {
    super.create();
    Analytics.init();
}

// Consent screen button:
// Analytics.setConsent(true);

// Gameplay:
// Analytics.track("level_complete", {level: 3, attempt: 1, score: 1200});

Sources: HaxeFlixel API, FlxG and FlxState; Lime API, Application; Manalens app events documentation.

What changes for web, desktop and mobile builds?

HaxeFlixel builds for HTML5, desktop (Windows, macOS and Linux through hxcpp), Android and iOS through OpenFL and Lime.

  • HTML5: haxe.Http uses an async XMLHttpRequest. The x-publishable-key header causes a CORS preflight, which the collector answers for your project domain, its subdomains and Allowed origins. *.itch.zone is allowed by default.
  • Desktop and mobile: the request blocks for up to cnxTimeout (10 seconds by default), so the class sends it from a thread. A native request sends no Origin header, so CORS does not apply.
  • Android: add <config:android permission="android.permission.INTERNET" /> to project.xml, and use an https:// endpoint, because Android 9 and later block cleartext HTTP by default.
  • Neko: HTTPS needs -lib hxssl, and the error without it is thrown, not passed to onError(). Test on hxcpp or HashLink if you ship those.

Sources: Haxe API, haxe.http.HttpJs and sys.Http; Lime documentation, Project files; Android developer documentation, Network security configuration; Manalens app events documentation.

What are the HaxeFlixel gotchas?

Most of these differ between HTML5 and native targets.

  • haxe.Http.request() blocks on native targets. Called in update(), it freezes the game for up to 10 seconds when the network is slow.
  • onError() fires in different cases on each target: HTML5 calls it for status 400 and up and for a failed connection, native targets for any status outside 200 to 399. Read the code from onStatus().
  • FlxG.autoPause is true by default, so the game pauses on focus loss and timers stop. The class saves the queue on FlxG.signals.focusLost.
  • Date.getTime() has only second resolution on cpp and neko, and Date.toString() is local time. Build the timestamp from the getUTC getters.
  • FlxG.random is a seeded generator for repeatable play. Use Std.random() for IDs, or players can share IDs.

Sources: Haxe standard library source, sys.Http and HttpJs; Haxe API, Date; HaxeFlixel API, FlxG and FlxRandom.

How do I check that HaxeFlixel events arrive?

Send one batch from a development build and read the response status. Trace the status in onStatus while you test: 200 means the batch was accepted. On HTML5, the OPTIONS preflight should succeed first.

  1. Create a test project in Manalens and copy its Publishable key.
  2. Run lime test html5 with localhost in Allowed origins of a test project, then run a native target such as lime test windows.
  3. Send game_open and session_start from the HaxeFlixel build, then check that the response is {"accepted":2}.
  4. Open the activity feed and check that platform, build and engine are set on the events.
  5. Switch off the network, play for a minute, switch it on, and check that the queued events arrive once.
  6. Replace the test key with the production Publishable key before you ship.

Sources: Manalens app events documentation.

How do I start?

Manalens is the analytics and growth engine built for games. Add Analytics.hx to your HaxeFlixel project, ask for consent, and use the Game KPIs board to compare your HTML5 and desktop builds.

Sources: Manalens product documentation.

Frequently asked questions

Does haxe.Http block the game in HaxeFlixel?

On native targets, yes. The sys implementation of haxe.Http.request() waits for the reply, up to a 10 second connect timeout, so the class sends it from sys.thread.Thread. On HTML5, haxe.Http uses an async XMLHttpRequest and does not block, so the class calls request() directly there.

Where does HaxeFlixel save the analytics data?

In your own FlxSave named analytics. On HTML5 it lives in the local storage of the page origin, and on desktop it is a .sol file in the user data folder of each OS. Do not use FlxG.save, because HaxeFlixel keeps its own settings there.

How do I read the HTTP status code with haxe.Http?

Set onStatus. It gets the status code on HTML5 and on native targets. onError fires in different cases on each target and carries only a message, so store the code from onStatus and decide on retry or drop when onData or onError runs.

Does the HTML5 build work on itch.io?

Yes. haxe.Http on HTML5 uses XMLHttpRequest, and the browser sends a CORS preflight because of the x-publishable-key header. The collector answers it for your project domain and Allowed origins, and *.itch.zone is allowed by default, so itch.io uploads need no setup.

Sources and implementation