Integration of App Banner

1

Install the SDK

Add ahdjs to your project via NPM or a CDN script tag.

NPM

# Install the package
npm install ahdjs

// Import in your entry file
import AHDjs from 'ahdjs';
import 'ahdjs/build/css/index.css';
import 'https://pagepilot.fabbuilder.com/ahdStyles.css';

CDN

<!-- Add inside <head> -->
<link rel="stylesheet" href="https://unpkg.com/ahdjs/build/css/index.css" />
<link rel="stylesheet" href="https://pagepilot.fabbuilder.com/ahdStyles.css" />
<script src="https://unpkg.com/ahdjs/build/index.js"></script>

<!-- Access the constructor via window -->
const AHDjs = window.AHDjs.default;

2

Initialize AHDjs

Create an instance with your Application ID and API host.

const ahdJs = AHDjs(undefined, {
  applicationId:   'YOUR_APPLICATION_ID',  // from the platform dashboard
  apiHost:         'https://pagepilot.fabbuilder.com',
  visitorId:       'CURRENT_USER_ID',       // required for oneTimeOnly tracking
  showProgressbar: false,
});

💡 Find your Application ID in the platform under Settings → Integration.

ℹ️ visitorId is required for oneTimeOnly — without it the SDK cannot track which visitors have already seen the banner.

3

Add a target element

Place an empty <div> with the banner's identifier as its id.

<!-- The SDK injects rendered banner HTML into this element -->
<div id="your-banner-identifier"></div>

⚠️ The id must exactly match the identifier set when creating the banner in the platform.

4

Render the banner

Call renderAppBanner — the SDK fetches and injects the content.

// async/await
await ahdJs.renderAppBanner('your-banner-identifier', true);

// — or — promise chain
ahdJs.renderAppBanner('your-banner-identifier', true)
  .then(() => console.log('Banner rendered'))
  .catch((err) => console.error(err));

ℹ️

Second parameter — true
Passing true enables visitor-tracking. When oneTimeOnly is set on the banner record, the SDK uses this to suppress the banner for visitors who have already seen it. Always pass true when using oneTimeOnly.

5

Configure the banner in the platform

Create a banner record with these fields.

Field	Description
`identifier`	Unique string that matches the `id` of your target element
`type`	Banner style: `simpleBanner`, `carousel`, or `modal`
`showCloseIcon`	When `true`, renders a close (✕) button so the visitor can dismiss the banner
oneTimeOnly	When `true`, the banner is shown only once per visitor and suppressed on all future renders

Behaviour options

✕

showCloseIcon
Renders a dismiss button in the corner of the banner. When clicked, the banner is hidden for that visitor.

🔁

oneTimeOnly
Shows the banner only once per visitor. After they see or dismiss it, it will not appear again. To reset, call ahdJs.markUnacknowledge(identifier) — see Step 7.

Banner types

📢

simpleBannerFlat inline strip

🎠

carouselSlideshow of slides

🪟

modalOverlay dialog

🔑

Understanding the identifier

Think of it as a name tag that tells the banner exactly where to appear.

An identifier is simply a name you give your banner — like a label on a parcel. You write the same name in three spots, and the system uses it to match the right banner to the right place on your page. If all three names match, the banner shows up. If even one is different, nothing appears.

📦

A simple way to picture it
Imagine labelling a parcel "Summer Sale", reserving a shelf also labelled "Summer Sale", and then asking a helper to "bring the Summer Sale parcel to the Summer Sale shelf." Same name in all three places = it ends up exactly where you want it.

The same name goes in three places

1 · In the platform → When you create the banner, you give it this name

2 · On your page → You mark the empty spot where the banner should appear with the same name

3 · In the code → You tell the system, by name, which banner to show

The same name everywhere — here "summer-sale"

// 1 · In the platform, you name the banner: "summer-sale"

<!-- 2 · On your page, you mark the spot with the same name -->
<div id="summer-sale"></div>

// 3 · In the code, you ask for it by the same name
await ahdJs.renderAppBanner('summer-sale', true);

A few simple rules

Use a different name for each banner — no two banners should share the same name.
Spell it exactly the same way every time — capital and small letters matter, so Summer-Sale is not the same as summer-sale.
Don't rename it later — once your banner is live, changing the name will stop it from showing.
Pick something easy to recognise — short, all-lowercase, words joined by dashes, e.g. welcome-banner or checkout-offer.

⚠️ Banner not showing up? The most common reason is a name that doesn't match. Check that the name is written exactly the same in all three places above — a single typo or capital letter is enough to break it.

