Reference

Complete reference for @screeb/sdk-react.

✨ New to Screeb? Start with the Install guide.

Configuration

Option	Type	Required	Description
websiteId	string	Yes	-
userId	string	No	-
userProperties	PropertyRecord	No	-
hooks	HooksInit	No	-
language	string	No	-
shouldLoad	boolean	No	-
autoInit	boolean	No	-
options	ScreebOptions	No	-

useScreeb() methods

Lifecycle

Method	Description	More
init(websiteId: string, userId?: string, userProperties?: PropertyRecord, hooks?: HooksInit, language?: string) => Promise<void>	Initializes Screeb tag.	👉
load(options?: ScreebOptions) => Promise<void>	Appends Screeb tag into your dom.	👉
close() => Promise<void>	Shutdowns current Screeb session.	👉

Identity

Method	Description	More
identity(userId: string, userProperties?: PropertyRecord) => Promise<unknown>	Change the current user identity.	👉
identityProperties(userProperties: PropertyRecord) => Promise<unknown>	Adds properties to the current user identity.	👉
identityReset() => Promise<unknown>	Resets the current user identity.	👉
identityGet() => Promise<ScreebIdentityGetReturn>	Retrieves the current user identity.	👉

Groups

Method	Description	More
identityGroupAssign(groupName: string, groupType?: string, groupProperties?: PropertyRecord) => Promise<unknown>	Assigns the current user to a group.	👉
identityGroupUnassign(groupName: string, groupType?: string) => Promise<unknown>	Unassigns the current user to a group.	👉

Tracking

Method	Description	More
eventTrack(eventName: string, eventProperties?: PropertyRecord) => Promise<unknown>	Tracks a user event.	👉

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.	👉
surveyClose() => Promise<unknown>	Interrupts a running survey.	👉

Messages

Method	Description	More
messageStart(messageId: string, allowMultipleResponses?: boolean, hiddenFields?: PropertyRecord, hooks?: HooksMessageStart, language?: string) => Promise<unknown>	Starts a message by its ID.	👉
messageClose() => Promise<unknown>	Interrupts a running message.	👉

Session replay

Method	Description	More
sessionReplayStart() => Promise<unknown>	Starts a session replay.	👉
sessionReplayStop() => Promise<unknown>	Interrupts a running session replay.	👉

Debug

Method	Description	More
debug() => Promise<unknown>	Prints the actual state information of Screeb tag.	👉
targetingDebug() => Promise<unknown>	Prints the current state of the targeting engine.	👉

Privacy helpers

Method	Description	More
ScreebMaskText<T extends Element>(element: T) => T	Mask a view or component in session replay.	👉
ScreebNoCapture<T extends Element>(element: T) => T	Exclude a view or component from session replay capture.	👉
ScreebId<T extends Element>(element: T, id: string) => T	Set a stable Screeb element ID for IAM targeting.	👉

API signatures

Lifecycle

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

Identity

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

Groups

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

Tracking

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

Surveys

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

Messages

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

Session replay

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

Debug

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

Privacy helpers

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

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

HookOnSurveyDisplayAllowed

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

HookOnMessageDisplayAllowed

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

HookOnSurveyShowed

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

HookOnSurveyStarted

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

HookOnSurveyCompleted

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

HookOnSurveyHidden

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

HookOnMessageShowed

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

HookOnMessageStarted

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

HookOnMessageCompleted

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

HookOnMessageHidden

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

HookOnQuestionReplied

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

For complete hook payload definitions, see the JS tag hooks reference.

Type definitions

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

type ScreebContextValues = {
  close: CloseFunction;
  debug: DebugFunction;
  eventTrack: EventTrackFunction;
  identity: IdentityFunction;
  identityGet: IdentityGetFunction;
  identityGroupAssign: IdentityGroupAssignFunction;
  identityGroupUnassign: IdentityGroupUnassignFunction;
  identityProperties: IdentityPropertiesFunction;
  identityReset: IdentityResetFunction;
  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 ScreebOptions = {
    window?: Window;

    sdkName?: string;
    sdkVersion?: string;

    screebEndpoint?: string;

    platform?: string;
};

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 HooksSurveyStart = {
    onSurveyShowed?: HookOnSurveyShowed;
    onSurveyStarted?: HookOnSurveyStarted;
    onSurveyCompleted?: HookOnSurveyCompleted;
    onSurveyHidden?: HookOnSurveyHidden;

    onQuestionReplied?: HookOnQuestionReplied;
};

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

    onQuestionReplied?: HookOnQuestionReplied;
};

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

        onReady?: HookOnReady;

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