HTML5 game: send app events

Send app events (an app context and no page URL) from the game code, or add the web SDK snippet with the app option. itch.io runs the build in an iframe on an itch.zone host, and the collector accepts a web event when its page URL is on a host in Allowed origins (*.itch.zone by default). Inside the iframe it sees the itch.io game host, not the itch.io page, so the UTM tags and referrer of that page are not visible. A Unity WebGL build or a Godot web export with our SDK sends app events for you. A JavaScript game posts them to the events endpoint. The app context marks every event as coming from the itch.io build, so the App filters (build, version, platform, storefront) work.

JavaScript in the HTML5 build: one app event

fetch('https://YOUR_COLLECTOR_ENDPOINT/v0/events', {
  method: 'POST',
  headers: { 'x-publishable-key': 'YOUR_PUBLISHABLE_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ events: [{
    type: 'track', event: 'level_complete', channel: 'app', version: '1.4.0',
    message_id: crypto.randomUUID(), anonymous_id: playerId, session_id: sessionId,
    original_timestamp: new Date().toISOString(),
    context: { app: { platform: 'web', storefront: 'itch', app_version: '1.4.0', build: '571', engine: 'other' } },
    properties: { level: 3 },
  }] }),
});

Unity WebGL or downloadable builds

In Unity, set Storefront = "itch" in the SDK options. The Godot SDK has the same storefront option. A downloadable build sends game_open with is_first_open on the first launch, so installs show on the Attribution Installs tab.

C#

Manalens.Init(new ManalensOptions
{
    PublishableKey = "YOUR_PUBLISHABLE_KEY",
    Endpoint = "https://YOUR_COLLECTOR_ENDPOINT",
    Storefront = "itch",
});

Connect the itch.io API

You need the owner or admin role and a verified MFA session. The sync runs once a day.

Purchases match only an email that your server sent with the Secret key in an identify event. Send only an address that you verified. Only payments are recorded; free key claims are not.

  1. Create an API key in your itch.io account settings, under API keys.
  2. In Manalens, open Settings, Integrations, itch.io, paste the key and choose the game.
  3. Send an identify event with the verified email from your server.
  4. Select Sync now. Each purchase becomes an purchase event with the channel itch (a donation has the property donation).

Verify the installation

Open the game on its itch.io page and check that events appear in the project activity feed. Choose itch.io in the Overview source picker to see views, downloads, purchases and earnings from the itch.io API. To refuse itch.io builds, remove *.itch.zone from Project settings, Allowed origins.

Frequently asked questions

Can I add the snippet to my itch.io project page?

No. The itch.io project page only offers a field for a Google Analytics 4 measurement ID. Add the SDK to the game build instead. For an HTML5 game, send app events from the game code or add the web SDK snippet to the build; both work in the itch.io iframe. For a downloadable build, set Storefront to itch.

Do I need to change allowed origins for itch.io?

No. itch.io serves HTML5 builds from itch.zone hosts, and every project allows *.itch.zone by default. So app events from a Unity WebGL build, a Godot web export or your own code, and the web SDK snippet in the build, arrive without setup. To refuse itch.io builds, remove *.itch.zone from Allowed origins.

How are itch.io purchases recorded?

Connect an itch.io API key under Settings, Integrations, itch.io, and choose the game. The sync runs once a day. Each purchase becomes an purchase event with the channel itch (a donation has the property donation). A purchase matches only an email that your server sent with the Secret key in an identify event.

Sources and implementation