lotame-sdk

TypeScript SDK for Lotame Lightning Tag with:

• browser-safe script loading
• typed collect, page, consent, and identity helpers
• onTagReady / onProfileReady integration
• SSR helpers for rendering Lotame tags in server templates

Install

npm install lotame-sdk

Browser usage

import { createLotameClient } from 'lotame-sdk';

const lotame = createLotameClient({
  clientId: 123,
  audienceLocalStorage: true,
  data: {
    behaviorIds: [1001],
    ruleBuilder: { section: ['sports'] },
  },
});

await lotame.load();
await lotame.collect({ behaviors: { act: ['video play'] } });
await lotame.page({ ruleBuilder: { article_title: ['Example'] } });
await lotame.setEmail('[email protected]');

SSR usage

import { renderLotameSnippet } from 'lotame-sdk/ssr';

const html = renderLotameSnippet({
  clientId: 123,
  config: { autoRun: false },
  data: { ruleBuilder: { section: ['homepage'] } },
});

API highlights

• createLotameClient(options)
• client.load() / client.ready()
• client.collect(data)
• client.page(data?)
• client.setEmail(email)
• client.setHashedEmail(sha256Email)
• client.setConsent(boolean)
• client.getAudiences(limit?)
• client.getPanorama()
• client.on('tagReady' | 'profileReady', listener)

SSR helpers

• getLotameHeadTags(options)
• renderLotameInitScript(options)
• renderLotameScriptTag(options)
• renderLotameSnippet(options)

These helpers follow Lotame's documented initialization pattern and keep the client bootstrap serializable for frameworks like Next.js, Nuxt, and custom Node SSR templates.

Examples

• examples/nextjs contains a small App Router integration showing:
  • SSR tag rendering with getLotameHeadTags()
  • client-side createLotameClient() usage
  • profile/tag-ready event handling
• examples/smoke-test contains a live browser page that imports this package from dist and lets you test with your own Lotame client ID.

Live smoke test

Build the package and run the local smoke-test server:

LOTAME_CLIENT_ID=YOUR_LOTAME_CLIENT_ID npm run smoke-test

Then open http://localhost:4173.

You can also leave LOTAME_CLIENT_ID unset and enter your own Lotame client ID directly in the page.

No real Lotame client ID is bundled in this repo. To perform a live validation, supply your own account's client ID either through the environment variable above or through the smoke-test UI.

Suggested checks:

• Load SDK succeeds and emits tagReady
• Send collect() logs without runtime errors
• Send page() re-runs targeting logic
• Get audiences returns values when your Lotame setup is configured to persist them
• Get panorama returns an ID when available for the current browser and consent state