feat: itch.io source

[ItachiSan]

Implemented a source for itch.io.
The source takes care of navigating through the various steps, simulating what happens in the browser.

Important notice
The code has been mainly generated via Gemini CLI under supervision.

[ItachiSan]

Thanks for the feedback! I will address the issues ASAP. 😉

[ItachiSan]

Hi! I went over all the code and did a major brush up.

Overall all the issues should be solved.

For URLs I used for testing, these are the ones I used:

• https://dragonrod342.itch.io/digital-tamers-2
• https://wideball-studios.itch.io/micro-gaelic-football
• https://meiri.itch.io/the-narrator-says-were-meant-to-be
• https://devilinlovegames.itch.io/the-winter-wedding
• https://justcore.itch.io/burning-snow (should fail)

Overall, any download here should work:

https://itch.io/games/free/platform-android

And downloads from here without Android should not:

https://itch.io/games/free

An important notice is that paid games are not supported, as in here:

https://meant-to-bee-studios.itch.io/criminally-yours

This has an Android download that requires payment.
Since it is associated to being logged in, Obtanium would need to support a WebView for login, but it doesn't seem available to me.

As a possible improvement, I would like to know whether it is possible to avoid downloading the APK when adding the app in Obtanium; it seems the assetsUrl is called when adding an app no matter what.

[ImranR98]

Thanks!
We need to know an app's package ID when we add it, that's why we download the APK. In some cases like f-droid, that's not necessary because the package id can already be inferred (in this case through the URL). If there is a way to infer the package ID from itch.io without downloading the APK, then you can define the inferAppId function for that (the name might be wrong, but it's something along those lines, can't check right now).

[ItachiSan]

There is no consistent way to infer the ID; even the version is a problem 🤣
Is there an option to infer the version from the APK?

[toast-riot]

@ItachiSan
I'd really to see this implemented, and I happened to be looking into exactly this topic only just today. I've collected some really useful info for this implementation.

---

data.json
Endpoint: {GAME_URL}/data.json

This is the easiest way to get the game's ID. Does not require any authentication.
Example

---

api.itch.io
This API requires an API key, but is exceptionally useful and is fully supported by Itch. The documentation for this API is (kinda) here, but it doesn't list the API endpoints themselves, so I've extracted the URLs from Itch.io's tool Butler. The API key is passed as the Authorization header.

For general game info: https://api.itch.io/games/{GAME_ID}
Example (you will need to be logged in)
Returns a Game struct.

For updates: https://api.itch.io/games/{GAME_ID}/uploads
Example (you will need to be logged in)
This lists almost everything we need. The notable fields in each upload are:

Info	Example
display_name	"DigitalTamers02 - v1.1.5 (Android)"
filename	"DigitalTamers02 - Android.apk"
updated_at	"2026-02-21T02:13:26.000000000Z"
md5_hash	"d1973ac6f6c42da8f205f7c0800158c8"
traits	["p_android"]

(p_android means "supports Android")

I would highly recommend that this API is used. Also, creating an API key is very easy:

1. Create an account (you don't even need to verify an email address)
2. Go to settings/api-keys
3. Click "Generate new API key"

---

Notes

I've omitted a lot of the info I found, mostly on APIs that aren't consistent, officially supported or useful for this particular case. One example is Wharf, which can be used to return the latest version very easily, but only works on a small percentage of games.

Also, there's an API for getting download URLs, so I'll look into that now.

[toast-riot]

The idea with my suggestion is to limit the browser-level stuff and use the APIs, hopefully resulting in a much more robust (and performant) implementation.

[toast-riot]

Yeah looks like downloads are quite simple too:
https://itch.io/api/1/{API_KEY}/upload/{UPLOAD_ID}/download. This returns {url: "https://example.com"} with the download URL for the game files.

Also, this should work with paid-only games, though I have no way of testing that.

Hope all this info helps :)

[ItachiSan]

Hello!
Thanks for the input @toast-riot.

I believe the current implementation will suffice, since all API access does require an API key and Obtanium works normally without the need for it (although it recommends for specific providers).

There could be an alternative "API" handler that avoids the web scraping and uses the API directly.
Then, the ItchIo class could work as:

1. If API key has been provided use the API handler
2. Otherwise, use the web scraper handler

I think input from @ImranR98 is needed for choosing the direction forward. 😄

[toast-riot]

Since it is associated to being logged in, Obtanium would need to support a WebView for login [...]
I believe the current implementation will suffice, since all API access does require an API key and Obtanium works normally without the need for it [...]

Not needing to use an API key does save the user a few steps. I figured that since the user (according to your earlier message, at least) needed to be logged in, having them create an API key wouldn't be too difficult. That said, I'm the type to trade ease of use for performance and robustness hahaha :)

There could be an alternative "API" handler that avoids the web scraping and uses the API directly.
Then, the ItchIo class could work as:
If API key has been provided use the API handler
Otherwise, use the web scraper handler

This gets the best of both worlds, and sounds like a good solution to me. Users can get it working quickly and easily without a key, but for power-users a key can be provided.

Hopefully API access isn't too complex to implement (at least, it seems like it should be straightforward). I would add it myself but uhhhh... I don't know dart whatsover 😅