PiwikPRO

The official Piwik PRO .NET SDK — the complete package. This meta-package installs everything you need to integrate Piwik PRO analytics and tracking into your .NET 8 application.

Installation

dotnet add package PiwikPRO

This installs both PiwikPRO.Analytics and PiwikPRO.Tracking (which include PiwikPRO.Core automatically).

Tip: If you only need analytics or only tracking, install the individual packages to keep your dependency footprint smaller.

Prerequisites

You need credentials from your Piwik PRO instance:

1. Log in to your Piwik PRO account
2. Go to Menu > Profile > API Keys to create an OAuth client (Client ID + Client Secret)
3. Find your Website ID under Administration > Sites & Apps

Quick Start

using PiwikPRO.Analytics.Extensions; using PiwikPRO.Tracking.Extensions; var builder = WebApplication.CreateBuilder(args); // Register analytics services (query builder, sessions, real-time events, goals) builder.Services.AddPiwikProAnalytics(options => { options.BaseUrl = "https://your-instance.piwik.pro"; options.ClientId = "your-client-id"; options.ClientSecret = "your-client-secret"; options.WebSiteId = "your-website-id"; }); // Register tracking services (server-side tracking, JS code generation) builder.Services.AddPiwikProTracking(options => { options.BaseUrl = "https://your-instance.piwik.pro"; options.ClientId = "your-client-id"; options.ClientSecret = "your-client-secret"; options.WebSiteId = "your-website-id"; });

Query Analytics Data

using PiwikPRO.Analytics; using PiwikPRO.Analytics.Constants; public class DashboardService { private readonly IAnalyticsService _analytics; public DashboardService(IAnalyticsService analytics) => _analytics = analytics; public async Task<QueryResponse> GetVisitorsByDate() { return await _analytics.QueryAsync(builder => builder.AddDimension(Dimensions.Date.DateDimension) .AddMetric(Metrics.Sessions.Visitors) .AddMetric(Metrics.Pages.PageViews) .SetLastDays(30) .OrderByDescending(Metrics.Sessions.Visitors) .Limit(100)); } }

Track Events Server-Side

using PiwikPRO.Tracking; public class EventService { private readonly ITrackingService _tracking; public EventService(ITrackingService tracking) => _tracking = tracking; public async Task TrackPurchase() { await _tracking.TrackPageViewAsync( url: "https://example.com/checkout/complete", actionName: "Purchase Complete"); await _tracking.TrackGoalAsync(goalId: "purchase-goal", revenue: 99.99m); } }

Generate JavaScript Tracking Code

using PiwikPRO.Tracking; var trackingCode = codeGenerator.GenerateTrackingCode(); var tagManagerCode = codeGenerator.GenerateTagManagerTrackingCode();

Configuration Options

Property	Type	Default	Description
BaseUrl	string	Required	Your Piwik PRO instance URL
ClientId	string	—	OAuth client ID
ClientSecret	string	—	OAuth client secret
AccessToken	string?	—	Static access token (alternative to OAuth)
WebSiteId	string?	—	Default website ID (can be overridden per query)
TimeoutSeconds	int	30	HTTP request timeout
EnableRateLimitHandling	bool	true	Automatic retry on HTTP 429 and 5xx errors
MaxRetryAttempts	int	3	Maximum retry attempts
RetryDelaySeconds	int	2	Base delay between retries (exponential backoff)
MaxRetryDelaySeconds	int	30	Maximum delay between retries

What's Included

PiwikPRO.Analytics

• Fluent Query Builder — Build analytics queries with method chaining
• Strongly-Typed Constants — Predefined dimensions (Dimensions.*) and metrics (Metrics.*)
• Date Range Utilities — DateRangeUtilities.LastDays(30), .CurrentMonth(), .CurrentQuarter(), etc.
• Filtering — WhereContains, WhereIn, WhereEquals and more
• Aggregations — Sum, Average, Min, Max, UniqueCount
• Sessions & Real-Time Events — Access raw session and real-time data
• Goals Management — CRUD operations for goals
• Streaming — IAsyncEnumerable support for large datasets

PiwikPRO.Tracking

• Server-Side Tracking — Page views, events, goals, downloads, outlinks, site searches
• JavaScript Code Generation — Tracking snippets and Tag Manager code
• Custom Dimensions — Attach custom data to tracking events

PiwikPRO.Core (included automatically)

• OAuth 2.0 Authentication — Automatic, thread-safe token refresh
• Resilient HTTP Client — Retry with exponential backoff and jitter
• Rate Limit Handling — Automatic HTTP 429 retry, honors Retry-After headers

Individual Packages

Package	Description
PiwikPRO.Analytics	Analytics and reporting only
PiwikPRO.Tracking	Server-side tracking only
PiwikPRO.Core	Core infrastructure only