Skip to main content
Use presentStudy(...) to prepare and open a hosted study for the current browser user. These presentation APIs are part of the @trypillow/web package.

​
Present a study

await sdk.presentStudy({ id: 'demo-study' });
The SDK bootstraps the audience session, prepares the campaign, and opens the Pillow widget shell.

​
Study options

presentStudy accepts an options object as second argument:
OptionTypeDefaultDescription
skipIfAlreadyExposedbooleanfalseSkip presenting if the user has already seen this study. Emits studySkip instead.
forceFreshSessionbooleanfalseIgnore any saved session and start a new conversation.
presentationobject—Layout and appearance options (see below).
await sdk.presentStudy(
  { id: 'demo-study' },
  {
    forceFreshSession: true,
    skipIfAlreadyExposed: true,
    presentation: {
      mode: 'modal',
      width: 720,
      height: 720,
    },
  },
);

​
Presentation options

Control how the study window is displayed by passing presentation in the study options.
OptionTypeDefaultDescription
mode'modal' | 'overlay' | 'embed''modal'How the study is displayed.
position'bottom-right' | 'bottom-left''bottom-right'Corner position. Applies to overlay mode.
zIndexnumber999999CSS z-index for the widget container.
widthnumber | stringMode-dependentWidth of the study window. Numbers are pixels. Strings are used as-is (e.g. '80vw'). Defaults: 400px modal, 360px overlay/embed.
heightnumber | stringMode-dependentHeight of the study window. Defaults: 680px modal, 540px overlay, 520px embed.
borderRadiusnumber | stringMode-dependentCorner radius. Defaults: 24px modal/embed, 20px overlay.
bottomnumber | string20pxBottom offset. Applies to overlay mode.
topnumber | string—Top offset. Applies to overlay mode.
leftnumber | string—Left offset. Applies to overlay mode.
rightnumber | string—Right offset. Applies to overlay mode.
targetstring | HTMLElement | nullnullMount target for embed mode. Pass a CSS selector or a DOM element.
backdropobjectSee belowBackdrop overlay for modal mode.

​
Presentation modes

  • modal — Centered dialog over a full-page backdrop. Dismissed by clicking the backdrop or pressing Escape.
  • overlay — Floating corner panel anchored to position. Dismissed via the close button or Escape.
  • embed — Inline inside a target element. No backdrop or positioning — the study fills the target container.
If you omit mode, the SDK defaults to modal.

​
Backdrop options

Control the overlay behind the study window in modal mode.
OptionTypeDefaultDescription
blurnumber6Backdrop blur radius in pixels.
colorstring'#0f172a'Backdrop tint color (any CSS color value).
alphanumber0.42Backdrop opacity from 0 (transparent) to 1 (opaque).

​
Examples

// Modal with custom size and backdrop
await sdk.presentStudy({ id: 'demo-study' }, {
  presentation: {
    mode: 'modal',
    width: 720,
    height: 720,
    backdrop: { blur: 10, alpha: 0.55, color: '#020617' },
  },
});

// Overlay in the bottom-left corner
await sdk.presentStudy({ id: 'demo-study' }, {
  presentation: {
    mode: 'overlay',
    position: 'bottom-left',
    bottom: 32,
    left: 32,
  },
});

// Embedded inside a container
await sdk.presentStudy({ id: 'demo-study' }, {
  presentation: {
    mode: 'embed',
    target: '#study-container',
    width: '100%',
    height: '100%',
    borderRadius: 0,
  },
});

​
Distribution

You can ship the browser SDK in either of these ways:
  • Import @trypillow/web from your frontend app.
  • Load https://unpkg.com/@trypillow/web/dist/pillow-sdk.min.js with a script tag.

​
Lifecycle events

Register listeners before calling presentStudy(...) to capture every event.
EventPayloadWhen
studyPresent{ study }The study widget has opened.
studySkip{ study }The study was skipped (e.g. skipIfAlreadyExposed matched).
studyFinish{ study }The participant completed the study.
studyError{ study, error }Something went wrong preparing or presenting the study.
sdk.on('studyPresent', ({ study }) => {
  console.log('Presented', study.id);
});

sdk.on('studyFinish', ({ study }) => {
  console.log('Finished', study.id);
});

sdk.on('studySkip', ({ study }) => {
  console.log('Skipped', study.id);
});

sdk.on('studyError', ({ study, error }) => {
  console.error('Failed', study.id, error);
});

await sdk.presentStudy({ id: 'demo-study' });

​
Unsubscribing

on(...) returns an unsubscribe function. Call it when you no longer need the listener — for example, when a component unmounts. 
const unsubscribe = sdk.on('studyFinish', ({ study }) => {
  console.log('Finished', study.id);
});

// Later, when you no longer need this listener:
unsubscribe();
You can also remove a specific listener with off(...): 
function handleFinish({ study }) {
  console.log('Finished', study.id);
}

sdk.on('studyFinish', handleFinish);

// Later:
sdk.off('studyFinish', handleFinish);

​
What’s next?

Getting started

Review the full browser SDK setup flow.

Session management

Clear or reset sessions when the user logs out or restarts a study.