Developer Documentation
Integrate FestiveLayer into any web application or CMS in under 60 seconds. Zero dependencies, strict Shadow DOM containment, and full API control.
1 · 60-Second Quick-Start
Paste this single script tag right before the closing </body> tag on any web page:
<script src="https://cdn.example.com/v1/festive.js"
data-festival="auto" async></script> 2 · Declarative Configuration (data- Attributes)
Configure the engine declaratively directly on the script element without writing JavaScript:
| Attribute | Type | Default | Description |
|---|---|---|---|
| data-festival | string | "auto" | Festival ID (e.g. "christmas", "new-year", "sinhala-tamil-new-year") or "auto" to follow the calendar. Set to "none" to disable. |
| data-intensity | string | number | "medium" | Particle density multiplier: "low" (0.5x), "medium" (1.0x), "high" (1.6x), or numeric float. |
| data-z | number | 999999 | CSS z-index applied to the fixed canvas overlay. |
| data-base | URL | (Auto) | Custom CDN directory path where lazy-loaded festival pack JS files reside. |
| data-key | string | "" | Cryptographically signed domain license token. |
| data-debug | string | "0" | Set to "1" to render live FPS, frame execution time, and active particle counters. |
3 · JavaScript API (window.Festive)
Control the animation dynamically from your own client code:
Festive.start(id?)
Mounts the canvas overlay and begins the animation loop for the given festival ID (or active calendar festival).
Festive.stop()
Halts the animation loop, removes all listeners, and cleanly detaches the overlay from the DOM.
Festive.setFestival(id)
Switches the active pack dynamically (e.g. Festive.setFestival('new-year')) without unmounting.
Festive.setIntensity(level)
Adjusts visual particle density on the fly ('low', 'medium', 'high', or float).
Festive.trigger(action, x?, y?)
Dispatches custom festival events (e.g. 'santa', 'launch', 'lamp', 'kolam', 'firecracker').
4 · Platform Installation Guides
Shopify
In your Shopify Admin, go to Online Store > Themes > Edit code. Open layout/theme.liquid, find </body>, and paste before it:
<!-- Paste immediately above </body> in layout/theme.liquid -->
<script src="https://cdn.example.com/v1/festive.js"
data-festival="auto"
data-intensity="medium"
async></script> WordPress
Use our standalone single-file plugin or paste this hook into your active theme's functions.php:
// Add to functions.php or active child theme
add_action('wp_footer', function() {
echo '<script src="https://cdn.example.com/v1/festive.js" data-festival="auto" data-intensity="medium" async></script>';
}); React & Next.js
Use Next.js Script component with strategy="lazyOnload" in your root layout:
// Next.js App Router (app/layout.tsx)
import Script from "next/script";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<Script
src="https://cdn.example.com/v1/festive.js"
strategy="lazyOnload"
data-festival="auto"
data-intensity="medium"
/>
</body>
</html>
);
} Google Tag Manager (GTM)
Create a Custom HTML Tag with a trigger set to Window Loaded:
<!-- Google Tag Manager: Custom HTML Tag triggered on Window Loaded -->
<script src="https://cdn.example.com/v1/festive.js"
data-festival="auto"
data-intensity="medium"
async></script> Wix & Squarespace
Navigate to Settings > Custom Code / Code Injection, select Body - End, and paste the standard quick-start snippet.