Documentation

MacroBoarding turns your product's knowledge base into in-app onboarding: an activation checklist, product tours, a welcome modal and an announcement bar, delivered by one script tag and measured as an activation funnel.

Quickstart

1. Create an account. You get a project with a public key (mb_…).
2. Connect your MacroPrimer knowledge base under Knowledge base.
3. Under Onboarding, generate a draft, edit what you like, preview it, and publish.
4. Under Install, copy the script tag and the track() line for each milestone into your app.

<script src="https://macroboarding.com/b.js" data-mb-key="mb_..."></script>

Put it on every page of your app. It is small, loads synchronously so window.MacroBoarding exists for the next line of your code, and does its network work in the background. Nothing renders until a plan is published.

Connecting MacroPrimer

MacroPrimer builds a knowledge base from your repository: features, use cases with their steps, a glossary, and every screen and route with what it is for and what its buttons do. MacroBoarding reads it with an API key that you mint and control.

1. In MacroPrimer, open Settings → API keys → Create key.
2. Grant knowledge:read (required) and workspace:read (optional — links your help center from the checklist).
3. Paste the mp_live_… key into MacroBoarding. We check its permissions first, then import.

The key is encrypted at rest and only ever sent to api.macroprimer.com. Importing makes about 15 requests against your MacroPrimer rate limit. Click Refresh after your product changes, then regenerate. Revoking the key in MacroPrimer cuts MacroBoarding off immediately; already-published onboarding keeps working.

The onboarding plan

Everything the snippet shows lives in one plan, which you edit as a draft and publish when it reads right.

Welcome

A modal shown once per user on first load. Its button opens the checklist, starts a tour, or goes to a page.

Activation checklist

A launcher with a progress ring, opening to your milestones. A user who completes every milestone is activated — that is the number the dashboard tracks. Each item can carry a “Show me” button that starts a tour or opens a page.

Tours

Step-by-step cards. A step with a CSS selector spotlights that element; without one, or if the element isn't on the page, the step shows as a centered card. A tour starts from a button, from MacroBoarding.startTour(id), or automatically the first time a user lands on a matching path such as /dashboard or /projects/*.

Announcement bar

A dismissible bar across the top of the page, with an optional link.

Generating

Generate with AI reads the knowledge base and designs milestones around the moments that deliver value, tours that use your real labels, and a welcome specific to your product, then explains its choices. Draft from knowledge base is instant and deterministic: use cases become milestones and how-to tours, and top features become a quick tour. Both replace the draft only — what is live changes when you publish.

Milestones

Each milestone completes one of four ways:

• Your code calls track() — the most reliable. Call it in the success path of the action.
• The user visits a page — a path glob like /settings/team*. Works with single-page-app navigation.
• The user clicks an element — a CSS selector such as #connect-button.
• The user ticks it off — for things you can't observe.

// after the order saves
MacroBoarding.track("order_created");

Event names are lowercase snake_case, up to 64 characters. The Install page prints the exact name each milestone waits for, along with the note the generator wrote about where the call belongs.

Identifying users

Without identify(), progress is kept per browser. With it, progress follows the person across devices, and anything they did before signing in is carried over.

MacroBoarding.identify("user_123", {
  email: "ana@example.com",
  createdAt: "2026-10-06T12:00:00Z"
});

Traits are flat: up to 20 string, number or boolean values. createdAt powers Only new users: when that is on, users whose createdAt is older than the window — or missing — see nothing. You can also set window.MacroBoardingUser = { id: "user_123", ... } before the script tag.

JavaScript API

Calls made before the plan has loaded are queued and applied once it arrives.

Server API

Many activation moments happen on a backend — a payment clears, an import finishes. Create a secret key under Settings → Keys (shown once; we store only a hash) and call:

curl -X POST https://macroboarding.com/api/v1/events \
  -H "Authorization: Bearer $MACROBOARDING_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_123", "event": "order_created", "traits": {"plan": "pro"}}'

The response includes the user's completed milestones. To read progress — for example to gate a feature until activation:

curl "https://macroboarding.com/api/v1/progress?userId=user_123" \
  -H "Authorization: Bearer $MACROBOARDING_SECRET_KEY"

{ "userId": "user_123", "completed": ["create-order"], "total": 3, "activated": false }

Errors use { "error": { "type", "message" } }: 401 bad key, 409 nothing published, 422 invalid input, 429 rate limited (honour Retry-After). Keep the secret key on your server.

Security & data

• The public key can only read your published plan and report progress. Set Allowed origins once you are live so it works only on your domains.
• Isolation. The UI renders in a shadow root: your CSS can't break it, and it can't restyle your app. Every piece of plan text is inserted as text, never HTML, and links accept only https:, http: or same-site paths.
• What we store about your users: the id you pass to identify() (or a random browser id), the traits you send, which milestones and tours they completed and when. Nothing else — no page content, no keystrokes, no cookies.
• Your MacroPrimer key is encrypted with AES-256-GCM and used only to read your knowledge base.