6

Enable One-Time-Only display

Show the banner exactly once per visitor — then suppress it automatically.

What oneTimeOnly does

After a visitor sees the banner, the SDK records an acknowledgement tied to the visitorId you passed during initialization.
On every subsequent renderAppBanner call the SDK checks this record — if the visitor has already acknowledged, the container is left empty.
The acknowledgement is stored server-side, so it persists across devices and browser sessions for the same visitorId.

How to enable it — 2 steps

Step A — Platform: Open your banner record in the dashboard and toggle oneTimeOnly to true.

Step B — Code: Pass a stable visitorId during initialization and true as the second argument to renderAppBanner.

// 1. Initialize with a visitorId so the SDK can track this visitor
const ahdJs = AHDjs(undefined, {
  applicationId:   'YOUR_APPLICATION_ID',
  apiHost:         'https://pagepilot.fabbuilder.com',
  visitorId:       'CURRENT_USER_ID',   // ← required for oneTimeOnly
  showProgressbar: false,
});

// 2. Render — SDK silently skips if visitor has already seen it
await ahdJs.renderAppBanner('your-banner-identifier', true);

Runtime flow

renderAppBanner called → Is oneTimeOnly enabled on this banner?

Yes → Has this visitorId already acknowledged it?

No — first time → Banner renders and acknowledgement is recorded

Yes — already seen → Banner suppressed — container stays empty

No — disabled → Banner always renders on every call

Combining with showCloseIcon

When both oneTimeOnly and showCloseIcon are true, dismissing via ✕ also records the acknowledgement — so the banner will not reappear even on page reload.

✅ Best practice: enable both together for welcome banners, announcements, or promotional modals that should appear only on first visit.

⚠️ If visitorId is omitted or changes between sessions, the SDK cannot link acknowledgements and may show the banner again. Always use a stable, unique identifier such as your internal user ID.

7

Re-show a one-time banner — markUnacknowledge()

Clear the acknowledgement so a oneTimeOnly banner is visible again.

Calling markUnacknowledge(identifier) clears the acknowledgement record for the current visitor, so the next renderAppBanner call will display it again.

// Clear acknowledgement for a specific banner
await ahdJs.markUnacknowledge('your-banner-identifier');

// Re-render to show the banner again
await ahdJs.renderAppBanner('your-banner-identifier', true);

ℹ️

Parameter
identifier — the same unique string used in renderAppBanner and the banner record.

⚠️ This only affects the current visitor (identified by visitorId). Other visitors are not affected.

Common use-cases

Scenario	When to call
Re-show after a content update	After publishing new banner content, reset acknowledgement for all visitors server-side or expose a UI button
QA / demo testing	Add a hidden dev button to reset so testers can view the banner repeatedly
Subscription upgrade prompt	Clear when a user downgrades so the upgrade banner shows again

8

Responsive banners — separate designs per screen size

Create a mobile-optimised and a desktop-optimised banner, then let CSS show only the right one.

Because the SDK renders into any <div id="…"> in the page, the recommended pattern is to create two separate banner records in the platform — one for mobile, one for desktop — then use a CSS @media query to hide whichever version doesn't apply.

Why two records instead of one adaptive banner?

Full design control per breakpoint — different copy, images, button sizes, and layout.
Only the visible container receives content; the hidden one is never populated, so there is no wasted render.
Simpler to maintain: update the mobile banner without touching the desktop one.

Breakpoint reference

📱 Mobile0 – 767 px

📟 Tablet768 – 1023 px

🖥 Desktop≥ 1024 px

Adjust the CSS threshold to match your app's own layout breakpoints.

Step A — Create two banner records in the platform

Record	Suggested identifier	Design target
Mobile banner	`welcome-banner-mobile`	Compact layout, stacked content, large tap targets (≤ 767 px)
Desktop banner	`welcome-banner-desktop`	Wide layout, inline content, hover states (≥ 768 px)

Step B — Add two container elements

<!-- Mobile container — hidden on large screens via CSS -->
<div id="welcome-banner-mobile"  class="ahd-banner-mobile"></div>

<!-- Desktop container — hidden on small screens via CSS -->
<div id="welcome-banner-desktop" class="ahd-banner-desktop"></div>

Step C — Hide the off-breakpoint container with CSS

/* Mobile-first: mobile banner visible by default, desktop hidden */
.ahd-banner-mobile  { display: block; }
.ahd-banner-desktop { display: none;  }

