Reference

Complete reference for @screeb/sdk-react.

✨ New to Screeb? Start with the Install guide.

Configuration

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.	👉
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, spaNavigationHandler?: SpaNavigationHandler) => 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;

HookOnButtonNavigateStarted

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

HookOnButtonNavigateCompleted

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.

Type definitions

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