# Reference

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

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

## Configuration

Pass these options as props of `ScreebProvider`, which wraps your app.

| Option                 | Type                   | Required | Description                                                                           |
| ---------------------- | ---------------------- | -------- | ------------------------------------------------------------------------------------- |
| `websiteId`            | `string`               | Yes      | Your website/channel id.                                                              |
| `userId`               | `string`               | No       | The unique identifier of your user.                                                   |
| `userProperties`       | `PropertyRecord`       | No       | The properties of your user.                                                          |
| `hooks`                | `HooksInit`            | No       | Hooks to define callback for various event.                                           |
| `language`             | `string`               | No       | The language you want to force.                                                       |
| `spaNavigationHandler` | `SpaNavigationHandler` | No       | Optional handler for the `in-page-spa` "Navigate to URL" target (custom SPA routers). |
| `shouldLoad`           | `boolean`              | No       | Indicates if Screeb should be automatically loaded.                                   |
| `autoInit`             | `boolean`              | No       | Indicates if Screeb should be automatically initialized.                              |
| `options`              | `ScreebOptions`        | No       | Screeb tag initialization options.                                                    |

## useScreeb() methods

### Lifecycle

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

### Identity

| Method                                                                          | Description                                                                                                                               | More                                                                               |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `identity(userId: string, userProperties?: PropertyRecord) => Promise<unknown>` | Change the current user identity.                                                                                                         | [Guide](https://developers.screeb.app/sdk-react/identity)                          |
| `identityProperties(userProperties: PropertyRecord) => Promise<unknown>`        | Adds properties to the current user identity.                                                                                             | [Guide](https://developers.screeb.app/sdk-react/identity)                          |
| `identityReset() => Promise<unknown>`                                           | Resets the current user identity.                                                                                                         | [Guide](https://developers.screeb.app/sdk-react/identity)                          |
| `setAnonymousId(anonymousId: string) => Promise<unknown>`                       | 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-react/identity#2-share-one-anonymous-id) |
| `identityGet() => Promise<ScreebIdentityGetReturn>`                             | Retrieves the current user identity.                                                                                                      | [Guide](https://developers.screeb.app/sdk-react/identity)                          |

### Groups

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

### Tracking

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

### Surveys

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

### Messages

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

### Session replay

| Method                                     | Description                          | More                                                            |
| ------------------------------------------ | ------------------------------------ | --------------------------------------------------------------- |
| `sessionReplayStart() => Promise<unknown>` | Starts a session replay.             | [Guide](https://developers.screeb.app/sdk-react/session-replay) |
| `sessionReplayStop() => Promise<unknown>`  | Interrupts a running session replay. | [Guide](https://developers.screeb.app/sdk-react/session-replay) |

### Debug

| Method                                 | Description                                        | More                                                             |
| -------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
| `debug() => Promise<unknown>`          | Prints the actual state information of Screeb tag. | [Guide](https://developers.screeb.app/sdk-react/troubleshooting) |
| `targetingDebug() => Promise<unknown>` | Prints the current state of the targeting engine.  | [Guide](https://developers.screeb.app/sdk-react/troubleshooting) |

### Privacy helpers

| Method                                                     | Description                                              | More                                                             |
| ---------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------- |
| `ScreebMaskText<T extends Element>(element: T) => T`       | Mask a view or component in session replay.              | [Guide](https://developers.screeb.app/sdk-react/privacy-helpers) |
| `ScreebNoCapture<T extends Element>(element: T) => T`      | Exclude a view or component from session replay capture. | [Guide](https://developers.screeb.app/sdk-react/privacy-helpers) |
| `ScreebId<T extends Element>(element: T, id: string) => T` | Set a stable Screeb element ID for IAM targeting.        | [Guide](https://developers.screeb.app/sdk-react/privacy-helpers) |

## API signatures

### Lifecycle

```ts
init(websiteId: string, userId?: string, userProperties?: PropertyRecord, hooks?: HooksInit, language?: string, spaNavigationHandler?: SpaNavigationHandler) => Promise<void>;
load(options?: ScreebOptions) => Promise<void>;
close() => Promise<void>;
```

### Identity

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

### Groups

```ts
identityGroupAssign(groupName: string, groupType?: string, groupProperties?: PropertyRecord) => Promise<unknown>;
identityGroupUnassign(groupName: string, groupType?: string) => Promise<unknown>;
```

### Tracking

```ts
eventTrack(eventName: string, eventProperties?: PropertyRecord) => Promise<unknown>;
```

### Surveys

```ts
surveyStart(surveyId: string, distributionId?: string, allowMultipleResponses?: boolean, hiddenFields?: PropertyRecord, hooks?: HooksSurveyStart, language?: string, selectors?: string | string[]) => Promise<unknown>;
surveyClose() => Promise<unknown>;
```

### Messages

```ts
messageStart(messageId: string, allowMultipleResponses?: boolean, hiddenFields?: PropertyRecord, hooks?: HooksMessageStart, language?: string) => Promise<unknown>;
messageClose() => Promise<unknown>;
```

### Session replay

```ts
sessionReplayStart() => Promise<unknown>;
sessionReplayStop() => Promise<unknown>;
```

### Debug

```ts
debug() => Promise<unknown>;
targetingDebug() => Promise<unknown>;
```

### Privacy helpers

```ts
ScreebMaskText<T extends Element>(element: T) => T;
ScreebNoCapture<T extends Element>(element: T) => T;
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-react/hooks).

## Type definitions

```ts
type ScreebProps = {
    websiteId: string;
    userId?: string;
    userProperties?: PropertyRecord;
    hooks?: HooksInit;
    language?: string;
    spaNavigationHandler?: SpaNavigationHandler;
};

type ScreebContextValues = {
  close: CloseFunction;
  debug: DebugFunction;
  eventTrack: EventTrackFunction;
  identity: IdentityFunction;
  identityGet: IdentityGetFunction;
  identityGroupAssign: IdentityGroupAssignFunction;
  identityGroupUnassign: IdentityGroupUnassignFunction;
  identityProperties: IdentityPropertiesFunction;
  identityReset: IdentityResetFunction;
  setAnonymousId: SetAnonymousIdFunction;
  init: InitFunction;
  load: LoadFunction;
  surveyClose: SurveyCloseFunction;
  surveyStart: SurveyStartFunction;
  messageClose: MessageCloseFunction;
  messageStart: MessageStartFunction;
  sessionReplayStart: SessionReplayStartFunction;
  sessionReplayStop: SessionReplayStopFunction;
  targetingDebug: TargetingDebugFunction;
  ScreebMaskText: ScreebMaskTextFunction;
  ScreebNoCapture: ScreebNoCaptureFunction;
  ScreebId: ScreebIdFunction;
};

type ScreebProviderProps = {
    shouldLoad?: boolean;
    autoInit?: boolean;
    options?: ScreebOptions;
} & Partial<ScreebProps>;

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;
  };
```
