Toolsby Spectral Web Services

DocsItty Bitty Ad Server

Itty Bitty Ad Server configuration

Getting a first ad live in six steps, then the reference — the three placement types, what each ad carries, how several rotate, what Analytics counts, and what to check when an ad doesn't appear.

The Itty Bitty Ad Server runs a handful of local sponsor and community ads on a Ghost site, through one code-injection tag. It is not Google Ad Manager: no bidding, no exchange, no network. You sell the ad, you keep the money, and this puts the image on the page and counts what happened.

Get it running

  1. Connect your Ghost site. If you haven't yet, Connect your Ghost site has the steps. An Admin API key is needed only to upload artwork — without one you can still run ads by pasting image URLs you host elsewhere. 1:24
  2. Add a placement, and start with the adhesion bar. A bottom adhesion bar needs no knowledge of your theme at all — it sticks to the bottom of the page wherever you put it. The selector placement is more precise but wants a look at your theme's HTML; leave it for your second ad. 1:36
  3. Add an ad inside it. Give it a name, the Destination URL the click should go to, Alt text, and a Disclosure label if you want one. Set the audience and paths on the placement — "not on the home page" is a common first choice. 2:27
  4. Add the artwork. Up to three images per ad, each ticked for the screen sizes it suits — a wide banner for desktop and tablet, a squarer card for phones. Don't use a transparent image on an adhesion bar: it sits over your content and the text shows through. 3:09
  5. Save, then paste the install snippet once. Copy it from the Install tab into Ghost → Settings → Code injection → Site Footer — at the end, not in the middle of code that's already there — and save. Every later ad and edit goes live on its own; you never come back here. 4:31
  6. Look at your site, then at Analytics. Load a page the placement allows and the ad should be there. Views and clicks appear in the Analytics tab after a short delay. 9:58

Everything below is reference — the placement types in full, what each ad carries, what Analytics counts, and what to check when an ad doesn't appear.

The walkthrough goes from artwork in the inbox to a live ad in twelve minutes. Two things in it have since shipped: it says a downloadable month-by-month report is coming — the Analytics tab has one now — and it promises a list of common insertion points for common themes, which is Ad targets by theme.

Install & Settings

The Install tab shows one script tag. Paste it once into Ghost → Settings → Code injection → Site Footer, and that's the whole install: every change you save here reaches your site within about a minute, with nothing to re-paste and no theme edits.

Under Advanced settings on the same tab:

  • Ads enabled site-wide, the master switch. Off, nothing renders anywhere, whatever the placements say.
  • Device breakpoints, in pixels: a screen up to Mobile max counts as mobile, up to Tablet max as tablet, and anything wider as desktop. These decide which of an ad's images a reader gets.

Placements

A placement is a spot where ads appear; the ads inside it rotate. Each has a name, an on/off switch, and one of three types:

  • Bottom adhesion bar (sticky). A bar along the bottom of every page that stays put as the reader scrolls, transparent apart from the ad itself. Dismissible (×) gives it a close button, and Re-show after N minutes decides how long a reader who closed it goes without it. The easiest place to start.
  • Insert near a page element (CSS selector). Puts the ad Before, After, or Inside (at the start or the end of) whatever the CSS selector matches, such as .post-content to sit next to the article body. Your theme's class names are what you write here — and some themes ship named spots for exactly this, listed in Ad targets by theme.
  • Newsletter ad slot. Nothing renders on your site for this one. Add an "Ad" section to a newsletter automation and pick this slot; each reader is shown one of its ads, rotated by weight as the email is opened, so use one image size for every ad in the slot. The disclosure label, its position and the alt text live on the slot itself, since the ad changes per reader. Opens and clicks show up in Analytics like any other ad.

Every placement also carries:

  • Audience: logged-out visitors, free members, paying members, and for paying members an optional list of tier IDs to limit it to.
  • Only show on paths and Never show on paths, one per line. Blank means everywhere; a bare / means the home page only.

The ads inside a placement

Add as many ads as you've sold. With more than one, they rotate randomly by weight, so Rotation weight is how the sponsor who bought more gets shown more. Each ad has:

  • a name and an on/off switch, so a finished campaign can be switched off and kept;
  • the Destination URL the click goes to. Clicks pass through our counter on the way, and the destination is read from your saved settings, never from the page, so a link can't be tampered with;
  • Alt text, which is what a screen reader hears and what shows if the image fails;
  • an optional Disclosure label (small italic text such as "advertisement", just outside the ad) and where it sits: above or below, left, centre or right;
  • up to three images, each ticked for the devices it should Show on (Desktop, Tablet, Mobile), so a phone gets a tall block and a desktop a banner. Images come from your site or an upload straight to Ghost. If a reader resizes the window across a breakpoint, the ad swaps to the right image rather than squashing. A newsletter slot's ads carry one image each.

Duplicate copies an ad, and a card can be dragged from one placement to another.

Ads are rendered into your page, not into an iframe, so your theme's CSS can reach them. If the disclosure label's font or colour doesn't suit your site — white on black where you'd rather have black on white — style it from your own stylesheet like anything else on the page.

Analytics

The Analytics tab shows the last 7 or 30 days per ad: Views, Unique views, Clicks, Unique clicks and CTR. A view counts only when at least half the ad was actually on screen, once per page view. "Unique" is per browser per day, kept as a marker in the reader's own browser; no visitor identifier leaves it, there's no third-party network, and nobody is followed around. Newsletter slot ads count an impression when the image is served in the email, and a click the same way as on the web.

Export a report for a sponsor. The tab's CSV control offers each of the last two full calendar months by name, or the last 90 days, and downloads a file you can send to whoever bought the ad. A month still in progress is labelled as possibly incomplete.

Counts lag by several minutes, so clicking your own ad and refreshing straight away shows nothing. That's normal — wait and look again.

What the tool deliberately isn't: an ad network, an exchange, a bidding system, or a payment processor. You sell the ad and you keep the money.

When an ad doesn't appear

Nothing shows anywhere on the site

Check in this order: Ads enabled site-wide is on under Advanced settings; the placement is switched on; the ad inside it is switched on; and the install snippet is in Code injection → Site Footer with that page saved. Then reload the page properly rather than looking at a tab that's been open since before you pasted it.

It shows on some pages but not the one I want

That's the placement's Only show on paths / Never show on paths, or its Audience. Remember you're probably signed in as staff, so a placement limited to logged-out visitors won't show to you — try a private window.

A selector placement puts the ad nowhere, or in the wrong spot

The selector matched nothing, or matched something other than you meant. A selector that matches nothing fails quietly: no ad, no error. Check the spelling, prefer an id over a class, and try the other insertion positions — Before, After and the two Inside options land in visibly different places. Ad targets by theme lists the spots some themes provide on purpose.

Re-check your selector placements after a theme update or a theme change; the old class names may simply be gone.

The adhesion bar sits on top of my text

Your image has a transparent background. The bar itself is transparent by design so only the ad shows, which means a transparent artwork lets the page show through it. Use an image with a solid background for adhesion placements.

The wrong image size is showing

Each image is ticked for the devices it should appear on, and the cut-offs are the Device breakpoints under Advanced settings — which are site-wide, not per ad. An ad with no image ticked for the reader's device shows nothing at all.

I can't upload artwork

Uploading pushes the file into your Ghost media library, so it needs a Ghost Admin API key on your site. Without one, host the image somewhere else and paste its URL instead — everything else works the same.

Contributor access

If you give a contributor an Itty Bitty Ad Server grant (Site settings → Users), manage lets them change placements, ads and settings.