Skip to main content

Advertising Platform System

Overview​

This document describes the advertising platform system that allows companies like Rapala to create and manage advertising campaigns on the FishingLog platform. The system is similar to Facebook Ads Manager, allowing advertisers to:

  1. Create advertiser accounts
  2. Create ad campaigns with budgets and targeting
  3. Upload ad creatives (images, videos, text)
  4. Track performance (impressions, clicks, conversions)
  5. Manage billing and payments

Architecture​

Core Entities​

1. AdvertiserAccount​

Represents a company/brand that can advertise (e.g., Rapala, Shimano).

Key Features:

  • Company information and verification
  • Stripe integration for payments
  • Subscription tiers (Basic, Professional, Enterprise)
  • Budget limits and account balance
  • Team member management

Workflow:

  1. User creates advertiser account
  2. Admin reviews and verifies account
  3. Advertiser adds payment method (Stripe)
  4. Advertiser can create campaigns

2. AdCampaign​

A collection of ads with shared budget and targeting.

Key Features:

  • Budget management (daily or lifetime)
  • Targeting options (location, demographics, interests)
  • Scheduling (start/end dates)
  • Frequency capping (max impressions per user)
  • Performance metrics

Example:

  • Campaign: "Rapala Spring Sale"
  • Budget: $5,000 lifetime
  • Target: Users interested in bass fishing, ages 25-55, in US
  • Duration: March 1 - March 31

3. AdCreative​

The actual ad content (image, video, text, etc.).

Key Features:

  • Multiple formats (banner, video, carousel, native)
  • Headline, text, call-to-action
  • Media assets (images, videos)
  • Destination URL
  • Approval workflow

Example:

  • Format: Banner
  • Headline: "New Rapala X-Rap - Catch More Fish!"
  • Image: rapala-xrap-banner.jpg
  • CTA: "Shop Now"
  • Link: rapala.com/products/xrap

4. AdImpression & AdClick​

Track when ads are shown and clicked.

Key Features:

  • User tracking (for frequency capping)
  • Device and location data
  • Cost tracking (CPM/CPC)
  • Billing integration

5. AdvertiserInvoice & AdvertiserPayment​

Handle billing and payments.

Key Features:

  • Monthly invoices for ad spend
  • Stripe payment processing
  • Payment history
  • Account top-ups

How It Works (Similar to Facebook Ads)​

1. Account Creation & Verification​

// User creates advertiser account
POST /api/advertising/accounts
{
    "companyName": "Rapala",
    "contactEmail": "ads@rapala.com",
    "website": "rapala.com"
}

// Admin verifies account
PUT /api/advertising/accounts/{id}/verify
{
    "status": "Active",
    "verifiedByUserId": "admin-guid"
}

2. Payment Setup​

// Add payment method (Stripe)
POST /api/advertising/accounts/{id}/payment-methods
{
    "stripePaymentMethodId": "pm_xxx"
}

// Top up account balance
POST /api/advertising/accounts/{id}/top-up
{
    "amount": 1000,
    "currency": "USD"
}

3. Create Campaign​

POST /api/advertising/campaigns
{
    "advertiserAccountId": "rapala-account-id",
    "name": "Spring Sale Campaign",
    "budgetType": "Lifetime",
    "lifetimeBudget": 5000,
    "startDate": "2024-03-01",
    "endDate": "2024-03-31",
    "targetLocations": "US",
    "targetFishSpecies": "Bass",
    "optimizationGoal": "Clicks"
}

4. Create Ad Creative​

POST /api/advertising/creatives
{
    "advertiserAccountId": "rapala-account-id",
    "campaignId": "campaign-id",
    "name": "X-Rap Banner",
    "format": "Banner",
    "headline": "New Rapala X-Rap",
    "primaryText": "Catch more fish with the new X-Rap",
    "imageUrl": "https://cdn.rapala.com/banner.jpg",
    "destinationUrl": "rapala.com/products/xrap",
    "callToAction": "Shop Now"
}

5. Ad Serving (Backend Logic)​

When a user views a page, the system:

  1. Determines available ad slots
  2. Finds active campaigns matching user's profile
  3. Selects best ad based on optimization goal
  4. Checks frequency capping
  5. Records impression
  6. Charges advertiser (CPM or CPC)
// Get ad for user
GET /api/advertising/ads/next?placement=Feed&userId={userId}

// Response
{
    "adCreativeId": "creative-id",
    "headline": "New Rapala X-Rap",
    "imageUrl": "https://cdn.rapala.com/banner.jpg",
    "destinationUrl": "rapala.com/products/xrap",
    "trackingUrl": "/api/advertising/ads/{id}/click"
}

6. Track Clicks​

// User clicks ad
POST /api/advertising/ads/{creativeId}/click
{
    "userId": "user-id",
    "placement": "Feed"
}

// System records click, charges advertiser (CPC), redirects to destination

7. Analytics & Reporting​

