VeeFriends.LinkShortener 5.0.21

VeeFriends.LinkShortener 📎✨

VeeFriends.LinkShortener is a modern, production-ready .NET 9 library and service for creating, managing, and tracking short links. It features robust analytics, QR code generation, and seamless integration with Azure Table Storage, Cloudinary, and Link Preview APIs. Designed for extensibility and testability, it supports dependency injection and is fully covered by automated tests.

Features

• Short Link Creation: Generate branded, expiring, and analytics-enabled short URLs.
• Analytics Tracking: Collects and stores detailed analytics for each link visit, including IP, user agent, geo, and device info.
• QR Code Generation: Automatically generates QR codes for each short link.
• Link Preview Integration: Fetches and stores link preview metadata (title, description, image).
• Cloudinary Support: Stores and serves QR codes and images via Cloudinary.
• Azure Table Storage: Fast, scalable, and cost-effective storage for links and analytics.
• Extensible & Testable: Built for dependency injection and easy extension.
• .NET 9 & C# 13: Uses the latest .NET and C# features.

Installation

Install the VeeFriends.LinkShortener NuGet package in your project:

dotnet add package VeeFriends.LinkShortener

Configuration

Configure the necessary services in your Startup.cs or Program.cs file:

using Microsoft.Extensions.DependencyInjection; using VeeFriends.LinkShortener;
var services = new ServiceCollection();
services.AddLinkShortener(options => { 
    options.AzureTableConnectionString = "your-azure-table-connection-string"; 
    options.CloudinaryApiSecret = "your-cloudinary-api-secret"; 
    options.CloudinaryApiKey = "your-cloudinary-api-key"; 
    options.CloudinaryCloudName = "your-cloudinary-cloud-name"; 
    options.LinkPreviewApiKey = "your-link-preview-api-key"; 
    options.HostUrl = "https://your-shortener-domain.com"; 
    options.QrCodeMoneyApiKey = "your-qrcode-monkey-api-key"; 
    options.ClarityMsTrackingCode = "your-clarity-ms-tracking-code"; 
});

LinkShortenerConfig Options

Usage

ILinkService Overview

The ILinkService interface provides methods for creating, updating, deleting, tracking, and reporting on short links and their analytics.

Core Methods

• CreateLink: Create a new short link with optional custom slug, expiration, and QR code options.
• UpdateLink: Update an existing link's name, URL, expiration, or QR code options.
• DeleteLink: Soft-delete a link by setting its expiration to now.
• GetAllLinks: Retrieve all short links (up to 1000).
• GetLinkBySlug: Retrieve a link by its slug.
• GetAnalytics / GetAnalyticsBySlug: Retrieve analytics for a link by ID or slug.
• TrackView / TrackViewBySlug: Track a view (click or scan) of a link, with support for both HttpRequest and HttpRequestMessage.
• GenerateRedirectPageFromLinkModel: Generate the HTML redirect page for a link, including analytics and tracking code.
• Reporting: Get activity reports, top performing links, and top locations for all links or a specific link.

Example: Creating and Managing Links

public class MyLinkService 
{ 
    private readonly ILinkService _linkService;

    public MyLinkService(ILinkService linkService)
    {
        _linkService = linkService;
    }

    public async Task CreateAndTrackAsync()
    {
        // Create a new short link
        var link = await _linkService.CreateLink(
            "My Campaign",
            "https://veefriends.com",
            slug: null,
            expiresAt: DateTime.UtcNow.AddDays(7),
            qrCodeOptions: null,
            CancellationToken.None
        );

        // Retrieve by slug
        var retrieved = await _linkService.GetLinkBySlug("your-slug", CancellationToken.None);

        // Track a view (analytics)
        var request = new HttpRequestMessage(HttpMethod.Get, link.ShortUrl);
        await _linkService.TrackViewBySlug("your-slug", request, null, false, CancellationToken.None);

        // Get analytics
        var analytics = await _linkService.GetAnalyticsBySlug("your-slug", CancellationToken.None);
    }
}

Example: Analytics

Analytics are automatically tracked for each link visit, including:

• Request method and URL
• IP address and geo lookup (country, region, city)
• User agent, device type, OS, and browser
• Referrer

Retrieve analytics for a link:

var analytics = await linkService.GetAnalyticsBySlug("your-slug", CancellationToken.None);

foreach (var entry in analytics) 
{ 
    Console.WriteLine($"{entry.Timestamp}: {entry.IpAddress} - {entry.UserAgent}"); 
}

Example: Reporting

Generate reports for dashboarding and analytics:

// Get activity report for all links 
var report = await linkService.GetLinkActivityReport( DateTime.UtcNow.AddDays(-30), DateTime.UtcNow, CancellationToken.None );

// Get top performing links 
var topLinks = await linkService.GetTopPerformingLinks( DateTime.UtcNow.AddDays(-30), DateTime.UtcNow, CancellationToken.None );

// Get top locations for a link 
var topLocations = await linkService.GetTopLocationsForLink( linkId, DateTime.UtcNow.AddDays(-30), DateTime.UtcNow, CancellationToken.None );

License

This project is licensed under the MIT License. See the LICENSE file for more details.