Developer Documentation & Edge API Integration Guide

1. Architecture Overview

Connectgold Edge Ad Network delivers AI-optimized programmatic ads directly at Cloudflare edge nodes. Real-time contextual decisions are routed via Cloudflare Workers and Workers AI Gateway to maximize yield across direct advertisers and programmatic demand partners (InMobi OpenRTB 2.5, ExoClick, HilltopAds, A-Ads, etc.).

Core Request Parameters

Parameter Type Description
platform String Target environment: web, webview
format String Ad unit format: banner, ai_text, native_display, infeed, interstitial_fullscreen, rewarded_video
plc String Unique placement ID on your domain/app (auto-generated in dashboard)
pub_id String Your verified Publisher Account ID (retrieved via dashboard)
consent String User GDPR/CCPA consent state (1 = Granted, 0 = Denied)

2. Ad Unit Formats & Publisher Usage Guide

Connectgold offers six flexible ad formats designed for high eCPM yield across desktop and mobile layouts. Here is how each unit functions and how to place the generated snippet in your code:

1. Display Banners (`banner`)

How It Works: Standard fixed-size display units (320x50, 300x250, 728x90) that render high-converting image or rich-media banners. Auto-rotates at specified intervals (15sā€“60s) to refresh winning bids dynamically.

Publisher Usage: Paste the generated snippet inside an HTML container at the top header, sidebar, or footer of your layout where you want the banner to display.

2. AI Dynamic Text Ads (`ai_text`)

How It Works: Powered by Cloudflare Workers AI (Google Gemma 4 26B). It dynamically writes targeted, high-converting ad copy and call-to-action buttons matched to specified niche keywords in real-time.

Publisher Usage: Place inside article body paragraphs, product review cards, or sidebar widgets to display contextual text recommendations.

3. Native Display Cards (`native_display`)

How It Works: Blends into your site design using native HTML components (headline, thumbnail, body text, and CTA button) to match host page styling and deliver high click-through rates (CTR).

Publisher Usage: Insert anywhere in article main body sections, content grids, or recommended reading blocks.

4. In-Feed Native Content (`infeed`)

How It Works: Automatically scans host page DOM for post elements (<article>, .post, .card). When posts are present (`has_posts=true`), it injects structured native sponsored posts naturally within your newsfeed stream.

Publisher Usage: Place the embed snippet directly between repeating feed elements or blog article loops in your homepage or blog template.

5. Full Screen Interstitials (`interstitial_fullscreen`)

How It Works: High-eCPM full-screen overlay ads triggered by user navigation actions (e.g., page change, level completion, or button clicks).

Publisher Usage: Paste the generated function script into your page header, then trigger it programmatically using:
showConnectGoldAd(function() { console.log('Overlay closed'); });

6. Rewarded Video (`rewarded_video`)

How It Works: Users watch a full-screen video or interactive ad in exchange for in-game currency, unlocked premium articles, or user points.

Publisher Usage: Bind the generated script to a click event (e.g., "Watch Ad to Unlock Premium Content") like so:
<button onclick="showConnectGoldAd(grantUserReward)">Unlock Content</button>

3. Generating Publisher Embed Code

To ensure proper credentials, rotation intervals, GDPR consent settings, and third-party telemetry bindings are accurately configured, all ad integration tags should be generated through your account dashboard.

  1. Sign in to the Connectgold Console and navigate to the šŸ“Œ Placements & Code tab.
  2. Your unique Publisher ID will automatically populate into the form.
  3. Enter a Placement Name (e.g., Header Banner Unit or Sidebar Feed).
  4. Select your target Ad Unit Format (Display Banner, AI Dynamic Text Ad, Native Card, Interstitial, or Rewarded Video).
  5. Configure optional settings such as Banner Size, Rotation Duration, or AI Product Keywords.
  6. Click Generate Placement & Embed Code to produce your tailored JavaScript snippet.
  7. Click Copy Code Snippet and paste it into your website HTML where the ad should display.

4. Programmatic OpenRTB 2.5 / Prebid Endpoint

Connectgold supports direct Server-to-Server (S2S) OpenRTB 2.5 auctions. External DSPs and Prebid Server bidders can submit standard JSON POST requests to our edge auction pipeline.

  1. Navigate to the šŸ“Œ Placements & Code section of your dashboard.
  2. Retrieve your assigned edge auction endpoint URL under your account developer credentials.
  3. Configure your Prebid Server or OpenRTB DSP adapter to issue POST requests using standard OpenRTB 2.5 specifications with your active pub_id.

5. Multi-Engine Analytics & Telemetry

Ad impression callbacks automatically detect and report impression events to active third-party analytics engines loaded on the host page (Google Analytics GA4, Mixpanel, and Plausible Analytics).

  1. Go to the šŸ“Š Network Analytics tab in your dashboard.
  2. Scroll to Developer Third-Party Analytics Setup.
  3. Enter your GA4 Measurement ID, Plausible Domain, or Mixpanel Token.
  4. Once entered, all newly generated placement snippets will automatically embed your custom analytics tracking scripts.

6. Authorized Digital Sellers (ads.txt)

To authorize Connectgold demand sources to bid on your domain inventory, you must publish your authorized seller line on your domain root (https://yourdomain.com/ads.txt).

  1. Navigate to the āš™ļø Network Settings tab in your dashboard.
  2. Locate the Authorized Connectgold Network ads.txt Entry box.
  3. Click Copy ads.txt Line to copy your personalized seller entry.
  4. Paste the line into your domain's root ads.txt file.

7. Advertiser Campaign Submission

Advertisers can publish direct campaigns into the edge auction engine. Bids are verified against active account balances in real time.

  1. First, navigate to the šŸ’³ Payments & Wallet tab to fund your advertiser wallet via Paystack.
  2. Switch to the šŸ“¢ Advertisers & Bids tab.
  3. Fill in your campaign details, target format, destination URL, image/video assets, bid rate ($ CPM), and total budget.
  4. Click Publish Campaign to Auction Engine to submit your ad to the live auction.

8. Publisher Earnings & Payout Requests

Connectgold publishers earn 80% revenue share on every served ad impression. Earnings are accumulated and tracked in real time across edge workers.

  1. Navigate to the šŸ’³ Payments & Wallet tab in your dashboard.
  2. Click šŸ”„ Refresh Balance to view your total earned USD earnings.
  3. Complete the Global Publisher Tax Declaration (TIN/NIN certification).
  4. Enter your bank details and click Request Publisher Payout to initiate a direct transfer.

9. Network Analytics Reporting

Query real-time performance analytics across ad formats, impressions, clicks, and Click-Through Rates (CTR).

  1. Navigate to the šŸ“Š Network Analytics tab in your dashboard.
  2. Select your target Ad Format and Date Range.
  3. Click Refresh to view your aggregated live impression, click, and CTR metrics.