Storyblok Plugin

Introduction

Adds an editor-friendly field in Storyblok to store the Airgentic website embed (full snippet or site key) and optionally declare a Service Hub container (<div id="airgentic"></div>). Your frontend reads this field and injects the script at runtime.

Works With:

Storyblok V2 (Field Plugins, React)

Includes:

Field Plugin UI + optional Next.js helper for injection

Requirements

Storyblok account and a space where you can add Field Plugins.
Node.js 18+ and npm/yarn/pnpm for local plugin development (if you want to customize).
A frontend (Next.js/Nuxt/other) that consumes Storyblok content.
Airgentic embed snippet or Airgentic Site key.

Installation

Option A — Use the provided package (quick start)

Download the bundle:
Create a new Field Plugin in Storyblok (via CLI):

npx @storyblok/field-plugin-cli@latest create
choose: polyrepo → package name → React
cd <your-plugin-folder>
Replace files with the contents of the ZIP:
- Overwrite src/App.tsx with the provided src/App.tsx.
- Add AirgenticProvider.tsx (you’ll copy this into your frontend project, too).
- Keep the generated project config as-is.
Install & build:
- npm install
- npm run build
Deploy the plugin to your Storyblok account/org:
- npx @storyblok/field-plugin-cli@latest deploy
- # choose “My plugins” (or your Organization)
- # Suggested name: "Airgentic Website Integration"

Option B — Start from scratch (if you didn’t use the ZIP)

Initialize a Field Plugin using the Storyblok CLI (React template).
Replace the generated src/App.tsx with the Airgentic plugin UI code.
Build & deploy as above.

Configuration (in Storyblok)

Add the field to a schema
- In Storyblok → Components, open your Global Settings (or a layout/root component).
- Add a new field of type Custom.
- Select Airgentic Website Integration (the plugin you deployed).
Editor options (in the plugin field)
- Enabled: Master on/off toggle.
- Embed snippet: Paste the full <script>…</script> provided by Airgentic (recommended).
- Site key (optional): If you don’t have the full snippet, enter the Site key—your frontend can generate a minimal loader.
- Service Hub container (optional): Toggle + set a container ID (default airgentic); this shows the exact <div id="…"> to render.

ℹ️ Unlike WordPress, Field Plugins do not inject scripts into the live site by themselves. They store config. Your frontend must read the field and inject the snippet (next section).

Frontend Integration

Next.js (App Router) — Recommended

Copy AirgenticProvider.tsx into your frontend (e.g., components/AirgenticProvider.tsx).
Use it in your root layout (ensuring you fetch the Storyblok “global settings” story that contains the plugin field):

// app/layout.tsx

import AirgenticProvider from "@/components/AirgenticProvider";

export default

async function RootLayout({ children }) {

// Implement this to fetch your settings story from Storyblok

const settings = await loadGlobalSettingsFromStoryblok();

return (

<body>

{ /* The plugin value is at settings.content.airgentic */} <AirgenticProvider settings={settings?.content?.airgentic} />

{children}

</body>

</html>

);

}

If Embed snippet is present, it’s injected with next/script.
If only a Site key is set, the provider uses a minimal loader (update the placeholder widget URL to your official Airgentic script).

Nuxt 3 (Vue) — Sketch

Create a client plugin that reads your global settings and injects the snippet or minimal loader. (A ready example can be provided on request.)

Service Hub Container

In WordPress, you used a shortcode that rendered:

<div id="airgentic"></div>
In Storyblok, you can either:
- Add a “Service Hub” block to the page schema, and have your renderer output the div with the configured ID, or
- Render a simple component in your layout or specific pages:

// components/ServiceHub.tsx

export default function ServiceHub({ id = "airgentic" }) {

return <div id={id} />;

}

Editors can toggle the container in the plugin field and see the exact markup to copy/use.

Usage

Editors open Global Settings in Storyblok and configure:
- Enabled = on
- Paste Embed snippet (or set Site key)
- (Optional) Enable Service Hub and confirm Container ID
Deploy/publish content as usual.
The frontend reads the field and injects the script at runtime (no rebuilds required if you fetch settings at request time; otherwise on next deploy/revalidation).

Updates

To update the plugin’s UI/logic:
1. Modify src/App.tsx.
2. npm run build
3. npx @storyblok/field-plugin-cli deploy
To update frontend behavior (e.g., script URL or attributes), edit your AirgenticProvider.tsx and redeploy your site.

Uninstall / Removal

Remove the Custom field using this plugin from your components.
Optional: Remove the plugin from My Plugins in Storyblok if no longer needed.
Remove AirgenticProvider.tsx and any Service Hub components from your frontend.

Troubleshooting

Nothing appears on the live site
Ensure your frontend actually reads the plugin field and injects the snippet. Field Plugins don’t modify the live site by themselves.
Plugin loads but shows “Loading…”
This is normal briefly; it uses the Storyblok Field Plugin SDK hook to initialize. If it persists, check you’re running inside Storyblok’s editor or the local sandbox.
Service Hub not visible
Ensure you’ve rendered <div id="…"> somewhere on the page and that the ID matches the plugin’s configured value.
Security
Don’t store secrets in plugin fields. Keep secret tokens in server env or secure runtime config.

FAQ

Q: Why not a Tool/Space plugin?
A: Those are for editor dashboards and utilities. We need a field attached to content so the frontend can read and inject the website script—hence a Field Plugin.

Q: Can I use this on a single page only?
A: Yes. Put the field on a page-level component, or keep it global and add the Service Hub container only on selected pages.

Q: Does this work without React?
A: The plugin UI here is React-based (supported by Storyblok). Your frontend can be anything (Next.js, Nuxt, Rails, etc.) as long as it reads the field and injects the script.

Support

General CMS/editor questions → Storyblok docs & support.
Airgentic embed specifics (snippet, attributes, site key) → Airgentic support/contact.
Implementation help: happy to tailor the provider for your preferred framework or add a Vue/Nuxt helper on request.

Download Storyblok Plugin

Airgentic