Reference

Complete reference for the Ionic SDK, which uses @screeb/sdk-angular internally.

✨ New to Screeb? Start with the Install guide.

Methods by capability

Inject the Screeb service and call these methods. All methods return a Promise.

Lifecycle

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

Identity

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

Groups

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

Tracking

Method	Description	More
eventTrack(eventName: string, eventProperties?: PropertyRecord)	Tracks a user event.	👉

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

Messages

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

Session replay

Method	Description	More
sessionReplayStart()	Starts a session replay.	👉
sessionReplayStop()	Interrupts a running session replay.	👉

Debug

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

Privacy helpers

Method	Description	More
ScreebMaskText<T extends Element>(element: T): T	Marks an element as sensitive in Screeb session replay.	👉
ScreebNoCapture<T extends Element>(element: T): T	Excludes an element from Screeb session replay capture.	👉
ScreebId<T extends Element>(element: T, id: string): T	Sets a stable Screeb element ID for IAM targeting and replay context.	👉

API signatures

Lifecycle

public async init(websiteId: string, userId?: string, userProperties?: PropertyRecord, hooks?: HooksInit, language?: string, spaNavigationHandler?: SpaNavigationHandler);
public async load(options?: ScreebOptions);
public async close();

Identity

public async identity(userId: string, userProperties?: PropertyRecord);
public async identityProperties(userProperties: PropertyRecord);
public async identityReset();
public async identityGet();

Groups

public async identityGroupAssign(groupName: string, groupType?: string, groupProperties?: PropertyRecord);
public async identityGroupUnassign(groupName: string, groupType?: string);

Tracking

public async eventTrack(eventName: string, eventProperties?: PropertyRecord);

Surveys

public async surveyStart(surveyId: string, distributionId: string, allowMultipleResponses: boolean, hiddenFields?: PropertyRecord, hooks?: HooksSurveyStart, language?: string, selectors?: string | string[]);
public async surveyClose();

Messages

public async messageStart(messageId: string, allowMultipleResponses?: boolean, hiddenFields?: PropertyRecord, hooks?: HooksMessageStart, language?: string);
public async messageClose();

Session replay

public async sessionReplayStart();
public async sessionReplayStop();

Debug

public async debug();
public async targetingDebug();

Privacy helpers

public ScreebMaskText<T extends Element>(element: T): T;
public ScreebNoCapture<T extends Element>(element: T): T;
public ScreebId<T extends Element>(element: T, id: string): T;

ScreebModule configuration

Option	Type	Required	Description
websiteId	string	No	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.
spaNavigationHandler	SpaNavigationHandler	No	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.

Note: The language parameter is not available in ScreebModule.forRoot(). To set the language, use the language parameter when calling init() directly.

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