agentleFS
dream-horizon-orgdream-horizon-org/pulse/.agents/skills/integrate-pulse-web-sdk/SKILL.md

integrate-pulse-web-sdk

Skill44 starsChanged 5 months agoApache-2.0View on GitHub

Integrate @dreamhorizonorg/pulse-web into a host app (vanilla JS, React SPA, React Router, Next.js App/Pages Router). Use when adding Pulse Web RUM/OTEL to a new or existing frontend, wiring PulseProvider, trackEvent, setUserId, verifying integration success, or debugging OTLP export failures.

  • Reads credentials
  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 5 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add @dreamhorizonorg/pulse-web RUM to a host application.

    line 12
  2. Very specific:

    Do not: call Pulse.init and wrap PulseProvider for the same app — the provider calls init once.

    line 29
  3. Distinctive:

    Create a small config module (read API key from env.

    line 87
  4. Very specific:

    Singleton bundling: ensure one copy of @dreamhorizonorg/pulse-web (webpack/vite alias if linking local SDK — see ecommerce-demo …

    line 115
  5. Very specific:

    Webpack alias: when developing against monorepo SDK — use ESM dist/*.js entries so one Pulse singleton (see nextjs-demo/next.config.ts).

    line 146
  6. Very specific:

    Use useNextPagesRouterTracking or exported pages helper from @dreamhorizonorg/pulse-web/next

    line 153
  7. Distinctive:

    After login (when user id is known):

    line 160
  8. Very specific:

    Avoid importing heavy app constants barrels from RUM helpers (circular deps) — use a tiny local constants file.

    line 184
  9. Distinctive:

    Leave key empty to disable RUM (provider no-op pattern).

    line 201
  10. Distinctive:

    If all P0 pass → integration is successful: Stop and report pass/fail table.

    line 221
  11. Distinctive:

    Wait 2–3s for SDK init.

    line 262
  12. Very specific:

    Run query-clickhouse command (SELECT only).

    line 276
  13. Very specific:

    If adding default-project interaction seeds for new trackEvent names: update backend/db/shared/mysql-default-project-interactions.sql + …

    line 349
  14. Very specific:

    Do not: use web-sdk-ship for host-only integration — that skill is for SDK package changes.

    line 350

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Integrate Pulse Web SDK

Add @dreamhorizonorg/pulse-web RUM to a host application. This skill is for consumers of the npm package — not for implementing instrumentations inside pulse-web-otel/ (use web-sdk-instrument for that).

Canonical specs: pulse-web-otel/docs/instrumentations/integration/SPEC.md
Reference patterns: reference.md


1. Pick the integration path

HostImport pathInit
Vanilla JS (Vite, webpack, static HTML)@dreamhorizonorg/pulse-webawait Pulse.init(config) once before app boot
React SPA (CRA, Vite + React)@dreamhorizonorg/pulse-web/react<PulseProvider config={...}> at root
React + React Router v6above + @dreamhorizonorg/pulse-web/react/router<PulseRouterEvents /> inside <BrowserRouter>
Next.js App Router@dreamhorizonorg/pulse-web/nextClient PulseProvider + PulseRouterEvents in layout
Next.js Pages Router@dreamhorizonorg/pulse-web/nextPulseProvider in _app.tsx + pages router hook

Do not call Pulse.init and wrap PulseProvider for the same app — the provider calls init once.


2. Install

yarn add @dreamhorizonorg/pulse-web
# or: npm install @dreamhorizonorg/pulse-web

Pin version from the consuming app's needs (monorepo: check pulse-web-otel/package.json).


3. Minimal config (all frameworks)

Required on PulseWebConfig:

FieldNotes
apiKeyProject API key (e.g. default-project_devkey01 for local Pulse stack)
dataCollectionStatePulseDataCollectionConsent.ALLOWED to enable collectors
serviceNameApp identifier in Pulse (e.g. "my-storefront")
serviceVersionOptional but recommended (app version string)

Do not pass endpoint from env unless there is a documented edge case (Capacitor WebView, custom collector). The SDK resolves OTLP from the API key:

  • default-project_* → http://localhost:4318
  • prod keys → Pulse cloud collector

4. Framework workflows

4a. Vanilla JS

import { Pulse, PulseDataCollectionConsent } from "@dreamhorizonorg/pulse-web";

const config = {
  apiKey: import.meta.env.VITE_PULSE_API_KEY,
  dataCollectionState: PulseDataCollectionConsent.ALLOWED,
  serviceName: "my-app",
  serviceVersion: "1.0.0",
};

await Pulse.init(config);
// optional: expose for debugging
globalThis.Pulse = Pulse;
  • Init after DOM ready (or in main() before routing).
  • Manual navigation: call Pulse.setScreenName(name) on route changes if not using a router adapter.
  • Reference: pulse-web-otel/examples/web-sdk-docs/src/main.js

4b. React SPA (Vite / CRA)

  1. Create a small config module (read API key from env; no-op when key missing).
  2. Wrap the app root:
import { PulseProvider } from "@dreamhorizonorg/pulse-web/react";
import { PulseDataCollectionConsent } from "@dreamhorizonorg/pulse-web";

<PulseProvider config={{
  apiKey: process.env.REACT_APP_PULSE_WEB_API_KEY!,
  dataCollectionState: PulseDataCollectionConsent.ALLOWED,
  serviceName: "my-app",
  serviceVersion: "1.0.0",
}}>
  {children}
</PulseProvider>
  1. React Router v6 — inside BrowserRouter:
import { PulseRouterEvents } from "@dreamhorizonorg/pulse-web/react/router";

<BrowserRouter>
  <PulseRouterEvents />
  {routes}
</BrowserRouter>
  1. Singleton bundling: ensure one copy of @dreamhorizonorg/pulse-web (webpack/vite alias if linking local SDK — see ecommerce-demo vite.config.ts).

Reference: pulse-web-otel/examples/ecommerce-demo/src/Root.tsx, pulse-ui/src/pulse-web-rum/

4c. Next.js (App Router)

  1. "use client" provider wrapper (SDK touches window):
// app/providers/PulseProvider.tsx
"use client";
import { PulseProvider, PulseRouterEvents } from "@dreamhorizonorg/pulse-web/next";
import { PulseDataCollectionConsent } from "@dreamhorizonorg/pulse-web";

export function AppPulseProvider({ children }: { children: React.ReactNode }) {
  return (
    <PulseProvider config={{
      apiKey: process.env.NEXT_PUBLIC_PULSE_API_KEY!,
      dataCollectionState: PulseDataCollectionConsent.ALLOWED,
      serviceName: "my-app",
      serviceVersion: process.env.NEXT_PUBLIC_APP_VERSION ?? "1.0.0",
    }}>
      <PulseRouterEvents />
      {children}
    </PulseProvider>
  );
}
  1. Mount in root layout.tsx (outside RSC-only boundaries).
  2. Optional build: withPulseConfig from @dreamhorizonorg/pulse-web/next-config for source maps (prod crash deobfuscation).
  3. Webpack alias when developing against monorepo SDK — use ESM dist/*.js entries so one Pulse singleton (see nextjs-demo/next.config.ts).

Reference: pulse-web-otel/examples/nextjs-demo/app/pulse-provider.tsx, lottery-demo/app/providers/PulseProvider.tsx

4d. Next.js (Pages Router)

  • PulseProvider in pages/_app.tsx
  • Use useNextPagesRouterTracking or exported pages helper from @dreamhorizonorg/pulse-web/next
  • Reference: pulse-web-otel/examples/nextjs-demo/pages/_app.tsx

5. User identity & custom events (all frameworks)

After login (when user id is known):

import { Pulse } from "@dreamhorizonorg/pulse-web";

Pulse.setUserId(userId);
Pulse.setUserProperties({ email, tenant_id: tenantId }); // optional

On logout:

Pulse.clearUserIdentity();

Product analytics:

Pulse.trackEvent("checkout_started", { cart_items: 3 });

Host-app patterns (centralize in one helper module):

  • Auto-attach project_id / tenant_id from session storage or cookies in a trackEvent wrapper — avoid repeating on every call site.
  • Avoid importing heavy app constants barrels from RUM helpers (circular deps) — use a tiny local constants file.
  • Fire *_loaded events once per screen visit for interaction configs.

See pulse-ui/src/pulse-web-rum/.


6. Environment variables (build-time)

ToolAPI key env var
ViteVITE_PULSE_API_KEY
CRA / webpackREACT_APP_PULSE_WEB_API_KEY
Next.jsNEXT_PUBLIC_PULSE_API_KEY

Values are inlined at build time for static/SPA deploys. Docker: pass as ARG/ENV in the UI Dockerfile (see pulse-ui/Dockerfile, deploy/docker-compose.yml).

Leave key empty to disable RUM (provider no-op pattern).


7. Success criteria

Integration is successful only when P0 (must-pass) checks pass. P1/P2 are follow-ups for product analytics and interaction configs.

P0 — Core SDK alive (integration successful)

#CriterionHow to verify
1SDK initializedPulse.isInitialized() === true in browser console after load
2Consent allows collectiondataCollectionState === ALLOWED in config
3Session createdlocalStorage.pulse_session_id set within ~2s of init
4Installation IDlocalStorage.pulse_installation_id set
5OTLP export succeedsDevTools Network: POST …/v1/traces or /v1/logs → 2xx (not blocked/CORS/failed)
6session.start emittedSession keys present (see lottery-demo PulseHealthCheck step 7)
7No init errorsBrowser console: no TDZ/circular-import errors from RUM module; no duplicate-init warnings

If all P0 pass → integration is successful. Stop and report pass/fail table.

P1 — Navigation & identity (SPA / auth apps)

#CriterionHow to verify
8Router adapter mountedNavigate between routes → new screen_load / screen_session OTLP batches
9setUserId after loginUser id on subsequent spans/logs (Pulse Debug Panel or ClickHouse UserId)
10clearUserIdentity on logoutUser id cleared on next session signals

P2 — Product events & Pulse UI (optional)

#CriterionHow to verify
11Custom trackEventClickHouse otel_logs with expected event name + Platform = 'web'
12Interaction configsPulse UI → Interactions shows journey completion (requires MySQL seeds)

Local stack: cd deploy && ./scripts/start.sh -d — collector 4318, UI 3000.


8. Autonomous verify & debug loop

After wiring integration, the agent MUST run this loop without asking the user (unless blocked by login, missing env, or app won't start).

Step A — Preconditions

# Pulse stack (monorepo)
cd deploy && ./scripts/start.sh -d
docker ps --filter name=pulse-otel-collector --format '{{.Status}}'

# Host app (example)
cd <host-app> && yarn dev   # note port

Confirm API key env var is set at build/runtime (empty key = RUM disabled by design).

Step B — Browser verification (use browser MCP or ask user to open app)

  1. Navigate to app URL (e.g. http://localhost:3001).
  2. Wait 2–3s for SDK init.
  3. browser_console_messages — scan for Pulse/RUM errors.
  4. browser_network_requests — filter for 4318 or /v1/traces, /v1/logs; expect 2xx.
  5. Optional: trigger one navigation + one click to confirm extra exports.

Dev-only helpers (copy from reference apps if missing):

  • PulseHealthCheck — logs P0 steps 1–7 to console (lottery-demo/app/components/PulseHealthCheck.tsx)
  • PulseDebugPanel — Shift+P OTLP traffic overlay (pulse-web-otel/examples/ecommerce-demo/src/components/PulseDebugPanel.tsx)

Expose SDK in dev: globalThis.Pulse = Pulse after init for console checks.

Step C — Backend confirmation (ClickHouse)

Run query-clickhouse command (SELECT only). Example — recent web sessions for project:

SELECT Timestamp, ServiceName, PulseType, SessionId, UserId
FROM otel.otel_traces
WHERE ProjectId = 'default-project'
  AND Platform = 'web'
  AND ServiceName = '<your-serviceName>'
  AND Timestamp > now() - INTERVAL 15 MINUTE
ORDER BY Timestamp DESC
LIMIT 20

Custom events:

SELECT Timestamp, LogAttributes['event.name'] AS event_name, SessionId
FROM otel.otel_logs
WHERE ProjectId = 'default-project'
  AND Platform = 'web'
  AND PulseType = 'custom_event'
  AND Timestamp > now() - INTERVAL 15 MINUTE
LIMIT 20

Replace ServiceName / ProjectId from apiKey prefix.

Step D — Diagnose failures (fix and re-run loop)

SymptomLikely causeFix
Pulse.isInitialized() === falseMissing key, provider not mounted, SSR initClient boundary; check env var inlined at build
No OTLP requestsConsent denied, key empty, collector downALLOWED; start stack; check 4318
OTLP 403/401Bad API keyUse default-project_devkey01 locally
OTLP CORS/network errorCollector not reachable from browser hostStart collector; Capacitor → LAN IP + optional endpoint
Duplicate singleton / weird initTwo @dreamhorizonorg/pulse-web copiesWebpack/vite alias to one ESM dist
TDZ / Cannot access 'X' before initializationCircular import in RUM helpersSplit constants; never import app barrels from RUM
Session keys missingInit race or consent offDelay health check 500ms; verify ALLOWED
Traces in Network but not ClickHouseCollector → CH pipeline lagWait 30s; check docker logs pulse-otel-collector
Remote config 403 (prod origin)CORS allowlistSee integration SPEC §R5; local keys skip this

Loop: fix → rebuild if env changed → reload app → re-run Steps B–C until P0 all pass or report blocker.

Step E — Report

Output a short table:

Pulse Web SDK integration verification
- P0: 7/7 pass | FAIL: <list>
- P1: n/a or x/y
- P2: n/a or x/y
- Blockers: <none | description>

9. Anti-patterns

Don'tDo instead
Import @dreamhorizonorg/pulse-web from deep internal pathsUse documented exports subpaths only
Pass OTLP endpoint in normal web deploysLet SDK resolve from apiKey
Pulse.init + PulseProvider togetherProvider only
Init in Server Components / SSRClient-only boundary ("use client", useEffect, or provider)
Raw fetch for app API if network spans neededUse instrumented fetch or SDK network config
Invent new pulse.type valuesUse existing semconv; see docs/sdk-core/data-contract/SPEC.md

10. When done in Pulse monorepo

  • Host app outside pulse-web-otel/: commit integration in that repo only.
  • If adding default-project interaction seeds for new trackEvent names: update backend/db/shared/mysql-default-project-interactions.sql + host doc (see lottery-demo / pulse-ui interaction docs).
  • Do not use web-sdk-ship for host-only integration — that skill is for SDK package changes.

Additional resources

  • reference.md — env matrix, file layout template, example paths
  • pulse-web-otel/docs/instrumentations/integration/SPEC.md
  • pulse-web-otel/docs/instrumentations/nextjs-integration/SPEC.md
  • pulse-web-otel/docs/sdk-core/config-and-public-api/SPEC.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.