CleanInsights

class cleaninsights.CleanInsights(conf: Configuration | PathLike | str, store: Store)

Core class for the CleanInsights SDK.

classmethod auto_track(storage_dir: Path, server: str, site_id: int, campaigns: Dict[str, Campaign] | None = None) CleanInsights

Instantiates a singleton CleanInsights object with a default configuration and a default campaign named “visits” which never expires.

The “visits” campaign will have an aggregation_period_length of 1 day. That means, starts will be collected during 24 hours and then sent to the server, evenly distributed over that day, in order to keep user privacy.

After instantiation, it will automatically track a start of the app, but ONLY, if consent is given.

You will need to show some consent form to the user, so the user is able to agree to this tracking before setting consent.

Refer to the example code to see how consent is handled.

Parameters:
  • storage_dir – The directory the store will be located in.

  • server – The server URL should look like https://myhost.example.com/ci/cleaninsights.php.

  • site_id – The Matomo site ID to record page visits for.

  • campaigns – (Additional) campaign configurations.

Returns:

The instantiated CleanInsights object.

property campaign_consents: List[str]
consent_for_campaign(campaign_id: str) CampaignConsent | None

Returns the consent for a given campaign, if any available.

Parameters:

campaign_id – The campaign ID to get the consent for.

Returns:

The CampaignConsent for the given campaign or None, if consent unknown.

consent_for_feature(feature: Feature) FeatureConsent | None

Returns the consent for a given feature, if any available.

Parameters:

feature – The feature to get the consent for.

Returns:

The FeatureConsent for the given feature or None, if consent unknown.

deny_campaign(campaign_id: str)
deny_feature(feature)
property feature_consents: List[str]
grant_campaign(campaign_id: str) CampaignConsent | None
grant_feature(feature)
is_campaign_currently_granted(campaign_id: str) bool
measure_event(category: str, action: str, campaign_id: str, name: str | None = None, value: int | float | None = None)

Track an event.

Parameters:
  • category – The event category. Must not be empty. (e.g. Videos, Music, Games…)

  • action – The event action. Must not be empty. (e.g. Play, Pause, Duration, Add Playlist, Downloaded, Clicked…)

  • campaign_id – The campaign ID as per your configuration, where this measurement belongs to.

  • name – The event name.

  • value – The event value.

measure_visit(scene_path: List[str], campaign_id: str, timestamp: datetime | None = None)

Track a scene visit.

Parameters:
  • scene_path – A hierarchical path best describing the structure of your scenes. E.g. [‘Main’, ‘Settings’, ‘Some Setting’].

  • campaign_id – The campaign ID as per your configuration, where this measurement belongs to.

  • timestamp – Optional timestamp when the visit happened for use in retrograde log analysis and such. Ignored, when Configuration.server_side_anonymous_usage is False!

persist()

Persist accumulated data to the filesystem.

An app should call this when the process exits for whatever reason.

state_of_campaign(campaign_id: str) ConsentState

Checks the consent state of a campaign.

Parameters:

campaign_id – The campaign ID to check the consent state of.

Returns:

The current state of consent.

state_of_feature(feature: Feature) ConsentState

Checks the consent state of a feature.

Parameters:

feature – The feature to check the consent state of.

Returns:

The current state of consent.

test_server(done: Callable[[Exception | None], None])

Sends an empty body to the server for easy debugging of server-related issues like TLS and CORS problems.

DON’T LEAVE THIS IN PRODUCTION, once you’re done fixing any server issues. There’s absolutely no point in pinging the server with this all the time, it will undermine your privacy promise to your users!

Parameters:

done – Callback, when the operation is finished, either successfully or not.