> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trypillow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Install the Pillow browser SDK and present your first study on the web

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

<CodeGroup>
  ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark"}}
  npm install @trypillow/web
  ```

  ```html Script tag theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <script src="https://unpkg.com/@trypillow/web/dist/pillow-sdk.min.js"></script>
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```ts React / SPA theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // src/lib/pillow.ts: initialize once, import everywhere
  import { init } from '@trypillow/web';

  export const pillow = init({
    publishableKey: 'pk_live_...',
  });
  ```

  ```html Script tag theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <script src="https://unpkg.com/@trypillow/web/dist/pillow-sdk.min.js"></script>
  <script>
    var pillow = Pillow.init({
      publishableKey: 'pk_live_...',
    });
  </script>
  ```
</CodeGroup>

<Note>
  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.
</Note>

## Identify and present

<Steps>
  <Step title="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.

    ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import { pillow } from './lib/pillow';

    pillow.setExternalId('user_123');
    pillow.setUserProperty('plan', 'pro');
    ```
  </Step>

  <Step title="Listen for events">
    Register event listeners to react to study lifecycle events.

    ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
    pillow.on('studyFinish', ({ study }) => {
      console.log('Finished', study.id);
    });
    ```
  </Step>

  <Step title="Present a study">
    Call `presentStudy(...)` when you want to open the hosted study.

    ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
    await pillow.presentStudy(
      { id: 'demo-study' },
      { skipIfAlreadyExposed: true },
    );
    ```

    <Check>
      The Pillow widget shell opens immediately and loads your hosted study.
    </Check>
  </Step>
</Steps>

## Presentation modes

Use presentation options to switch between the default centered modal, a floating overlay panel, or an inline embed.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
await sdk.presentStudy(
  { id: 'demo-study' },
  {
    presentation: {
      mode: 'embed',
      target: '#pillow-study',
    },
  },
);
```

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
await sdk.presentStudy(
  { id: 'demo-study' },
  {
    presentation: {
      mode: 'modal',
      width: 720,
      height: 720,
    },
  },
);
```

## What's next

<CardGroup cols={3}>
  <Card title="Identification" icon="badge-check" href="/sdk/web/identification">
    Learn how external IDs and user properties work in the browser SDK.
  </Card>

  <Card title="Studies" icon="message-square" href="/sdk/web/studies">
    Configure study presentation options and widget behavior.
  </Card>

  <Card title="Session management" icon="refresh-cw" href="/sdk/web/session-management">
    Reset identity and manage in-progress study sessions.
  </Card>
</CardGroup>