AdSense & Donation Banners

A small module for showing a dismissible donation banner or a Google AdSense unit at the top, bottom, or sidebar of your page. This is the module that powers the banner on this documentation site.

💡 Site-only module. Unlike most modules on this site, onigiri-adsense.js isn't part of the core OnigiriJS framework repository - it ships alongside this documentation site's own source, in static/js/.

Features

Donation banner - a configurable call-to-action banner with a donate link and a close button
AdSense banner - injects an <ins class="adsbygoogle"> unit and loads the AdSense script for you
Dismiss memory - remembers a dismissal for a configurable duration, via Onigiri.storage when available, falling back to localStorage
Escaped by default - banner title/message/button text are HTML-escaped before rendering, so values pulled from a CMS field or translation file can't inject markup

Quick Start

1. Include the Module

<script src="/static/js/onigiri-adsense.js"></script>

Note: this module lives in this site's own static/js/ directory, not the framework's jsDelivr-hosted src/framework/ tree - point your <script> tag at wherever you've copied it in your own project.

2. Initialize

Onigiri.adsense.init({
    enableDonation: true,
    enableAdSense: false,
    donationUrl: 'https://github.com/sponsors/your-username',
    position: 'top',
    dismissible: true,
    autoShow: true
});

✅ That's it! A donation banner will appear automatically if autoShow is enabled.

API Reference

Configuration Options

Option	Type	Default	Description
`adClient`	String	null	Your AdSense publisher ID (e.g. `ca-pub-xxxxxxxx`)
`adSlot`	String	null	Default ad slot ID
`autoShow`	Boolean	true	Show a banner automatically on `init()`
`dismissible`	Boolean	true	Show a close button and remember the dismissal
`dismissCookieName`	String	'onigiri_donation_dismissed'	Storage key used to remember the dismissal
`dismissDuration`	Number	604800000 (7 days)	How long a dismissal is remembered, in milliseconds
`position`	String	'top'	`'top'`, `'bottom'`, or `'sidebar'`
`animationDuration`	Number	300	Fade in/out duration in milliseconds
`donationUrl`	String	null	Link used for the donate button
`donationText`	String	'Support our project'	Reserved for future use in the default template
`enableAdSense`	Boolean	false	Show an AdSense unit instead of/alongside the donation banner
`enableDonation`	Boolean	true	Show the donation banner

When both enableDonation and enableAdSense are true, showBanner() shows the donation banner (it's checked first). Call createAdSenseBanner() directly if you want both on the page at once.

Methods

Onigiri.adsense.init(options)

Merges your options into the module config, injects the module's stylesheet, checks whether the banner was previously dismissed, and (if autoShow is true) shows a banner. Safe to call once per page load.

Onigiri.adsense.showBanner()

Creates and mounts a banner based on the current config (enableDonation vs enableAdSense). Does nothing if the banner was already dismissed within dismissDuration.

Onigiri.adsense.createDonationBanner(options)

Builds (but doesn't mount) a donation banner. Returns { id, element, mount(), unmount() }.

const banner = Onigiri.adsense.createDonationBanner({
    title: 'Enjoying OnigiriJS?',
    message: 'Consider sponsoring development.',
    theme: 'dark'
});
banner.mount();

Onigiri.adsense.createAdSenseBanner(options)

Builds (but doesn't mount) an AdSense banner. Requires adClient to be configured. Returns the same { id, element, mount(), unmount() } shape.

Onigiri.adsense.clearDismissed()

Clears the stored dismissal, so the banner will show again on the next showBanner() call.

Events

Event	Fired when
`onigiri:adsense:ready`	`init()` has finished
`onigiri:adsense:mounted`	A banner has been added to the page (`detail: { bannerId, element }`)
`onigiri:adsense:unmounted`	A banner has been removed (`detail: { bannerId }`)
`onigiri:adsense:dismissed`	The visitor closed a dismissible banner (`detail: { bannerId }`)

Security Notes

Banner title, message, and button text are HTML-escaped before being inserted into the page (via Onigiri.security.sanitizeHTML when loaded, or an inline fallback otherwise). If you source these strings from a translation file or CMS, this prevents an edited string from injecting markup.
The dismiss flag is stored client-side (via Onigiri.storage or localStorage) - it is not a server-verified consent record.