PiwikPRO.Tracking 1.0.1

PiwikPRO.Tracking

Official Piwik PRO .NET SDK for server-side tracking and JavaScript tracking code generation. Send tracking events from your .NET backend and generate client-side tracking snippets for web pages.

Installation

dotnet add package PiwikPRO.Tracking

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

Prerequisites

You need your Piwik PRO instance details:

1. Your Piwik PRO instance URL (e.g., https://your-instance.piwik.pro)
2. Your Website/App ID — found under Administration > Sites & Apps
3. For server-side tracking: an OAuth client (Client ID + Secret) from Menu > Profile > API Keys

Note: JavaScript tracking code generation only requires the instance URL and Website ID — no API credentials needed.

Quick Start

Register Services

using PiwikPRO.Tracking.Extensions;

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

Server-Side Tracking

Track events directly from your server — no client-side JavaScript required:

using PiwikPRO.Tracking;

public class MyService
{
    private readonly ITrackingService _tracking;

    public MyService(ITrackingService tracking) => _tracking = tracking;

    public async Task TrackUserActions()
    {
        // Page view
        await _tracking.TrackPageViewAsync(
            url: "https://example.com/products",
            actionName: "Product Listing Page");

        // Goal conversion with revenue
        await _tracking.TrackGoalAsync(goalId: "abc-123", revenue: 99.99m);

        // File download
        await _tracking.TrackDownloadAsync(
            downloadUrl: "https://example.com/files/whitepaper.pdf");

        // External link click
        await _tracking.TrackOutlinkAsync(linkUrl: "https://external-site.com");

        // Site search
        await _tracking.TrackSiteSearchAsync(
            searchQuery: "product name",
            categories: new List<string> { "Electronics" },
            resultCount: 42);
    }
}

Advanced Tracking with Custom Dimensions

using PiwikPRO.Tracking.Models;

var request = new TrackingRequest
{
    Url = "https://example.com/checkout",
    ActionName = "Checkout - Step 2",
    Uid = "user@example.com",
    CustomDimensions = new Dictionary<string, string>
    {
        ["dimension1"] = "Premium User",
        ["dimension2"] = "US-West"
    },
    EventCustomVars = new Dictionary<string, (string Name, string Value)>
    {
        ["1"] = ("Cart Value", "299.99"),
        ["2"] = ("Items Count", "3")
    }
};

await _tracking.TrackEventAsync(request);

JavaScript Tracking Code Generation

Generate Piwik PRO tracking scripts for embedding in web pages:

using PiwikPRO.Tracking;

// Standard tracking code (uses _paq variable)
var trackingCode = codeGenerator.GenerateTrackingCode();

// Use _ppas variable to avoid conflicts with Matomo
var ppasCode = codeGenerator.GenerateTrackingCode(trackerVariableName: "_ppas");

// Tag Manager + Consent Manager code
var tagManagerCode = codeGenerator.GenerateTagManagerTrackingCode();

// Custom site and account
var customCode = codeGenerator.GenerateTrackingCode(
    siteId: "specific-site-id",
    accountAddress: "custom.containers.piwik.pro");

Example output:

<script type="text/javascript">
  var _paq = window._paq = window._paq || [];
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="//your-instance.piwik.pro/";
    _paq.push(['setTrackerUrl', u+'ppms.php']);
    _paq.push(['setSiteId', 'your-site-id']);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.type='text/javascript'; g.async=true; g.src=u+'ppms.js'; s.parentNode.insertBefore(g,s);
  })();
</script>

ASP.NET Core Controller Example

public class ScriptController : ControllerBase
{
    private readonly IJavaScriptTrackingCodeGenerator _codeGenerator;

    public ScriptController(IJavaScriptTrackingCodeGenerator codeGenerator)
        => _codeGenerator = codeGenerator;

    [HttpGet("/tracking.js")]
    public IActionResult GetTrackingScript()
    {
        var code = _codeGenerator.GenerateTrackingCode();
        return Content(code, "text/javascript");
    }
}

Configuration Options

Features

• Server-Side Tracking — Page views, custom events, goal conversions, downloads, outlinks, site searches
• Custom Dimensions & Variables — Attach custom data to any tracking event
• JavaScript Code Generation — Generate standard tracking snippets for web pages
• Tag Manager Support — Generate Tag Manager + Consent Manager code
• Tracker Variable Names — Use _ppas instead of _paq to avoid Matomo conflicts
• Fluent Script Builder — ClientSideTrackingScriptBuilder for dynamic tracking scripts
• ASP.NET Core Integration — Full dependency injection via AddPiwikProTracking()

Related Packages