Short Links

Overview

The short link system in TanStack Ship provides branded, trackable short URLs that can be used across marketing campaigns, social media, and offline materials. Each link tracks clicks, unique visitors, geographic data, and UTM attribution — giving you complete visibility into link performance.

As part of the platform, short links integrate with the UTM tracking system for campaign attribution, the campaign and offer system for distribution, and the analytics dashboard for click-through reporting.

Design Flow

The short link system manages the complete link lifecycle from creation through redirection to analytics reporting:

Core Capabilities

Link Creation & Management

Create short links from the admin dashboard:

• Custom Alias — Define your own short path (e.g., go.yourdomain.com/summer)
• Auto-generate — System generates a unique short code automatically
• Destination URL — The full URL to redirect to
• UTM Parameters — Built-in UTM builder for campaign attribution
• Expiration — Optional link expiration for time-limited campaigns

Example — Short link API response:

{
  "shortUrl": "https://go.yourdomain.com/summer24",
  "destinationUrl": "https://yourplatform.com/pricing?utm_source=twitter&utm_medium=social",
  "clicks": 0,
  "createdAt": "2025-06-01T10:00:00Z"
}

**Example — Creating a short link from React:**

```tsx
import { useMutation } from '@tanstack/react-query'

function CreateShortLink() {
  const mutation = useMutation({
    mutationFn: async (data: { url: string; alias?: string }) => {
      const res = await fetch('/api/links', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data),
      })
      if (!res.ok) throw new Error('Failed to create link')
      return res.json()
    },
  })

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault()
    const form = new FormData(e.target as HTMLFormElement)
    mutation.mutate({ url: form.get('url') as string })
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="url" placeholder="Enter destination URL" />
      <button type="submit">Create Short Link</button>
      {mutation.data && <p>Short URL: {mutation.data.shortUrl}</p>}
    </form>
  )
}

Click Analytics

Each short link provides comprehensive analytics:

• Total Clicks — Aggregate click count over the link's lifetime
• Unique Visitors — Distinct visitor count based on IP and session
• Click Timeline — Clicks over time (daily, weekly, monthly views)
• Referrer Data — Where clicks are originating (direct, social, email, etc.)
• Geographic Data — Visitor country and city distribution

QR Code Generation

Each short link has a built-in QR code generator, enabling use in:

• Print materials (flyers, posters, business cards)
• Event signage and billboards
• Product packaging and in-store displays

Design Philosophy

Trackability by Default

Every short link is created with built-in analytics — no opt-in required. From the moment a link is created, click counts, unique visitors, geographic distribution, and referrer data are automatically collected and aggregated. This zero-configuration approach ensures that marketing teams never lose attribution data because they forgot to enable tracking. The analytics are presented in dedicated dashboard views with time-range filtering and campaign segmentation.

Campaign Attribution First

Short links are designed as first-class campaign delivery vehicles. The built-in UTM builder ensures that every link carries campaign attribution parameters, making each click traceable to its campaign source. Unlike generic URL shorteners such as Bitly that often strip UTM parameters or require paid plans for analytics, the system preserves and enriches attribution context throughout the redirect chain — with zero additional cost. This enables accurate reporting in the attribution analytics dashboard.

Multi-Channel Distribution

The system bridges online and offline marketing channels through QR code generation. A single short link can be distributed across email, social media, print materials, and event signage — with all channels feeding into the same analytics view. This unified measurement approach gives marketing teams a complete picture of campaign performance regardless of distribution channel.

Best Practices

Memorable Aliases

Use short, memorable aliases for links shared in offline or verbal contexts (e.g., yourbrand.com/launch). Save auto-generated codes for programmatic use.

Campaign-Specific Links

Create unique short links for each campaign to enable accurate attribution. Reusing the same link across campaigns dilutes analytics.

Monitor Click Patterns

Review click analytics regularly to identify traffic patterns. Sudden spikes may indicate viral distribution; sudden drops may indicate broken links.

FAQ

What is the base URL for short links? The base URL is configurable via environment variable. Default format is go.yourdomain.com.

Can I edit a short link after creation? Yes, you can update the destination URL, UTM parameters, and alias of existing short links from the admin dashboard.

How long is click data retained? Click data is retained indefinitely for historical analysis. The dashboard provides time-range filtering for focused reporting.

Configuration

Set the base URL for short links:

VITE_SHORT_LINK_BASE_URL=https://go.yourdomain.com

Links are managed entirely from the admin dashboard.

Integration Points

• UTM System — Short links carry UTM parameters for campaign attribution
• Campaigns — Distribute campaign URLs via trackable short links
• Click Analytics — Full click tracking and analytics dashboard
• Attribution Dashboard — Click data contributes to campaign attribution reporting
• QR Code Generation — Built-in QR export for offline distribution