PiwikPRO.Analytics 1.0.1

PiwikPRO.Analytics

Official Piwik PRO .NET SDK for analytics and reporting. Query your Piwik PRO data using a fluent API, access sessions and real-time events, manage goals, and stream large datasets.

Installation

dotnet add package PiwikPRO.Analytics

This automatically installs PiwikPRO.Core with authentication and HTTP infrastructure.

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

Register Services

using PiwikPRO.Analytics.Extensions;

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";
});

Or with a static access token:

builder.Services.AddPiwikProAnalytics(options =>
{
    options.BaseUrl = "https://your-instance.piwik.pro";
    options.AccessToken = "your-access-token";
    options.WebSiteId = "your-website-id";
});

Fluent Query Builder

using PiwikPRO.Analytics;
using PiwikPRO.Analytics.Constants;

public class MyService
{
    private readonly IAnalyticsService _analytics;

    public MyService(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));
    }
}

Filtering

var response = await _analytics.QueryAsync(builder =>
    builder.AddDimensions(Dimensions.Page.PageUrl, Dimensions.Device.Browser)
           .AddMetrics(Metrics.Sessions.Visitors, Metrics.Sessions.BounceRate)
           .SetDateRange("2025-01-01", "2025-12-31")
           .WhereContains(Dimensions.Page.PageUrl, "/product")
           .WhereIn(Dimensions.Device.Browser, "Chrome", "Firefox", "Safari")
           .OrderByDescending(Metrics.Sessions.Visitors)
           .Paginate(page: 1, pageSize: 50));

Aggregations and Transformations

var response = await _analytics.QueryAsync(builder =>
    builder.AddDimension(Dimensions.Date.DateDimension)
           .AddMetric(Metrics.Sessions.TotalSessions)
           .Sum(Metrics.Pages.PageViews, "total_page_views")
           .Average(Metrics.Sessions.TotalSessions, "avg_sessions")
           .ToStartOfMonth(Dimensions.Date.DateDimension, "month")
           .SetLastDays(90)
           .OrderByDescending("total_page_views"));

Streaming Large Datasets

await foreach (var row in _analytics.QueryStreamAsync(query, pageSize: 1000))
{
    // Process rows incrementally without loading everything into memory
}

Date Range Utilities

using PiwikPRO.Analytics.Utilities;

// Predefined ranges
var today = DateRangeUtilities.Today();
var last7Days = DateRangeUtilities.LastDays(7);
var thisMonth = DateRangeUtilities.CurrentMonth();
var thisQuarter = DateRangeUtilities.CurrentQuarter();
var thisYear = DateRangeUtilities.CurrentYear();

// Use in queries
var response = await _analytics.QueryAsync(builder =>
    builder.AddDimension(Dimensions.Date.DateDimension)
           .AddMetric(Metrics.Sessions.Visitors)
           .SetDateRange(thisMonth.Start, thisMonth.End));

Sessions

var request = _sessionsService.CreateRequest();
request.DateFrom = "2025-01-01";
request.DateTo = "2025-01-31";
var sessions = await _sessionsService.FetchSessionsDataAsync(request);

Real-Time Events

var request = _realTimeEventsService.CreateRequest();
request.DateFrom = DateTime.Now.AddMinutes(-10).ToString("yyyy-MM-dd HH:mm:ss");
request.DateTo = DateTime.Now.AddMinutes(-3).ToString("yyyy-MM-dd HH:mm:ss");
var events = await _realTimeEventsService.FetchRealTimeEventsAsync(request);

Working with Multiple Websites

// Override the default WebSiteId per query
var response = await _analytics.QueryAsync(builder =>
    builder.AddDimension(Dimensions.Date.DateDimension)
           .AddMetric(Metrics.Sessions.Visitors)
           .SetWebSiteId("other-website-id")
           .SetLastDays(7));

Configuration Options

Features

• Fluent Query Builder — Intuitive method-chaining API for building analytics queries
• Strongly-Typed Constants — Predefined dimensions (Dimensions.*) and metrics (Metrics.*) for discoverability
• Date Range Utilities — DateRangeUtilities.LastDays(30), .CurrentMonth(), .CurrentQuarter(), etc.
• Filtering — Dimension and metric filters with operators like WhereContains, WhereIn, WhereEquals
• Aggregations — Sum, Average, Min, Max, UniqueCount with named columns
• Transformations — ToStartOfMonth, ToHourOfDay, ToPath, and more
• Pagination — Built-in Paginate() and streaming via IAsyncEnumerable
• Sessions API — Access raw session-level data with flexible column selection
• Real-Time Events — Query real-time event data (retained for 1 hour)
• Goals Management — List, create, update, and delete goals
• Custom Dimensions — List custom dimensions with pagination support
• Apps Service — Application/site management

Related Packages