Skip to main content

Advertising Platform Implementation Summary

✅ What's Been Created​

1. Database Entities (8 entities)​

All entities are in FishingLog.Infrastructure/Entities/Advertising/:

  • AdvertiserAccount - Company accounts (e.g., Rapala)
  • AdCampaign - Campaigns with budgets and targeting
  • AdCreative - Ad content (images, videos, text)
  • AdImpression - Tracks when ads are shown
  • AdClick - Tracks clicks on ads
  • AdvertiserInvoice - Monthly billing invoices
  • AdvertiserPayment - Payment tracking
  • AdvertiserTeamMember - Team member management

2. Enums (12 enums)​

All enums are in FishingLog.Infrastructure/Entities/Enums/:

  • AdvertiserAccountStatus - Account status (Pending, Active, Suspended, etc.)
  • AdvertiserSubscriptionTier - Subscription levels (Basic, Professional, Enterprise)
  • AdCampaignStatus - Campaign status (Draft, Active, Paused, etc.)
  • AdBudgetType - Budget type (Daily, Lifetime)
  • AdOptimizationGoal - Optimization goals (Impressions, Clicks, Conversions)
  • AdFormat - Ad formats (Banner, Video, Carousel, Native)
  • AdPlacementType - Where ads appear (Feed, Profile, SpeciesPage, etc.)
  • AdCreativeStatus - Creative status (PendingReview, Approved, Rejected)
  • InvoiceStatus - Invoice status (Pending, Paid, Overdue)
  • PaymentType - Payment types (TopUp, Subscription, Invoice)
  • PaymentStatus - Payment status (Pending, Succeeded, Failed)
  • AdvertiserRole - Team member roles (Owner, Admin, Manager, Member)

3. API Controllers (4 controllers)​

AdvertiserController (/api/advertiser)​

  • GET /api/advertiser - Get all accounts (admin)
  • GET /api/advertiser/me - Get my accounts
  • GET /api/advertiser/{id} - Get specific account
  • POST /api/advertiser - Create account
  • PUT /api/advertiser/{id} - Update account
  • POST /api/advertiser/{id}/verify - Verify account (admin)
  • GET /api/advertiser/{id}/balance - Get account balance
  • GET /api/advertiser/{id}/analytics - Get account analytics

AdCampaignController (/api/adcampaign)​

  • GET /api/adcampaign/account/{accountId} - Get campaigns for account
  • GET /api/adcampaign/{id} - Get specific campaign
  • POST /api/adcampaign - Create campaign
  • PUT /api/adcampaign/{id} - Update campaign
  • POST /api/adcampaign/{id}/activate - Activate campaign
  • POST /api/adcampaign/{id}/pause - Pause campaign
  • GET /api/adcampaign/{id}/analytics - Get campaign analytics

AdCreativeController (/api/adcreative)​

  • GET /api/adcreative/account/{accountId} - Get creatives for account
  • GET /api/adcreative/{id} - Get specific creative
  • POST /api/adcreative - Create creative
  • PUT /api/adcreative/{id} - Update creative
  • POST /api/adcreative/{id}/review - Approve/reject creative (admin)

AdServingController (/api/ad-serving)​

  • GET /api/ad-serving/next - Get next ad to display ⭐ Core ad serving endpoint
  • POST /api/ad-serving/click/{creativeId} - Record click and redirect

4. Database Integration​

  • All entities added to AppDbContext as DbSets
  • Ready for migrations

🚀 How It Works​

Step 1: Rapala Creates Account​

POST /api/advertiser
{
  "companyName": "Rapala",
  "contactEmail": "ads@rapala.com",
  "website": "rapala.com"
}

Step 2: Admin Verifies Account​

POST /api/advertiser/{id}/verify
{
  "isApproved": true,
  "notes": "Verified company"
}

Step 3: Rapala Creates Campaign​

POST /api/adcampaign
{
  "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"
}

Step 4: Rapala Uploads Creative​

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

Step 5: Admin Approves Creative​

POST /api/adcreative/{id}/review
{
  "isApproved": true
}

Step 6: Rapala Activates Campaign​

POST /api/adcampaign/{id}/activate

Step 7: Frontend Requests Ad​

GET /api/ad-serving/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",
  "clickTrackingUrl": "/api/ad-serving/click/{creativeId}",
  "format": "Banner"
}

Step 8: User Clicks Ad​

POST /api/ad-serving/click/{creativeId}?userId={userId}
  • Records click
  • Charges advertiser (CPC)
  • Redirects to destination URL

💰 Pricing Models​

CPM (Cost Per Mille)​

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

CPC (Cost Per Click)​

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

CPA (Cost Per Action)​

  • Advertiser pays per conversion
  • Requires conversion tracking (future enhancement)

📊 Analytics​

Account Analytics​

GET /api/advertiser/{id}/analytics?startDate=2024-03-01&endDate=2024-03-31

Response:

{
  "totalCampaigns": 5,
  "activeCampaigns": 2,
  "totalImpressions": 100000,
  "totalClicks": 2500,
  "totalConversions": 150,
  "totalSpend": 4500,
  "averageCtr": 2.5,
  "averageCpc": 1.80,
  "averageCpm": 45.00
}

🎯 Targeting Options​

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

🔒 Security & Access Control​

  • Only account owners and admins can manage accounts
  • Admin approval required for creatives
  • Admin verification required for accounts
  • Team members can have different permission levels

📝 Next Steps​

  1. Create Migration

    dotnet ef migrations add AddAdvertisingPlatform --project FishingLog.Infrastructure --startup-project FishingLog.API

  2. Run Migration

    dotnet ef database update --project FishingLog.Infrastructure --startup-project FishingLog.API

  3. Stripe Integration (Future)

    • Add Stripe payment method management
    • Implement top-up functionality
    • Generate invoices automatically
    • Handle webhooks

  4. Enhanced Targeting (Future)

    • More sophisticated targeting algorithm
    • Lookalike audiences
    • Retargeting campaigns

  5. Advanced Features (Future)

    • A/B testing
    • Real-time bidding
    • Video ads
    • Native ads

📚 Documentation​

See FishingLog.Infrastructure/Entities/Advertising/README_Advertising.md for detailed documentation.