@media (min-width: 768px) {
  .ahd-banner-mobile  { display: none;  }
  .ahd-banner-desktop { display: block; }
}

✅ Using CSS display: none is the correct approach. The hidden container still exists in the DOM so the SDK can inject content, but the visitor never sees the wrong version.

ℹ️

Tailwind equivalents
class="block md:hidden" for the mobile container and class="hidden md:block" for the desktop container.

Step D — Render both banners with the SDK

const ahdJs = AHDjs(undefined, {
  applicationId:   'YOUR_APPLICATION_ID',
  apiHost:         'https://pagepilot.fabbuilder.com',
  visitorId:       'CURRENT_USER_ID',
  showProgressbar: false,
});

// Render both in parallel — CSS hides the one that doesn't apply
await Promise.all([
  ahdJs.renderAppBanner('welcome-banner-mobile',  true),
  ahdJs.renderAppBanner('welcome-banner-desktop', true),
]);

React / SPA usage

import { useEffect } from 'react';
import AHDjs from 'ahdjs';
import 'ahdjs/build/css/index.css';

export function WelcomeBanner({ userId }) {
  useEffect(() => {
    const ahdJs = AHDjs(undefined, {
      applicationId:   'YOUR_APPLICATION_ID',
      apiHost:         'https://pagepilot.fabbuilder.com',
      visitorId:       userId,
      showProgressbar: false,
    });

    Promise.all([
      ahdJs.renderAppBanner('welcome-banner-mobile',  true),
      ahdJs.renderAppBanner('welcome-banner-desktop', true),
    ]);
  }, [userId]);

  return (
    <>
      <div id="welcome-banner-mobile"  className="ahd-banner-mobile"  />
      <div id="welcome-banner-desktop" className="ahd-banner-desktop" />
    </>
  );
}

Platform design checklist per record

📱 Mobile record

identifier: welcome-banner-mobile

• Narrow image / icon (≤ 360 px)
• Short, single-line headline
• Full-width CTA button
• Larger font size (≥ 16 px)
• Vertical / stacked layout
• oneTimeOnly: true
• showCloseIcon: true

🖥 Desktop record

identifier: welcome-banner-desktop

• Wide image / illustration
• Longer headline + subtitle
• Inline CTA button (right-aligned)
• Standard font size (14–15 px)
• Horizontal / side-by-side layout
• oneTimeOnly: true
• showCloseIcon: true

9

Multi-language banners — localized content per visitor

Pass a language option so the SDK fetches banner content in the visitor's language.

How language filtering works

The SDK appends filter[language]=<code> to every banner API request.
The platform returns the banner variant whose language tag matches — or falls back to the default variant if no match is found.
Changing the language at runtime clears the SDK's local cache and re-fetches all active content automatically.
No page reload is required — a single setLanguage() call is enough.

Step A — Tag your banner content in the platform

Open the banner record in the dashboard. For each language you want to support, create a content variant and set its Language field to the matching code. Leave one variant's field empty or set it to your default language — this acts as the fallback.

Language	Code	Notes
English	`en`	Default — used when no language is specified
Hindi	`hn`

Step B — Pass the language at initialization

const ahdJs = AHDjs(undefined, {
  applicationId:   'YOUR_APPLICATION_ID',
  apiHost:         'https://pagepilot.fabbuilder.com',
  visitorId:       'CURRENT_USER_ID',
  showProgressbar: false,
  language:        'es',  // ← ISO code; omit or pass '' to use the platform default
});

await ahdJs.renderAppBanner('your-banner-identifier', true);

ℹ️ Omitting language (or passing '') tells the API to return the platform's default variant — typically the English content.

Step C — Switch language at runtime with setLanguage()

Call setLanguage(code) whenever the visitor changes their preferred language. The SDK clears its local cache, re-fetches all active content, and re-renders any banner that was previously displayed — all without a page reload.

// Called when the user picks a new language in your UI
await ahdJs.setLanguage('pt-BR');

// Then re-render to show the localized banner
await ahdJs.renderAppBanner('your-banner-identifier', true);

⚠️ setLanguage() clears the entire SDK cache — banners, tours, highlights, and visitor stats. Call it only when the user actively switches their language preference, not on every render.

Runtime flow

renderAppBanner called → API request includes filter[language]=<code>

Matching variant found → Localized banner content is rendered

No matching variant → Platform falls back to the default-language variant

language: '' (empty) → Platform always serves the default variant

React / SPA — subscribe to app language changes

Create the SDK instance once and call setLanguage() whenever your app's language state changes. Use two separate useEffect hooks so the instance is only recreated when userId changes — not on every language switch.

