# Reference

Every public method of @screeb/sdk-browser, with its signature.

Complete reference for `@screeb/sdk-browser`. New to Screeb? Start with the [install guide](https://developers.screeb.app/sdk-browser/install).

## Methods by capability

### Lifecycle

| Method                                                                                                                                                         | Description                       | More                                                       |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------- |
| `init(websiteId: string, userId?: string, userProperties?: PropertyRecord, hooks?: HooksInit, language?: string, spaNavigationHandler?: SpaNavigationHandler)` | Initializes Screeb tag.           | [Guide](https://developers.screeb.app/sdk-browser/install) |
| `load(options?: ScreebOptions)`                                                                                                                                | Appends Screeb tag into your dom. | [Guide](https://developers.screeb.app/sdk-browser/install) |
| `close()`                                                                                                                                                      | Shutdowns current Screeb session. | [Guide](https://developers.screeb.app/sdk-browser/install) |

### Identity

| Method                                                      | Description                                                                                                                               | More                                                                                 |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `identity(userId: string, userProperties?: PropertyRecord)` | Change the current user identity.                                                                                                         | [Guide](https://developers.screeb.app/sdk-browser/identity)                          |
| `identityProperties(userProperties: PropertyRecord)`        | Adds properties to the current user identity.                                                                                             | [Guide](https://developers.screeb.app/sdk-browser/identity)                          |
| `identityReset()`                                           | Resets the current user identity.                                                                                                         | [Guide](https://developers.screeb.app/sdk-browser/identity)                          |
| `setAnonymousId(anonymousId: string)`                       | Tells Screeb which anonymous id your CDP already uses for the current visitor (Amplitude device id, Segment or RudderStack anonymous id). | [Guide](https://developers.screeb.app/sdk-browser/identity#2-share-one-anonymous-id) |
| `identityGet(): Promise<ScreebIdentityGetReturn>`           | Retrieves the current user identity.                                                                                                      | [Guide](https://developers.screeb.app/sdk-browser/identity)                          |

### Groups

| Method                                                                                         | Description                            | More                                                                 |
| ---------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------- |
| `identityGroupAssign(groupName: string, groupType?: string, groupProperties?: PropertyRecord)` | Assigns the current user to a group.   | [Guide](https://developers.screeb.app/sdk-browser/group-assignation) |
| `identityGroupUnassign(groupName: string, groupType?: string)`                                 | Unassigns the current user to a group. | [Guide](https://developers.screeb.app/sdk-browser/group-assignation) |

### Tracking

| Method                                                            | Description          | More                                                              |
| ----------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------- |
| `eventTrack(eventName: string, eventProperties?: PropertyRecord)` | Tracks a user event. | [Guide](https://developers.screeb.app/sdk-browser/event-tracking) |

### Surveys

| Method                                                                                                                                                                                                 | Description                  | More                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | -------------------------------------------------------------------------------- |
| `surveyStart(surveyId: string, distributionId?: string, allowMultipleResponses?: boolean, hiddenFields?: PropertyRecord, hooks?: HooksSurveyStart, language?: string, selectors?: string \| string[])` | Starts a survey by its ID.   | [Guide](https://developers.screeb.app/sdk-browser/start-survey-programmatically) |
| `surveyClose()`                                                                                                                                                                                        | Interrupts a running survey. | [Guide](https://developers.screeb.app/sdk-browser/start-survey-programmatically) |

### Messages

| Method                                                                                                                                           | Description                   | More                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | --------------------------------------------------------------------------------- |
| `messageStart(messageId: string, allowMultipleResponses?: boolean, hiddenFields?: PropertyRecord, hooks?: HooksMessageStart, language?: string)` | Starts a message by its ID.   | [Guide](https://developers.screeb.app/sdk-browser/start-message-programmatically) |
| `messageClose()`                                                                                                                                 | Interrupts a running message. | [Guide](https://developers.screeb.app/sdk-browser/start-message-programmatically) |

### Session replay

| Method                 | Description                          | More                                                              |
| ---------------------- | ------------------------------------ | ----------------------------------------------------------------- |
| `sessionReplayStart()` | Starts a session replay.             | [Guide](https://developers.screeb.app/sdk-browser/session-replay) |
| `sessionReplayStop()`  | Interrupts a running session replay. | [Guide](https://developers.screeb.app/sdk-browser/session-replay) |

### Debug

| Method             | Description                                        | More                                                               |
| ------------------ | -------------------------------------------------- | ------------------------------------------------------------------ |
| `debug()`          | Prints the actual state information of Screeb tag. | [Guide](https://developers.screeb.app/sdk-browser/troubleshooting) |
| `targetingDebug()` | Prints the current state of the targeting engine.  | [Guide](https://developers.screeb.app/sdk-browser/troubleshooting) |
| `isLoaded()`       | Checks if Screeb tag has been loaded.              | [Guide](https://developers.screeb.app/sdk-browser/troubleshooting) |

### Privacy helpers

| Method                                                   | Description                                                           | More                                                               |
| -------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `ScreebMaskText<T extends Element>(element: T): T`       | Marks an element as sensitive in Screeb session replay.               | [Guide](https://developers.screeb.app/sdk-browser/privacy-helpers) |
| `ScreebNoCapture<T extends Element>(element: T): T`      | Excludes an element from Screeb session replay capture.               | [Guide](https://developers.screeb.app/sdk-browser/privacy-helpers) |
| `ScreebId<T extends Element>(element: T, id: string): T` | Sets a stable Screeb element ID for IAM targeting and replay context. | [Guide](https://developers.screeb.app/sdk-browser/privacy-helpers) |

## API signatures

### Lifecycle

```ts
export function init(websiteId: string, userId?: string, userProperties?: PropertyRecord, hooks?: HooksInit, language?: string, spaNavigationHandler?: SpaNavigationHandler);
export function load(options?: ScreebOptions);
export function close();
```

### Identity

```ts
export function identity(userId: string, userProperties?: PropertyRecord);
export function identityProperties(userProperties: PropertyRecord);
export function identityReset();
export function setAnonymousId(anonymousId: string);
export function identityGet(): Promise<ScreebIdentityGetReturn>;
```

### Groups

```ts
export function identityGroupAssign(groupName: string, groupType?: string, groupProperties?: PropertyRecord);
export function identityGroupUnassign(groupName: string, groupType?: string);
```

### Tracking

```ts
export function eventTrack(eventName: string, eventProperties?: PropertyRecord);
```

### Surveys

```ts
export function surveyStart(surveyId: string, distributionId?: string, allowMultipleResponses?: boolean, hiddenFields?: PropertyRecord, hooks?: HooksSurveyStart, language?: string, selectors?: string | string[]);
export function surveyClose();
```

### Messages

```ts
export function messageStart(messageId: string, allowMultipleResponses?: boolean, hiddenFields?: PropertyRecord, hooks?: HooksMessageStart, language?: string);
export function messageClose();
```

### Session replay

```ts
export function sessionReplayStart();
export function sessionReplayStop();
```

### Debug

```ts
export function debug();
export function targetingDebug();
export function isLoaded();
```

### Privacy helpers

```ts
export function ScreebMaskText<T extends Element>(element: T): T;
export function ScreebNoCapture<T extends Element>(element: T): T;
export function ScreebId<T extends Element>(element: T, id: string): T;
```

## Hooks

### `HookOnReady`

```ts
type HookOnReady = (data: { channel: Channel; user: User }) => void;
```

### `HookOnSurveyDisplayAllowed`

```ts
type HookOnSurveyDisplayAllowed = (
  data: HookCommonPropertiesSurvey,
) => boolean;
```

### `HookOnMessageDisplayAllowed`

```ts
type HookOnMessageDisplayAllowed = (
  data: HookCommonPropertiesSurvey,
) => boolean;
```

### `HookOnSurveyShowed`

```ts
type HookOnSurveyShowed = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
      items: ResponseItem[];
    };
  },
) => void;
```

### `HookOnSurveyStarted`

```ts
type HookOnSurveyStarted = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
    };
  },
) => void;
```

### `HookOnSurveyCompleted`

```ts
type HookOnSurveyCompleted = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
      items: ResponseItem[];
    };
  },
) => void;
```

### `HookOnSurveyHidden`

```ts
type HookOnSurveyHidden = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
      items: ResponseItem[];
      hide_reason: ResponseStatus;
    };
  },
) => void;
```

### `HookOnMessageShowed`

```ts
type HookOnMessageShowed = (
  data: HookCommonPropertiesMessage & {
    response: {
      id: string;
      items: ResponseItem[];
    };
  },
) => void;
```

### `HookOnMessageStarted`

```ts
type HookOnMessageStarted = (
  data: HookCommonPropertiesMessage & {
    response: {
      id: string;
    };
  },
) => void;
```

### `HookOnMessageCompleted`

```ts
type HookOnMessageCompleted = (
  data: HookCommonPropertiesMessage & {
    response: {
      id: string;
      items: ResponseItem[];
    };
  },
) => void;
```

### `HookOnMessageHidden`

```ts
type HookOnMessageHidden = (
  data: HookCommonPropertiesMessage & {
    response: {
      id: string;
      items: ResponseItem[];
      hide_reason: ResponseStatus;
    };
  },
) => void;
```

### `HookOnQuestionReplied`

```ts
type HookOnQuestionReplied = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
      status: null;
      question: ResponseItemQuestion;
      answer: ResponseItemAnswer;
      items: ResponseItem[];
    };
  },
) => void;
```

### `HookOnButtonNavigateStarted`

```ts
type HookOnButtonNavigateStarted = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
    };
    button: {
      url: string;
      url_target?: string;
    };
  },
) => void;
```

### `HookOnButtonNavigateCompleted`

```ts
type HookOnButtonNavigateCompleted = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
    };
    button: {
      url: string;
      url_target?: string;
    };
  },
) => void;
```

For complete hook payload definitions, see the [JS tag hooks reference](https://developers.screeb.app/sdk-browser/hooks).

## Type definitions

```ts
type PropertyType = number | boolean | string | Date | PropertyRecord;

type PropertyRecord = {
  [key: string]: PropertyType | PropertyType[];
};

type ScreebEndpoints = {
    rpc?: string;
    static?: string;
    report?: string;
    hostedPage?: string;
    centipede?: string;
};

type ScreebOptions = {
    window?: Window;

    sdkName?: string;
    sdkVersion?: string;

    screebEndpoint?: string;

    endpoints?: ScreebEndpoints;

    platform?: string;
};

type SpaNavigationHandler = (url: string) => void | Promise<void>;

type ScreebFunction = (..._: unknown[]) => void | Promise<unknown>;

type ScreebObject = ScreebFunction & {
  q?: {
    args: unknown[];
    ko: (reason?: unknown) => void;
    ok: (value?: unknown) => void;
    v: number;
  }[];
};

type ScreebIdentityGetReturn = {
    anonymous_id: string;
    user_id: string;
    session_id: string;
    session_start: string;
    session_end: string;
    channel_id: string;
    is_ready: boolean;
};

type ChannelType = "widget" | "ios" | "android";

type Channel = {
  id: string;
  type: ChannelType;
};

type User = {
  anonymous_id: string;
  userId?: string;
};

type SurveyFormat = "conversationnal" | "cards";

type SurveySize = 25 | 50 | 75 | 100 | 125 | 150;

type SurveyPosition =
  | "center-left"
  | "center-center"
  | "center-right"
  | "bottom-left"
  | "bottom-center"
  | "bottom-right";

type Survey = {
  id: string;
  survey_position: SurveyPosition;
  survey_format: SurveyFormat;
  survey_size: 100;
};

type Message = {
  id: string;
  messagey_size: 100;
};

type ResponseStatus =
  | "displayed"
  | "started"
  | "ended"
  | "closed"
  | "interrupted";

type ResponseItemQuestion = {
  id: string;
  title: string;
  type: "text" | "video";
  url?: string;
};

type ResponseItemAnswer = {
  replied_at?: string;
  fields?: {
    type: "string" | "number" | "boolean" | "none" | "time" | "file";
    text?: string;
    number?: number;
    boolean?: boolean;
    time?: string;
  }[];
};

type ResponseItem = {
  question: ResponseItemQuestion;
  answer: ResponseItemAnswer;
};

type HookCommonProperties = {
  channel: Channel;
  user: User;
};

type HookCommonPropertiesSurvey = HookCommonProperties & {
  survey: Survey;
};

type HookCommonPropertiesMessage = HookCommonProperties & {
  message: Message;
};

type HookOnReady = (data: { channel: Channel; user: User }) => void;

type HookOnSurveyDisplayAllowed = (
  data: HookCommonPropertiesSurvey,
) => boolean;

type HookOnMessageDisplayAllowed = (
  data: HookCommonPropertiesSurvey,
) => boolean;

type HookOnSurveyShowed = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
      items: ResponseItem[];
    };
  },
) => void;

type HookOnSurveyStarted = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
    };
  },
) => void;

type HookOnSurveyCompleted = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
      items: ResponseItem[];
    };
  },
) => void;

type HookOnSurveyHidden = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
      items: ResponseItem[];
      hide_reason: ResponseStatus;
    };
  },
) => void;

type HookOnMessageShowed = (
  data: HookCommonPropertiesMessage & {
    response: {
      id: string;
      items: ResponseItem[];
    };
  },
) => void;

type HookOnMessageStarted = (
  data: HookCommonPropertiesMessage & {
    response: {
      id: string;
    };
  },
) => void;

type HookOnMessageCompleted = (
  data: HookCommonPropertiesMessage & {
    response: {
      id: string;
      items: ResponseItem[];
    };
  },
) => void;

type HookOnMessageHidden = (
  data: HookCommonPropertiesMessage & {
    response: {
      id: string;
      items: ResponseItem[];
      hide_reason: ResponseStatus;
    };
  },
) => void;

type HookOnQuestionReplied = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
      status: null;
      question: ResponseItemQuestion;
      answer: ResponseItemAnswer;
      items: ResponseItem[];
    };
  },
) => void;

type HookOnButtonNavigateStarted = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
    };
    button: {
      url: string;
      url_target?: string;
    };
  },
) => void;

type HookOnButtonNavigateCompleted = (
  data: HookCommonPropertiesSurvey & {
    response: {
      id: string;
    };
    button: {
      url: string;
      url_target?: string;
    };
  },
) => void;

type HooksSurveyStart = {
    onSurveyShowed?: HookOnSurveyShowed;
    onSurveyStarted?: HookOnSurveyStarted;
    onSurveyCompleted?: HookOnSurveyCompleted;
    onSurveyHidden?: HookOnSurveyHidden;

    onQuestionReplied?: HookOnQuestionReplied;

    onButtonNavigateStarted?: HookOnButtonNavigateStarted;
    onButtonNavigateCompleted?: HookOnButtonNavigateCompleted;
};

type HooksMessageStart = {
    onMessageShowed?: HookOnMessageShowed;
    onMessageStarted?: HookOnMessageStarted;
    onMessageCompleted?: HookOnMessageCompleted;
    onMessageHidden?: HookOnMessageHidden;

    onQuestionReplied?: HookOnQuestionReplied;

    onButtonNavigateStarted?: HookOnButtonNavigateStarted;
    onButtonNavigateCompleted?: HookOnButtonNavigateCompleted;
};

type HooksInit = HooksSurveyStart &
  HooksMessageStart & {
        version: string;

        onReady?: HookOnReady;

        onSurveyDisplayAllowed?: HookOnSurveyDisplayAllowed;
        onMessageDisplayAllowed?: HookOnMessageDisplayAllowed;
  };
```
