How to send a Heartbeat via HTTP Tracking API

Support & Bugs
1

Hi all!

I am developing an open-source tool to send realtime data from Icecast and Shoutcast to Matomo. I would like to track when a user connects to a stream until he disconnects in realtime (users usually spend hours listening to a stream).

I think this could be achieved doing something similar to the Heartbeat that the JS Tracking client provides: JavaScript Tracking Client: Integrate - Matomo Analytics (formerly Piwik Analytics) - Developer Docs - v3

I have not been able to find that function on the HTTP Tracking API, how can I achieve that?

Basically I want to track this:

  • User connects to a stream /myradio.mp3 -> Add user to Matomo
  • User is still connected -> Send heartbeat to Matomo
  • [ repeat while user is connected ]
  • User stop listening to the stream -> End session in Matomo

I also havenā€™t figured out how to mark an user as disconnected instantly. Seems like Matomo mark a user as disconnected after the ā€œvisit_standard_lengthā€ timeout is over: How is a ā€˜visitā€™ defined in Piwik? - Analytics Platform - Matomo Is there a way to actively mark a user as disconnected/session has finished so I donā€™t need to wait for the timeout?

Every help will be appreciated. I havenā€™t found any tool that covers realtime analytics for streaming servers, and I think this would be a nice addition to the open source world.

2

Hi,

Good news, the ping parameter is finally documented here:
https://developer.matomo.org/api-reference/tracking-api

3

Amazing! Thanks.

I think there is no way to actively end a user session, so I think I will setup a short ā€œvisit_standard_lengthā€ and send a ping for every online user a little before the session times out.

1 Like
4

Hi @Lukas,

I have tried using that parameter, and I think I am not getting the described behaviour.

I have setup the visit length as 60 seconds:

[Tracker]
visit_standard_length = 60

And, after the first visit, I keep sending a heartbeat every 10 seconds (the same request but with ping=1).
It works great during 60 seconds, as the visit time increases, and the user is shown on the ā€œReal time visitor Countā€ and the ā€œReal time mapā€, so far so good, but after the ā€œvisit_standard_lengthā€ passes (60 seconds), the user disappears from those widgets, and marked visit finished.

I understand that this shouldnā€™t happen with ping=1, instead, the user should be kept online and the session time running as long as I keep sending those events, right?

Please, find here [JSON] matomo_logs - Pastebin.com the logs returned from the tracking API, together with the payload that I am sending to matomo.

You can see how before the 60s the tracking API returns:

DEBUG: Visit is known (IP = 178.193.1.1)
DEBUG: Updated existing visit: array (
DEBUG:   'idvisitor' => '0000000000030854',
DEBUG:   'visit_total_time' => 52,
DEBUG: )

and after that:

DEBUG: The visitor was not matched with an existing visitor...

Thanks!

5

This is currently expected behaviour see Fix total time of visit is not the sum of times of page visits if heartbeat feature is used by tsteur Ā· Pull Request #9617 Ā· matomo-org/matomo Ā· GitHub

The ping is not there to extend the visit, only to report more accurate visit length time, especially when there is only one page view in a visit.

It would need basically a new option to keep the visit active as well.

1 Like
6

Thanks for the answer @thomas_matomo, I guess I didnā€™t understand what ping does.

Then, I donā€™t see a way of being able to define a user visit length accurately, or am I missing something?

7

Iā€™m not quite sure what you are trying to achieve. Can you set visit_standard_length for example to an hour or longer and then the visit length would be more accurate maybe?

8

I agree with @xipher and I have the same concern. Ping is enabled, but visits donā€™t get counted past their default lifetime. I think this behavior should be modified. Do you agree? It would better match the counters on Chartbeat and Google Analytics, which keep counting a visitor as long as the page is open.