Which route fits a Ren'Py game?
Python in the game, with Ren'Py's own HTTP function. renpy.fetch(url, method, data, json, content_type, timeout, result, params, headers) sends a request and returns the response. With json set, it sends POST and the application/json content type. On failure it raises an exception.
Ren'Py docs say fetch() is meant for the main thread, after the game has started. Outside an interaction it waits with renpy.pause(), so the game does not lock up. Inside an interaction, such as a screen action, it blocks the display until the request ends or times out.
Sources: Ren'Py documentation, Fetching Data from the Web; Ren'Py changelog, 8.2.0 and 8.3.0.
What must every Ren'Py 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 Ren'Py?
Save this as game/analytics.rpy. It stores everything in persistent fields, which belong to no save slot, so loading a save or rolling back never changes the queue or the ID. renpy.save_persistent() writes them to disk after each change, so a crash loses nothing.
Python's datetime.isoformat() ends a UTC time with +00:00. The collector wants the Z form, so mana_now() formats the time by hand. uuid.uuid4() gives the version 4 UUIDs.
Ren'Py (game/analytics.rpy)
default persistent.mana_consent = False
default persistent.mana_anon_id = None
default persistent.mana_first_open_at = None
default persistent.mana_queue = []
init python:
import uuid, datetime, time
MANALENS_URL = "https://YOUR_COLLECTOR_ENDPOINT/v0/events"
MANALENS_KEY = "YOUR_PUBLISHABLE_KEY"
WEEK = datetime.timedelta(days=7)
class Manalens(object):
session_id = uuid.uuid4().hex
started = time.time()
retry_at = 0.0
backoff = 2.0
def mana_now(d=None):
d = d or datetime.datetime.now(datetime.timezone.utc)
return d.strftime("%Y-%m-%dT%H:%M:%S.") + "%03dZ" % (d.microsecond // 1000)
def mana_platform():
for flag, name in ((renpy.emscripten, "web"), (renpy.android, "android"), (renpy.ios, "ios"),
(renpy.windows, "windows"), (renpy.macintosh, "macos"), (renpy.linux, "linux")):
if flag:
return name
return "other"
def mana_track(event, props=None):
if not persistent.mana_consent:
return
if persistent.mana_anon_id is None:
persistent.mana_anon_id = str(uuid.uuid4())
persistent.mana_queue.append({
"type": "track", "event": event, "channel": "app", "version": "0.1.0",
"message_id": str(uuid.uuid4()), "anonymous_id": persistent.mana_anon_id,
"session_id": Manalens.session_id, "original_timestamp": mana_now(),
"context": {"app": {"platform": mana_platform(), "storefront": "steam",
"app_version": config.version or "0.0.0", "engine": "other"},
"locale": "en", "library_name": "my-game", "library_version": "0.1.0"},
"properties": props or {}})
persistent.mana_queue = persistent.mana_queue[-1000:]
renpy.save_persistent()
def mana_flush():
if not persistent.mana_consent or time.time() < Manalens.retry_at:
return
cutoff = mana_now(datetime.datetime.now(datetime.timezone.utc) - WEEK)
persistent.mana_queue = [e for e in persistent.mana_queue if e["original_timestamp"] > cutoff]
while persistent.mana_queue:
batch = persistent.mana_queue[:50]
try:
renpy.fetch(MANALENS_URL, json={"events": batch}, timeout=5,
headers={"x-publishable-key": MANALENS_KEY})
except Exception as e:
code = getattr(e, "status_code", None)
if code is None or code >= 500 or code in (408, 429):
Manalens.retry_at = time.time() + Manalens.backoff
Manalens.backoff = min(Manalens.backoff * 2, 300.0)
return
persistent.mana_queue = persistent.mana_queue[len(batch):]
Manalens.backoff = 2.0
renpy.save_persistent()
def mana_set_consent(value):
persistent.mana_consent = value
if not value:
persistent.mana_anon_id = None
persistent.mana_queue = []
renpy.save_persistent()
def mana_start():
if not persistent.mana_consent:
return
first = persistent.mana_first_open_at is None
if first:
persistent.mana_first_open_at = mana_now()
mana_track("game_open", {"is_first_open": first, "first_open_at": persistent.mana_first_open_at})
mana_track("session_start")
mana_flush()
def mana_on_quit():
mana_track("session_end", {"duration_s": int(time.time() - Manalens.started)})
config.quit_callbacks.append(mana_on_quit)Sources: Ren'Py documentation, Persistent Data, Fetching Data from the Web and Configuration Variables; Python documentation, uuid and datetime.
How do I start tracking and track story events?
Call mana_start() from the splashscreen label, and flush from script lines at natural pauses, such as the end of a chapter. Do not call mana_flush() from config.periodic_callbacks, which run about 20 times a second, or from a screen action, because both run inside an interaction.
session_end is queued in config.quit_callbacks and sent at the next launch, because a request at quit could block the close. For a visual novel, chapter_start, chapter_complete and choice_made with a choice name tell you where readers stop.
Ren'Py script
label splashscreen:
$ mana_start()
return
screen analytics_consent():
vbox:
text "Share anonymous play data to help us improve the game?"
textbutton "Yes" action [Function(mana_set_consent, True), Function(mana_start), Return()]
textbutton "No" action [Function(mana_set_consent, False), Return()]
label chapter_2_end:
$ mana_track("chapter_complete", {"chapter": 2, "route": "lena"})
$ mana_flush()
jump chapter_3Sources: Ren'Py documentation, Configuration Variables and Fetching Data from the Web; Manalens app events documentation.
How do the player ID, the offline queue and consent work?
The anonymous_id, the consent flag, the first open time and the queue live in persistent fields. Ren'Py saves persistent data when it terminates and when you call renpy.save_persistent(). On desktop it sits in the Ren'Py save folder that config.save_directory names, for example %APPDATA%/RenPy on Windows and ~/Library/RenPy on macOS.
Keep the batch and wait longer before each retry after a network error or a 5xx, 408 or 429 response. Drop it after any other 4xx, because the collector refused the data and a retry gets the same answer. The flush also drops events older than 7 days, because one old event refuses the whole batch with 400.
Until persistent.mana_consent is True, mana_track() does nothing and no ID is written. mana_set_consent(False) deletes the ID and the queue. Whether your game needs consent is a decision for you and your legal advisers.
Sources: Ren'Py documentation, Persistent Data and Configuration Variables; Manalens app events documentation.
What changes for web, desktop and mobile builds?
Ren'Py builds for Windows, macOS, Linux, Android, iOS and the web from one project. renpy.fetch() works on all of them, with these differences.
- Desktop: no Origin header, so the collector accepts the request with the Publishable key alone.
- Web: Ren'Py docs say sockets and the requests module do not work in the web build, but renpy.fetch() does, under the same CORS rules as any web page. The x-publishable-key header causes a CORS preflight, which the collector answers for your project domain, its subdomains and Allowed origins.
- itch.io: upload the web build zip. The game runs from an itch.zone host, and *.itch.zone is allowed by default.
- Web threads: the web build has no threading module and no renpy.invoke_in_thread(), so keep fetch() in the main thread on every platform.
- Android and iOS: use an https:// endpoint, because both block cleartext HTTP by default. On mobile, Ren'Py saves when the app goes to the background (config.save_on_mobile_background), but there is no quit callback you can count on, so events wait for the next launch.
Sources: Ren'Py documentation, Web and HTML5, Android and Fetching Data from the Web; Manalens app events documentation.
What are the Ren'Py gotchas?
Most of these come from the way Ren'Py saves and rolls back data.
- The headers argument of renpy.fetch() is new in Ren'Py 8.3. On 8.2 the call fails, so the key never reaches the collector and the queue only grows.
- Do not keep the queue in a normal store variable. Variables that change after init go into save files and rollback, so loading a save restores an old queue. Use persistent fields and class attributes, as in the code.
- renpy.fetch() inside a screen action or a periodic callback freezes the display until the request ends or times out (5 seconds by default). Call it from a $ line in a label.
- Any response that is not a success raises an exception. The code reads the status code from the exception when it has one, and treats a missing status, such as a timeout, as a reason to retry.
- Players can delete persistent data from the launcher or the web menu. That gives them a new anonymous ID, which counts as a new player. Datetime isoformat() gives +00:00, which the collector refuses: use the Z form.
Sources: Ren'Py documentation, Fetching Data from the Web, Persistent Data and Save, Load and Rollback; Ren'Py changelog, 8.3.0.
How do I check that Ren'Py events arrive?
Send one batch from a development build and read the response status. Add a temporary $ renpy.notify(str(len(persistent.mana_queue))) after the flush: 0 means the batch was accepted.
- Create a test project in Manalens and copy its Publishable key.
- Launch the project from the Ren'Py launcher, accept consent, and play to the first $ mana_flush() line.
- Send game_open and session_start from the Ren'Py build, then check that the response is {"accepted":2}.
- Open the activity feed and check that platform, build and engine are set on the events.
- Switch off the network, play for a minute, switch it on, and check that the queued events arrive once.
- 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.rpy, ask for consent once, and use funnels to see which chapter and which choice lose the most readers.
Sources: Manalens product documentation.
Frequently asked questions
Which Ren'Py version do I need?
Ren'Py 8.3 or later. renpy.fetch() arrived in Ren'Py 8.2, but the headers argument came in 8.3, and the collector needs the Publishable key in the x-publishable-key header. On 8.2 the call fails, so update the SDK before you add analytics to your visual novel.
Where should I store the analytics queue in Ren'Py?
In persistent data, not in a normal store variable. Persistent fields belong to no save slot and no rollback, so loading a save does not bring back old events or a different player ID. Call renpy.save_persistent() after each change, so a crash does not lose queued events.
Does renpy.fetch() work in the web build?
Yes. The Ren'Py docs say sockets and the requests module do not work on the web, but renpy.fetch() does, under normal CORS rules. The collector answers the CORS preflight for your project domain and Allowed origins, and *.itch.zone is allowed by default for itch.io uploads.
Why does my game freeze for a few seconds?
Because renpy.fetch() ran inside an interaction, such as a screen action or a periodic callback. There it blocks the display until the request ends or times out after 5 seconds. Call mana_flush() from a $ line in a label, where Ren'Py waits without locking up.
Sources and implementation
- Ren'Py documentation: Fetching Data from the Web (read 18 November 2026) ↗
- Ren'Py documentation: Persistent Data (read 18 November 2026) ↗
- Ren'Py documentation: Configuration Variables (read 18 November 2026) ↗
- Ren'Py documentation: Save, Load and Rollback (read 18 November 2026) ↗
- Ren'Py documentation: Web and HTML5 (read 18 November 2026) ↗
- Ren'Py documentation: Changelog (8.2.0 and 8.3.0) (read 18 November 2026) ↗
- Python documentation: uuid.uuid4() (read 18 November 2026) ↗