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.
Configuration
Section titled “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
Section titled “useScreeb() methods”Lifecycle
Section titled “Lifecycle”| Method | Description | More |
|---|---|---|
init(websiteId: string, userId?: string, userProperties?: PropertyRecord, hooks?: HooksInit, language?: string, spaNavigationHandler?: SpaNavigationHandler) => Promise<void> |
Initializes Screeb tag. | Guide |
load(options?: ScreebOptions) => Promise<void> |
Appends Screeb tag into your dom. | Guide |
close() => Promise<void> |
Shutdowns current Screeb session. | Guide |
Identity
Section titled “Identity”| Method | Description | More |
|---|---|---|
identity(userId: string, userProperties?: PropertyRecord) => Promise<unknown> |
Change the current user identity. | Guide |
identityProperties(userProperties: PropertyRecord) => Promise<unknown> |
Adds properties to the current user identity. | Guide |
identityReset() => Promise<unknown> |
Resets the current user identity. | Guide |
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 |
identityGet() => Promise<ScreebIdentityGetReturn> |
Retrieves the current user identity. | Guide |
Groups
Section titled “Groups”| Method | Description | More |
|---|---|---|
identityGroupAssign(groupName: string, groupType?: string, groupProperties?: PropertyRecord) => Promise<unknown> |
Assigns the current user to a group. | Guide |
identityGroupUnassign(groupName: string, groupType?: string) => Promise<unknown> |
Unassigns the current user to a group. | Guide |
Tracking
Section titled “Tracking”| Method | Description | More |
|---|---|---|
eventTrack(eventName: string, eventProperties?: PropertyRecord) => Promise<unknown> |
Tracks a user event. | Guide |
Surveys
Section titled “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 |
surveyClose() => Promise<unknown> |
Interrupts a running survey. | Guide |
Messages
Section titled “Messages”| Method | Description | More |
|---|---|---|
messageStart(messageId: string, allowMultipleResponses?: boolean, hiddenFields?: PropertyRecord, hooks?: HooksMessageStart, language?: string) => Promise<unknown> |
Starts a message by its ID. | Guide |
messageClose() => Promise<unknown> |
Interrupts a running message. | Guide |
Session replay
Section titled “Session replay”| Method | Description | More |
|---|---|---|
sessionReplayStart() => Promise<unknown> |
Starts a session replay. | Guide |
sessionReplayStop() => Promise<unknown> |
Interrupts a running session replay. | Guide |
| Method | Description | More |
|---|---|---|
debug() => Promise<unknown> |
Prints the actual state information of Screeb tag. | Guide |
targetingDebug() => Promise<unknown> |
Prints the current state of the targeting engine. | Guide |
Privacy helpers
Section titled “Privacy helpers”| Method | Description | More |
|---|---|---|
ScreebMaskText<T extends Element>(element: T) => T |
Mask a view or component in session replay. | Guide |
ScreebNoCapture<T extends Element>(element: T) => T |
Exclude a view or component from session replay capture. | Guide |
ScreebId<T extends Element>(element: T, id: string) => T |
Set a stable Screeb element ID for IAM targeting. | Guide |
API signatures
Section titled “API signatures”Lifecycle
Section titled “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
Section titled “Identity”identity(userId: string, userProperties?: PropertyRecord) => Promise<unknown>;identityProperties(userProperties: PropertyRecord) => Promise<unknown>;identityReset() => Promise<unknown>;setAnonymousId(anonymousId: string) => Promise<unknown>;identityGet() => Promise<ScreebIdentityGetReturn>;Groups
Section titled “Groups”identityGroupAssign(groupName: string, groupType?: string, groupProperties?: PropertyRecord) => Promise<unknown>;identityGroupUnassign(groupName: string, groupType?: string) => Promise<unknown>;Tracking
Section titled “Tracking”eventTrack(eventName: string, eventProperties?: PropertyRecord) => Promise<unknown>;Surveys
Section titled “Surveys”surveyStart(surveyId: string, distributionId?: string, allowMultipleResponses?: boolean, hiddenFields?: PropertyRecord, hooks?: HooksSurveyStart, language?: string, selectors?: string | string[]) => Promise<unknown>;surveyClose() => Promise<unknown>;Messages
Section titled “Messages”messageStart(messageId: string, allowMultipleResponses?: boolean, hiddenFields?: PropertyRecord, hooks?: HooksMessageStart, language?: string) => Promise<unknown>;messageClose() => Promise<unknown>;Session replay
Section titled “Session replay”sessionReplayStart() => Promise<unknown>;sessionReplayStop() => Promise<unknown>;debug() => Promise<unknown>;targetingDebug() => Promise<unknown>;Privacy helpers
Section titled “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;HookOnReady
Section titled “HookOnReady”type HookOnReady = (data: { channel: Channel; user: User }) => void;HookOnSurveyDisplayAllowed
Section titled “HookOnSurveyDisplayAllowed”type HookOnSurveyDisplayAllowed = ( data: HookCommonPropertiesSurvey,) => boolean;HookOnMessageDisplayAllowed
Section titled “HookOnMessageDisplayAllowed”type HookOnMessageDisplayAllowed = ( data: HookCommonPropertiesSurvey,) => boolean;HookOnSurveyShowed
Section titled “HookOnSurveyShowed”type HookOnSurveyShowed = ( data: HookCommonPropertiesSurvey & { response: { id: string; items: ResponseItem[]; }; },) => void;HookOnSurveyStarted
Section titled “HookOnSurveyStarted”type HookOnSurveyStarted = ( data: HookCommonPropertiesSurvey & { response: { id: string; }; },) => void;HookOnSurveyCompleted
Section titled “HookOnSurveyCompleted”type HookOnSurveyCompleted = ( data: HookCommonPropertiesSurvey & { response: { id: string; items: ResponseItem[]; }; },) => void;HookOnSurveyHidden
Section titled “HookOnSurveyHidden”type HookOnSurveyHidden = ( data: HookCommonPropertiesSurvey & { response: { id: string; items: ResponseItem[]; hide_reason: ResponseStatus; }; },) => void;HookOnMessageShowed
Section titled “HookOnMessageShowed”type HookOnMessageShowed = ( data: HookCommonPropertiesMessage & { response: { id: string; items: ResponseItem[]; }; },) => void;HookOnMessageStarted
Section titled “HookOnMessageStarted”type HookOnMessageStarted = ( data: HookCommonPropertiesMessage & { response: { id: string; }; },) => void;HookOnMessageCompleted
Section titled “HookOnMessageCompleted”type HookOnMessageCompleted = ( data: HookCommonPropertiesMessage & { response: { id: string; items: ResponseItem[]; }; },) => void;HookOnMessageHidden
Section titled “HookOnMessageHidden”type HookOnMessageHidden = ( data: HookCommonPropertiesMessage & { response: { id: string; items: ResponseItem[]; hide_reason: ResponseStatus; }; },) => void;HookOnQuestionReplied
Section titled “HookOnQuestionReplied”type HookOnQuestionReplied = ( data: HookCommonPropertiesSurvey & { response: { id: string; status: null; question: ResponseItemQuestion; answer: ResponseItemAnswer; items: ResponseItem[]; }; },) => void;HookOnButtonNavigateStarted
Section titled “HookOnButtonNavigateStarted”type HookOnButtonNavigateStarted = ( data: HookCommonPropertiesSurvey & { response: { id: string; }; button: { url: string; url_target?: string; }; },) => void;HookOnButtonNavigateCompleted
Section titled “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
Section titled “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; 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; };