DeryCode Ads — PPC Advertising Platform

Uganda's first local pay-per-click advertising platform
Built for East African businesses. Powered by DeryCode Search Engine.

Features

• Sponsored Search Results — Ads appear at the top of DeryCode Search results with a gold "Ad" badge
• PPC Model — Advertisers pay only when someone clicks their ad (UGX 500+ per click)
• Campaign Management — Full CRUD dashboard for creating, editing, pausing, and deleting campaigns
• Keyword Targeting — Advertisers choose which search keywords trigger their ads
• Budget Control — Monthly budgets with automatic spending caps
• Real-time Analytics — Clicks, impressions, CTR, spend tracking, and budget utilization
• MoMo Payments — MTN MoMo and Airtel Money integration for Ugandan advertisers
• Ad Widget — Embeddable JavaScript widget for third-party websites (publisher network)
• Click Fraud Prevention — Budget enforcement and click tracking per campaign

Architecture

derycode-ads/
├── api/
│   └── ads.js          # Ad serving, campaign CRUD, click tracking, analytics, payments
├── public/
│   ├── ads.html        # Advertiser dashboard (campaign management, analytics, payments)
│   └── widget.js       # Embeddable ad widget for publisher websites
├── package.json
├── vercel.json
└── README.md

API Endpoints

Method	Endpoint	Action
GET	/api/ads?q=keyword	Serve ads matching a search query
GET	/api/ads?action=click&id=X	Track click and redirect to ad URL
GET	/api/ads?action=list	List all campaigns (admin)
GET	/api/ads?action=analytics	Get analytics (all or single campaign)
GET	/api/ads?action=analytics&id=X	Get analytics for specific campaign
POST	/api/ads?action=create	Create new campaign
PUT	/api/ads?action=update&id=X	Update campaign
DELETE	/api/ads?action=delete&id=X	Delete campaign
POST	/api/ads?action=payment	Initiate MoMo payment

Pricing

Parameter	Value
Minimum bid per click	UGX 500
Minimum monthly budget	UGX 10,000
Max sponsored results per search	3
Impression charges	Free (pay per click only)
Ad position	Determined by bid amount (highest bidder = top)

Quick Start

Deploy to Vercel

1. Fork or clone this repo
2. Connect to Vercel
3. (Optional) Set up Vercel KV for persistent storage
4. Deploy

Integrate with DeryCode Search

Add the ads fetch to your search API:

// In search handler
const adsResponse = await fetch('/api/ads?q=' + encodeURIComponent(q));
const adsData = await adsResponse.json();
// Include adsData.ads in your search response

Embed Ad Widget on Third-Party Sites

<div id="derycode-ads"></div>
<script src="https://derycode-ads.vercel.app/widget.js" 
  data-keywords="technology,uganda,software" 
  data-limit="3" 
  data-publisher="your-site-id">
</script>

Payment Integration

Currently supports manual MTN MoMo payments. To enable automated collection:

1. Register for MTN MoMo API at https://momodeveloper.mtn.com
2. Set environment variables:
   • MOMO_API_USER
   • MOMO_API_KEY
   • MOMO_SUBSCRIPTION_KEY
3. Update the payment handler in api/ads.js to call the MoMo Collection API

Storage

• Production: Vercel KV (Redis-backed, persistent across serverless invocations)
• Development: In-memory store with seed data (resets on redeploy)

Revenue Model

Advertiser pays → DeryCode Ads → Sponsored result shown
                    ↓
              Click tracked
              Budget deducted
              Analytics updated

Future: Publisher Network

Advertiser pays → DeryCode Ads → Ad shown on DeryCode Search AND partner sites
                    ↓                    ↓
              DeryCode keeps 60%     Publisher earns 40%

Tech Stack

• Backend: Vercel Serverless Functions (Node.js)
• Storage: Vercel KV (Redis)
• Frontend: Vanilla HTML/CSS/JS (no framework dependency)
• Payments: MTN MoMo API, Airtel Money API
• Hosting: Vercel

Author

Asiimwe Derick — Founder & CEO, DeryCode Technologies

• GitHub: @asiimwe3
• Email: derycode50@gmail.com
• WhatsApp: +256 772 002 326

License

MIT — See LICENSE file