PiwikPRO 1.0.1

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

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