import { useEffect, useRef } from 'react';
import AHDjs from 'ahdjs';
import 'ahdjs/build/css/index.css';

export function LocalizedBanner({ userId, language }) {
  const ahdRef = useRef(null);

  // Create the instance once per user
  useEffect(() => {
    ahdRef.current = AHDjs(undefined, {
      applicationId:   'YOUR_APPLICATION_ID',
      apiHost:         'https://pagepilot.fabbuilder.com',
      visitorId:       userId,
      showProgressbar: false,
      language:        language || 'en',
    });
    ahdRef.current.renderAppBanner('your-banner-identifier', true);
  }, [userId]);

  // Re-render only when language changes — no instance recreation
  useEffect(() => {
    if (!ahdRef.current || !language) return;
    ahdRef.current.setLanguage(language).then(() =>
      ahdRef.current.renderAppBanner('your-banner-identifier', true)
    );
  }, [language]);

  return <div id="your-banner-identifier" />;
}

⚠️ Keep userId and language in separate useEffect hooks. Combining them recreates the SDK instance on every language change, which resets the oneTimeOnly check and causes unnecessary network calls.

oneTimeOnly with multi-language banners

Acknowledgements are stored against the visitorId + identifier pair — not per language variant. This means:

✅

Acknowledgement covers all language variants
A visitor who saw the English banner will not see it again when they switch to Spanish — the same identifier is acknowledged regardless of language.

ℹ️

Re-show after adding a new translation
After publishing a new language variant, call markUnacknowledge('your-banner-identifier') to reset acknowledgements so all visitors can see the updated content.

⚠️ The language option is a content filter, not a separate banner record. All language variants share the same identifier, oneTimeOnly flag, and acknowledgement record.

✓

Complete example

Drop-in snippet — replace the highlighted values.

<link rel="stylesheet" href="https://unpkg.com/ahdjs/build/css/index.css" />
<script src="https://unpkg.com/ahdjs/build/index.js"></script>

<div id="welcome-banner"></div>
<button onclick="resetBanner()">Show banner again</button>

<script>
  const AHDjs = window.AHDjs.default;

  const ahdJs = AHDjs(undefined, {
    applicationId:   'YOUR_APPLICATION_ID',
    apiHost:         'https://pagepilot.fabbuilder.com',
    visitorId:       'user-123',   // ← stable unique user ID
    showProgressbar: false,
    language:        'en',         // ← optional: ISO code for localized content
  });

  // Renders on load; skipped silently if visitor already saw it and oneTimeOnly=true
  ahdJs.renderAppBanner('welcome-banner', true);

  async function resetBanner() {
    await ahdJs.markUnacknowledge('welcome-banner');
    await ahdJs.renderAppBanner('welcome-banner', true);
  }

  // Switch language at runtime
  async function switchLanguage(code) {
    await ahdJs.setLanguage(code);
    await ahdJs.renderAppBanner('welcome-banner', true);
  }
</script>

Complete responsive + multi-language example

<link rel="stylesheet" href="https://unpkg.com/ahdjs/build/css/index.css" />
<script src="https://unpkg.com/ahdjs/build/index.js"></script>

<div id="welcome-banner-mobile"  class="ahd-banner-mobile"></div>
<div id="welcome-banner-desktop" class="ahd-banner-desktop"></div>

<style>
  .ahd-banner-mobile  { display: block; }
  .ahd-banner-desktop { display: none;  }
  @media (min-width: 768px) {
    .ahd-banner-mobile  { display: none;  }
    .ahd-banner-desktop { display: block; }
  }
</style>

<script>
  const AHDjs = window.AHDjs.default;

  const ahdJs = AHDjs(undefined, {
    applicationId:   'YOUR_APPLICATION_ID',   // ← replace
    apiHost:         'https://pagepilot.fabbuilder.com',
    visitorId:       'user-123',               // ← replace with real user ID
    showProgressbar: false,
    language:        'en',                      // ← replace with visitor's locale
  });

  Promise.all([
    ahdJs.renderAppBanner('welcome-banner-mobile',  true),
    ahdJs.renderAppBanner('welcome-banner-desktop', true),
  ]);

  // Call this whenever the visitor changes their language preference
  async function switchLanguage(code) {
    await ahdJs.setLanguage(code);
    await Promise.all([
      ahdJs.renderAppBanner('welcome-banner-mobile',  true),
      ahdJs.renderAppBanner('welcome-banner-desktop', true),
    ]);
  }
</script>