Support tracking Kobo Reading Sessions

[im-eliminator]

What would you like Grimmory to do?

The stock Kobo software is able to track various usages of the ereader. This includes when a book is read, for how long, and can also track rating a book. If Grimmory were to process the events that are sent during a Kobo sync, the data can be persisted in the database.

What problem does this solve for you?

This helps keep track of a book's reading sessions.

Anything else?

I took an stab at an initial implementation: https://github.com/im-eliminator/grimmory/tree/kobo-events

Been running this locally for a few days and it has been keeping track of my reading sessions and allowed me to rate the book on my reader and have it reflected in Grimmory.

Want to help out?

Yes! I'd love to help implement this

Before submitting

• I've searched existing discussions and this hasn't been suggested yet
• I've reviewed this report and have completed it as fully as I can

[imnotjames]

This is interesting for tracking reading sessions for sure.

This information isn't pushed over from the reading state endpoint?

[imnotjames]

For the rating, there is an explicit endpoint for rating we should be hooking into: /v1/products/{book_id}/rating/{rating}. If that's something you'd like to implement I can open a feature request for it. Could be cool.

[im-eliminator]

The Kobo UI itself allows you to rate a book (1 to 5 stars) and that's intended to be sent to the Kobo store. I found that there's a RateBook event that gets send during the sync. I just called the BookUpdateService.updatePersonalRating() call since the handler is already running in the sync process.

[AnonTester]

This would cover my feature request here: https://github.com/orgs/grimmory-tools/discussions/631

[im-eliminator]

The current Kobo sync function does quite well at keep track of a book's progress but it doesn't track individual reading session. I wanted to get the individual sessions to populate the reading stats. For example, I can get the following now:

[imnotjames]

Right - but the same information may be getting pushed to /v1/library/{book_id}/state - I see some similar data there which we currently are not translating to reading sessions. This endpoint uses the book ID, too, rather than the title so you don't have to lookup the book by title.

[im-eliminator]

Interesting. I hadn't noticed that. I'll take a look.

[im-eliminator]

I checked the data sent by Kobo during a few sync tests and see what you're saying. Both the /v1/library/{book_id}/state and events can track the amount of time spent reading a book but they handle things a little differently. Here's an example:

simplified payload to the v1/library/{book_id}/state API:

      "EntitlementId": "1",
      "LastModified": "2026-04-26T19:58:39Z",
      "Statistics": {
        "LastModified": "2026-04-26T19:58:39Z",
        "RemainingTimeMinutes": 153,
        "SpentReadingMinutes": 9
      },

Based on this, we have the last read timestamp and that 9 minutes were spent reading the book since the last sync.

simplified events data:

      "Timestamp": "2026-04-26T16:42:52Z", "Metrics": { "IdleTime": 5, "PagesTurned": 7, "SecondsRead": 194 },
      "Timestamp": "2026-04-26T16:46:17Z", "Metrics": { "IdleTime": 3, "PagesTurned": 5, "SecondsRead": 134 },
      "Timestamp": "2026-04-26T18:14:59Z", "Metrics": { "IdleTime": 3, "PagesTurned": 12, "SecondsRead": 221 },
      "Timestamp": "2026-04-26T19:58:39Z", "Metrics": { "IdleTime": 3, "PagesTurned": 0, "SecondsRead": 3 },

This shows 4 reading events since the last sync which totals about 9 minutes.

Not sure if I missed something during my tests but it looks like the /state approach is too coarse grained to capture reading sessions, esp. when the time between syncs is long.

[naivchan]

Just wanted to say that I would love if the Kobo and Koreader reading sessions were able to feed back to Grimmory somehow, I don't read in the web reader at all so the entire reading sessions area isn't usable for me.

Also, since I'm reading on two different devices, the Kobo reading times only show the time spent on device, so it would be helpful to know how much time you spent on a book overall.

[gaetan-petit]

Hi @im-eliminator do you think you'll open a PR from your branch?

[im-eliminator]

I can certainly do that if people are interested in the change.

[gaetan-petit]

@im-eliminator It was added to the project roadmap: #1506 (comment)
So there's definitely some interest.

[im-eliminator]

Been a bit busy and missed this update. Let me rebase my branch and test to make sure it's working with the latest code.