{"id":20218100,"url":"https://github.com/matrix-org/matrix-analytics-events","last_synced_at":"2025-04-10T15:46:10.693Z","repository":{"id":38299813,"uuid":"426237456","full_name":"matrix-org/matrix-analytics-events","owner":"matrix-org","description":"Cross-platform definitions of analytics events raised by matrix SDKs","archived":false,"fork":false,"pushed_at":"2024-11-05T18:00:44.000Z","size":667,"stargazers_count":9,"open_issues_count":10,"forks_count":9,"subscribers_count":20,"default_branch":"main","last_synced_at":"2024-12-06T21:35:01.166Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matrix-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-09T13:21:21.000Z","updated_at":"2024-12-02T01:42:38.000Z","dependencies_parsed_at":"2023-02-08T10:30:27.144Z","dependency_job_id":"e87b0085-404b-4477-973f-6f3239c72d6c","html_url":"https://github.com/matrix-org/matrix-analytics-events","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-analytics-events","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-analytics-events/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-analytics-events/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-analytics-events/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-org","download_url":"https://codeload.github.com/matrix-org/matrix-analytics-events/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248243512,"owners_count":21071055,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T06:37:14.946Z","updated_at":"2025-04-10T15:46:10.673Z","avatar_url":"https://github.com/matrix-org.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# matrix-analytics-events\n\nThis repository contains JSON schema defining analytics events raised by the Matrix client SDKs.\n\nIt also contains a generator of type stubs for these events which can be used by the client SDKs. Using these stubs\nensures events raised comply with the schema via compile-time type verification.\n\nYou can find an [overview of the analytics events here](https://matrix-org.github.io/matrix-analytics-events/).\n\n## Schemas\n\n`/schemas` contains one JSON schema file per event, each named exactly according to the name of that event\n(case-sensitive).\n\n`/types` contain type stubs generated from these schemas in the different client languages we support.\n\n## Generating new type stubs\n\nAfter creating or updating an event schema, you need to generate new type stubs and commit them along with your changes\nto the events.\n\nTo install the stub generator (only needed once), you'll need on your system\n\n* yarn\n* python 3.10+\n* [poetry](https://python-poetry.org/docs/#osx--linux--bashonwindows-install-instructions)\n\nFor me, the easiest way to install python 3.10 was via [pyenv](https://github.com/pyenv/pyenv),\nthen poetry was happy to recognise it after running `pyenv local 3.10.0`.\n\nThen run\n\n```\nscripts/setup.sh\n```\n\nTo generate the stubs:\n\n```\nyarn build\n```\n\n## Guidelines for creating new event schema\n\n* One schema per .json. The filename should match the event's name, including case.\n* Each schema should contain an `eventName` property declared as an `enum` with a single value.\n  This convention can be relied upon by consumers of stubs as a way to get the correct name to send for that event.\n\n  For example:\n\n```json\n\"eventName\": {\n  \"enum\": [\"Error\"]\n},\n```\n\n* You must describe your event using `description` fields. Your audience might be unfamiliar with the codebase,\n  or non-technical, so don't refer to code concepts and try to describe things in general but accurate terms. English grammar must be respected, in particular sentences must end with punctuation (eg a period).\n\n### Description examples\n\n#### Events\n\n```json\n{\n  \"type\": \"object\",\n  \"description\": \"Triggered when the user changed screen.\",\n  \"properties\": {\n    \"eventName\": {\n      \"enum\": [\"Screen\"]\n    }\n  }\n}\n```\n\n#### Primitive properties\n\n```json\n\"durationMs\": {\n  \"description\": \"How long the screen was displayed for in milliseconds.\",\n  \"type\": \"integer\"\n}\n```\n\n#### Enums\n\n```json\n\"screenName\": {\n  \"type\": \"string\",\n  \"oneOf\": [\n    {\"const\": \"Welcome\", \"description\": \"The splash screen.\"},\n  ]\n}\n```\n\n## Releasing\n\nUse \"[Run workflow](https://github.com/matrix-org/matrix-analytics-events/actions/workflows/release.yaml)\".\nRefer to [SemVer](https://semver.org/) for versioning semantics.\nThis workflow will bump the version, publish NPM and create a GitHub release.\nThe Swift consumer uses [SwiftPM](./Package.swift) and can target the latest released version, the Kotlin consumer pulls this repo weekly.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-analytics-events","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-org%2Fmatrix-analytics-events","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-analytics-events/lists"}