Hooks

Hooks allow you to listen to Screeb lifecycle events. You can define hooks globally via ScreebProvider or per-survey/per-message via surveyStart() and messageStart().

Available hooks

Hook Name	ScreebProvider / init	surveyStart	messageStart
onReady	✅	❌	❌
onSurveyDisplayAllowed	✅	❌	❌
onMessageDisplayAllowed	✅	❌	❌
onSurveyShowed	✅	✅	❌
onSurveyStarted	✅	✅	❌
onQuestionReplied	✅	✅	✅
onSurveyCompleted	✅	✅	❌
onSurveyHidden	✅	✅	❌
onMessageShowed	✅	❌	✅
onMessageStarted	✅	❌	✅
onMessageCompleted	✅	❌	✅
onMessageHidden	✅	❌	✅

Payload structure

React reuses the browser hook payload types. Hook payloads are nested:

type Channel = {
  id: string;
  type: "widget" | "ios" | "android";
};

type User = {
  anonymous_id: string;
  userId?: string;
};

type Survey = {
  id: string;
  survey_position:
    | "center-left"
    | "center-center"
    | "center-right"
    | "bottom-left"
    | "bottom-center"
    | "bottom-right";
  survey_format: "conversationnal" | "cards";
  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;
};

Exact callback payloads:

onReady(payload: { channel: Channel; user: User }): void;

onSurveyDisplayAllowed(payload: {
  channel: Channel;
  user: User;
  survey: Survey;
}): boolean;

onMessageDisplayAllowed(payload: {
  channel: Channel;
  user: User;
  survey: Survey;
}): boolean;

onSurveyShowed(payload: {
  channel: Channel;
  user: User;
  survey: Survey;
  response: {
    id: string;
    items: ResponseItem[];
  };
}): void;

onSurveyStarted(payload: {
  channel: Channel;
  user: User;
  survey: Survey;
  response: {
    id: string;
  };
}): void;

onSurveyCompleted(payload: {
  channel: Channel;
  user: User;
  survey: Survey;
  response: {
    id: string;
    items: ResponseItem[];
  };
}): void;

onSurveyHidden(payload: {
  channel: Channel;
  user: User;
  survey: Survey;
  response: {
    id: string;
    items: ResponseItem[];
    hide_reason: ResponseStatus;
  };
}): void;

onQuestionReplied(payload: {
  channel: Channel;
  user: User;
  survey: Survey;
  response: {
    id: string;
    status: null;
    question: ResponseItemQuestion;
    answer: ResponseItemAnswer;
    items: ResponseItem[];
  };
}): void;

onMessageShowed(payload: {
  channel: Channel;
  user: User;
  message: Message;
  response: {
    id: string;
    items: ResponseItem[];
  };
}): void;

onMessageStarted(payload: {
  channel: Channel;
  user: User;
  message: Message;
  response: {
    id: string;
  };
}): void;

onMessageCompleted(payload: {
  channel: Channel;
  user: User;
  message: Message;
  response: {
    id: string;
    items: ResponseItem[];
  };
}): void;

onMessageHidden(payload: {
  channel: Channel;
  user: User;
  message: Message;
  response: {
    id: string;
    items: ResponseItem[];
    hide_reason: ResponseStatus;
  };
}): void;

Global hooks via ScreebProvider

Define hooks that apply to all surveys and messages in your application:

import { ScreebProvider } from "@screeb/sdk-react";

export const App = () => (
  <ScreebProvider
    autoInit
    websiteId="<YOUR-CHANNEL-ID>"
    userId="<USER-ID>"
    hooks={{
      version: "1.0.0",
      onReady: (payload) => {
        console.log("Screeb is ready", payload);
      },
      onSurveyShowed: (payload) => {
        console.log("Survey showed", payload);
      },
      onSurveyCompleted: (payload) => {
        console.log("Survey completed", payload);
      },
      onQuestionReplied: (payload) => {
        console.log("Question answered", payload.response.question, payload.response.answer);
      },
    }}
  >
    <YourApp />
  </ScreebProvider>
);

Per-survey hooks

Define hooks for a specific survey when calling surveyStart():

import { useScreeb } from "@screeb/sdk-react";

const MyComponent = () => {
  const { surveyStart } = useScreeb();

  const showSurveyWithHooks = async () => {
    await surveyStart(
      "<SURVEY_ID>",
      "<DISTRIBUTION_ID>",
      false,
      { article_id: 42 },
      {
        onSurveyShowed: (payload) => {
          console.log("This specific survey showed", payload);
        },
        onSurveyCompleted: (payload) => {
          console.log("This specific survey completed", payload);
        },
      }
    );
  };
};

Per-message hooks

Define hooks for a specific message when calling messageStart():

import { useScreeb } from "@screeb/sdk-react";

const MyComponent = () => {
  const { messageStart } = useScreeb();

  const showMessageWithHooks = async () => {
    await messageStart(
      "<MESSAGE_ID>",
      false,
      { article_id: 42 },
      {
        onMessageShowed: (payload) => {
          console.log("This specific message showed", payload);
        },
        onMessageHidden: (payload) => {
          console.log("This specific message hid", payload);
        },
      }
    );
  };
};

Hook version field

version is part of the global HooksInit object passed to ScreebProvider/init(). It is not part of the surveyStart() or messageStart() hook objects.

Full payload definitions

For complete payload type definitions and detailed information about each hook, see the JS tag hooks reference.