// Get campaign performance
GET /api/advertising/campaigns/{id}/analytics?startDate=2024-03-01&endDate=2024-03-31

// Response
{
    "impressions": 100000,
    "clicks": 2500,
    "conversions": 150,
    "spend": 4500,
    "cpm": 45.00,
    "cpc": 1.80,
    "ctr": 2.5
}

Pricing Models​

1. Cost Per Mille (CPM) - Pay per 1,000 impressions​

  • Advertiser pays when ad is shown
  • Good for brand awareness
  • Typical: $5-50 per 1,000 impressions

2. Cost Per Click (CPC) - Pay per click​

  • Advertiser pays when user clicks
  • Good for driving traffic
  • Typical: $0.50-5.00 per click

3. Cost Per Action (CPA) - Pay per conversion​

  • Advertiser pays when user completes action (purchase, signup)
  • Most expensive but highest ROI
  • Requires conversion tracking

Subscription Tiers​

Basic ($99/month)​

  • $1,000 monthly ad spend limit
  • Basic targeting
  • Email support
  • Standard ad formats

Professional ($299/month)​

  • $10,000 monthly ad spend limit
  • Advanced targeting
  • Priority support
  • All ad formats
  • Analytics dashboard

Enterprise (Custom pricing)​

  • Unlimited ad spend
  • Custom targeting
  • Dedicated account manager
  • Custom ad formats
  • API access

Ad Placement Locations​

  1. Feed - In user's main feed/timeline
  2. Profile - On user profile pages
  3. Species Page - On fish species detail pages (e.g., "Bass" page)
  4. Gear Page - On gear/product pages
  5. Search - In search results
  6. Sidebar - Sidebar placement
  7. Banner - Top/bottom banner
  8. Email - In email newsletters

Targeting Options​

  • Location: Country, state, city, zip code
  • Demographics: Age, gender
  • Interests: Fish species, fishing methods, gear preferences
  • Behavior: User activity, purchase history
  • User Roles: Charter captains, tournament anglers, etc.

Approval Workflow​

  1. Advertiser creates creative
  2. Creative status: PendingReview
  3. Admin reviews creative
  4. Admin approves or rejects
  5. If approved, creative can be used in campaigns
  6. If rejected, advertiser receives reason

Billing Flow​

  1. Advertiser sets up payment method (Stripe)
  2. Advertiser tops up account balance OR sets up auto-pay
  3. As ads run, costs are deducted from balance
  4. Monthly invoice generated for total spend
  5. If balance runs low, advertiser is notified
  6. If balance reaches zero, ads pause automatically

Implementation Checklist​

Phase 1: Core Infrastructure​

  • Create entities and enums
  • Add DbSets to AppDbContext
  • Create migrations
  • Create AdvertiserController
  • Create AdCampaignController
  • Create AdCreativeController

Phase 2: Ad Serving​

  • Create ad serving endpoint
  • Implement ad selection algorithm
  • Implement frequency capping
  • Track impressions
  • Track clicks

Phase 3: Stripe Integration​

  • Integrate Stripe for payments
  • Handle payment methods
  • Process top-ups
  • Generate invoices
  • Handle webhooks

Phase 4: Admin Tools​

  • Admin approval workflow
  • Account verification
  • Creative review
  • Fraud detection

Phase 5: Analytics​

  • Campaign analytics
  • Creative performance
  • Reporting dashboard
  • Export capabilities

Example: Rapala Campaign​

  1. Rapala creates account

    • Company: Rapala
    • Contact: ads@rapala.com
    • Subscription: Professional ($299/month)

  2. Rapala adds payment

    • Stripe payment method added
    • Top up $5,000

  3. Rapala creates campaign

    • Name: "Spring Bass Fishing Sale"
    • Budget: $5,000 lifetime
    • Target: US users, ages 25-55, interested in bass fishing
    • Duration: March 1-31

  4. Rapala uploads creative

    • Banner image: rapala-xrap-banner.jpg
    • Headline: "New X-Rap - Catch More Bass!"
    • Link: rapala.com/products/xrap

  5. Campaign runs

    • Ads shown in feed, species pages, gear pages
    • 100,000 impressions
    • 2,500 clicks
    • $4,500 spent

  6. Rapala views analytics

    • CTR: 2.5%
    • CPC: $1.80
    • 150 conversions (purchases)

  7. Monthly invoice

    • Invoice generated: $4,500
    • Charged via Stripe
    • Account balance: $500 remaining

Security & Fraud Prevention​

  • Rate limiting on ad requests
  • IP address tracking
  • Click fraud detection
  • Bot detection
  • Frequency capping per user
  • Budget limits per campaign
  • Daily spending limits

Future Enhancements​

  • Real-time bidding (RTB)
  • Programmatic advertising
  • Retargeting campaigns
  • Lookalike audiences
  • A/B testing
  • Video ads
  • Native ads
  • Mobile app ads