Skip to main content
The Pillow browser SDK lets you identify website users, store durable traits, and present hosted Pillow studies with the same audience flow as the native SDKs. The current npm package is @trypillow/web.

​
Prerequisites

  • A publishable API key from Developer
  • A live study ID from the Integration tab

​
Install the SDK

npm install @trypillow/web

​
Initialize the SDK

Call init(...) once, as early as possible in your application — typically at the top level of your app, outside of any component render cycle. init(...) returns a singleton: calling it again with the same key returns the existing instance. 
// src/lib/pillow.ts — initialize once, import everywhere
import { init } from '@trypillow/web';

export const pillow = init({
  publishableKey: 'pk_live_...',
});
Initialize the SDK at the app entry point so the audience session is ready before you identify the user or present a study. Do not initialize inside a component that mounts and unmounts — the singleton will persist, but event listeners registered inside that component may become stale.

​
Identify and present

1

Identify the current user

Call setExternalId(...) after login or whenever you know who the user is. Set any properties you want to use for targeting.
import { pillow } from './lib/pillow';

pillow.setExternalId('user_123');
pillow.setUserProperty('plan', 'pro');
2

Listen for events

Register event listeners to react to study lifecycle events.
pillow.on('studyFinish', ({ study }) => {
  console.log('Finished', study.id);
});
3

Present a study

Call presentStudy(...) when you want to open the hosted study.
await pillow.presentStudy(
  { id: 'demo-study' },
  { skipIfAlreadyExposed: true },
);
The Pillow widget shell opens immediately and loads your hosted study.

​
Presentation modes

Use presentation options to switch between the default centered modal, a floating overlay panel, or an inline embed. 
await sdk.presentStudy(
  { id: 'demo-study' },
  {
    presentation: {
      mode: 'embed',
      target: '#pillow-study',
    },
  },
);

await sdk.presentStudy(
  { id: 'demo-study' },
  {
    presentation: {
      mode: 'modal',
      width: 720,
      height: 720,
    },
  },
);

​
What’s next?

Identification

Learn how external IDs and user properties work in the browser SDK.

Studies

Configure study presentation options and widget behavior.

Session management

Reset identity and manage in-progress study sessions.