From 66f7c5c5f8c3c19baa1086715b97420d8b6ea232 Mon Sep 17 00:00:00 2001 From: Jason Rebelo Date: Mon, 29 May 2023 02:08:00 +0200 Subject: [PATCH] :memo: README cleanup (#5) --- README.md | 54 ++---------------------- src/MatomoProvider/MatomoProvider.csproj | 44 +++++++++---------- src/MatomoProvider/README.md | 50 ++++++++++++++++++++++ 3 files changed, 76 insertions(+), 72 deletions(-) create mode 100644 src/MatomoProvider/README.md diff --git a/README.md b/README.md index 83ea35b..b81d675 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # MatomoProvider -

+

Nuget GitHub Workflow Status (with branch)

@@ -9,60 +9,14 @@ This component is based on [cmoissl's `Blazor.Matomo`](https://github.com/cmoissl/Blazor.Matomo) component but adapted to provide extra functionality, with a focus on Blazor WASM's SPA nature. -Some of the recommendations from [Matomo's SPA tracking documentation](https://developer.matomo.org/guides/spa-tracking) has been applied to allow proper page, page title, referrer URL, and user id tracking. Other features may follow. +Some of the recommendations from [Matomo's SPA tracking documentation](https://developer.matomo.org/guides/spa-tracking) have been applied to allow proper page, page title, referrer URL, and user id tracking. Other features may follow. -## Usage - -Install the [MatomoProvider](https://www.nuget.org/packages/MatomoProvider/) package. - -### Registering the component - -The recommended way to use `MatomoProvider` is to add it to the bottom of your `App.razor` file: - -```diff - - ... - - -+@* Register matomo provider application-wide *@ -+ - - @code { - - [Inject] - private MatomoOptions _matomoOptions { get; set; } = default!; - - } -``` - -You must provide: - -- `ApiUrl`: the endpoint at which your Matomo instance is hosted -- `SiteId`: your Matomo website id - -You may provide: - -- `UserIdFunc`: a function returning the user id to set for the current user - -### Adding the script reference - -`MatomoProvider` comes bundled with a Javascript file which needs to be added as a script reference in `wwwroot/index.html` for Blazor WASM and `Pages/_Host.cshtml` for Blazor Server: - -```diff - - ... - - -+ - -``` +More details in the [documentation](./src/MatomoProvider/README.md). ## Development For ease of development, a docker image has been provided (`/tools/matomo`) that sets up a `mariadb` and a `matomo` instance. -After starting up this docker image, follow the setup instructions (at http://localhost), this should be limited to pressing "next" until asked to create an admin account. +After starting up this docker image, follow the setup instructions (at [http://localhost](http://localhost)), this should be limited to pressing "next" until asked to create an admin account. Once the setup is complete no extra configuration needs to be made, the samples should work as-is. diff --git a/src/MatomoProvider/MatomoProvider.csproj b/src/MatomoProvider/MatomoProvider.csproj index 8703679..f56882e 100644 --- a/src/MatomoProvider/MatomoProvider.csproj +++ b/src/MatomoProvider/MatomoProvider.csproj @@ -1,4 +1,4 @@ - + Jason Rebelo Neves (igotinfected) MatomoProvider is a Blazor component that registers and enables the Matomo Analytics tracking code for you.code for you. @@ -7,37 +7,37 @@ MIT - - + + README.md - + - - net7.0 - enable - enable - - - - - - - + + net7.0 + enable + enable + + + + + + + runtime; build; native; contentfiles; analyzers; buildtransitive all - - - + + + runtime; build; native; contentfiles; analyzers; buildtransitive all - - - - + + + + diff --git a/src/MatomoProvider/README.md b/src/MatomoProvider/README.md new file mode 100644 index 0000000..d34cf30 --- /dev/null +++ b/src/MatomoProvider/README.md @@ -0,0 +1,50 @@ +`MatomoProvider` is a Blazor component that registers and enables the [Matomo Analytics](https://matomo.org/) tracking code for you. + +This component is based on [cmoissl's `Blazor.Matomo`](https://github.com/cmoissl/Blazor.Matomo) component but adapted to provide extra functionality, with a focus on Blazor WASM's SPA nature. + +Some of the recommendations from [Matomo's SPA tracking documentation](https://developer.matomo.org/guides/spa-tracking) have been applied to allow proper page, page title, referrer URL, and user id tracking. Other features may follow. + + +### Registering the component + +The recommended way to use `MatomoProvider` is to add it to the bottom of your `App.razor` file: + +```diff + + ... + + ++@* Register matomo provider application-wide *@ ++ + + @code { + + [Inject] + private MatomoOptions _matomoOptions { get; set; } = default!; + + } +``` + +You must provide: + +- `ApiUrl`: the endpoint at which your Matomo instance is hosted +- `SiteId`: your Matomo website id + +You may provide: + +- `UserIdFunc`: a function returning the user id to set for the current user + +### Adding the script reference + +`MatomoProvider` comes bundled with a Javascript file which needs to be added as a script reference in `wwwroot/index.html` for Blazor WASM and `Pages/_Host.cshtml` for Blazor Server: + +```diff + + ... + + ++ + +```