Bludit Analytics Integrations: Setup Guide | OpsBlu Docs

Bludit Analytics Integrations: Setup Guide

Integrate GA4, GTM, and Meta Pixel with Bludit CMS using plugins, theme templates, and the custom fields system.

Bludit is a flat-file CMS that stores content in JSON files instead of a database. It is lightweight, requires only PHP, and runs on minimal hosting. Analytics integration uses Bludit's plugin system or direct theme template editing. Because Bludit has no database and no build step, integrations are straightforward but limited to client-side approaches.

Integration Architecture

Bludit provides two primary integration paths:

  1. Plugins -- PHP plugins installed in /bl-plugins/. Bludit includes a "Custom Code" plugin (/bl-plugins/custom-code/) that injects arbitrary HTML into <head> and <body> sections. Additional plugins can be installed from the Bludit plugin directory.
  2. Theme Templates -- PHP template files in /bl-themes/yourtheme/. Edit index.php or include files to add tracking scripts directly.

There is no package manager, no Composer integration, and no admin-level extension marketplace with one-click installation.

Available Integrations

Analytics Platforms

Google Analytics 4

  • Custom Code plugin (paste gtag.js snippet)
  • Theme template injection in index.php

Tag Management

Google Tag Manager

  • Custom Code plugin head/body sections
  • Theme template head/body injection

Marketing Pixels

Meta Pixel

  • Via GTM (recommended)
  • Custom Code plugin head injection

Bludit ships with a built-in "Custom Code" plugin. Enable it at Admin > Plugins > Custom Code. Then navigate to Admin > Plugins > Custom Code > Settings to add:

Head Code -- Add GTM snippet:

<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;
j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;
f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer','GTM-XXXX');</script>
<!-- End Google Tag Manager -->

Body Code -- Add GTM noscript fallback:

<!-- Google Tag Manager (noscript) -->
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXX"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>

The Custom Code plugin calls Theme::plugins('siteHead') and Theme::plugins('siteBodyBegin') hooks, which most themes support.

Building a Data Layer

Bludit exposes page data through PHP helper functions. Add a data layer in your theme's index.php before the GTM snippet:

<?php
  $dataLayer = [
    'pageType' => $page ? $page->type() : 'other',
    'pageTitle' => $page ? $page->title() : $site->title(),
    'category' => $page ? $page->category() : '',
    'tags' => $page ? implode(',', $page->tags(true)) : '',
    'author' => $page ? $page->username() : '',
    'publishDate' => $page ? $page->dateRaw() : '',
    'siteName' => $site->title(),
    'language' => $site->language(),
  ];
?>
<script>
window.dataLayer = window.dataLayer || [];
window.dataLayer.push(<?php echo json_encode($dataLayer); ?>);
</script>

Available Bludit template variables:

  • $page->type() -- Returns published, sticky, static, or draft
  • $page->category() -- Category key for the current page
  • $page->tags(true) -- Array of tag names
  • $page->coverImage() -- Cover image path (useful for structured data)
  • $site->language() -- Site language code (e.g., en)

Platform Limitations

No server-side tracking. Bludit is a flat-file CMS with no backend API for event forwarding. Server-side implementations like Meta Conversions API require an external proxy service.

Plugin hook support varies by theme. The Custom Code plugin relies on Theme::plugins('siteHead') and Theme::plugins('siteBodyBegin') being called in the theme's template. Some minimal or custom themes may not include these hook calls. In that case, you must add tracking code directly to the theme's index.php.

No ecommerce. Bludit is a content-focused CMS with no cart, checkout, or product functionality. Ecommerce tracking events are not applicable.

Flat-file performance ceiling. While Bludit is fast for small sites (no database queries), sites with 500+ pages experience slower page generation. Adding tracking scripts to an already-strained rendering pipeline compounds the issue.

No content staging. Bludit has no draft preview URL or staging environment. Changes to tracking code in themes or plugins go live immediately.

Performance Considerations

  • Minimal baseline. Bludit pages are typically 50-100KB of HTML with minimal CSS. A GTM container with GA4 and Meta Pixel can easily double the total page weight. Keep the tag count low.
  • No asset bundling. Bludit has no build step. Scripts added via plugins or templates load as individual files. Use GTM to consolidate all tracking into a single container.
  • Shared hosting impact. Bludit is often deployed on shared hosting with limited bandwidth. Each additional third-party script adds DNS lookups and TLS handshakes that shared hosting handles poorly.
  • Static site generation. Consider using Bludit's static site generation plugin for maximum performance. Note that dynamic data layer values (page type, category) are baked in at generation time.
  1. Enable Custom Code plugin -- Add GTM head and body snippets
  2. Add data layer to theme -- Expose page metadata for analytics
  3. Configure GA4 in GTM -- Set up pageview and content group tracking
  4. Add Meta Pixel via GTM -- Standard event tracking for content engagement

Next Steps

For general integration concepts, see the integrations overview.

Nach oben