Hooks
Run your own code when Screeb is ready, when a survey or message shows, gets an answer or closes, and decide whether it may show at all.
Hooks are callbacks that Screeb calls on lifecycle events: the SDK is ready, a survey or message shows, the user answers a question, a survey closes. Use them to sync your app with Screeb, for example to pause a video while a survey is on screen, or to send a completed survey to your analytics. One hook can also decide whether a survey or message may show.
Every hook is optional. Every hooks object carries a version, "1.0.0", the only one that exists: the SDK rejects hooks without it.
Set hooks at initialization
Section titled “Set hooks at initialization”Hooks set at initialization apply to every survey and message of the session.
import app.screeb.sdk.kmp.Screebimport app.screeb.sdk.kmp.ScreebHooks
// payload is a JSON string. Return null when the hook sends nothing back.val hooks = ScreebHooks( version = "1.0.0", callbacks = mapOf( "onReady" to { payload -> println("Screeb is ready $payload") null }, "onSurveyCompleted" to { payload -> println("Survey completed $payload") null }, ),)
Screeb.initSdk( channelId = "<YOUR-CHANNEL-ID>", userId = "<USER-ID>", hooks = hooks,)Set hooks when you start a survey or a message
Section titled “Set hooks when you start a survey or a message”Hooks passed when you start a survey or start a message apply to that survey or message only. They run in addition to the hooks set at initialization, not instead of them.
Screeb.startSurvey( surveyId = "<SURVEY-ID>", hooks = ScreebHooks( version = "1.0.0", callbacks = mapOf( "onSurveyCompleted" to { payload -> println("Feedback survey completed $payload") null }, ), ),)
Screeb.startMessage( messageId = "<MESSAGE-ID>", hooks = ScreebHooks( version = "1.0.0", callbacks = mapOf( "onMessageHidden" to { payload -> println("Message closed $payload") null }, ), ),)Decide whether a survey or message shows
Section titled “Decide whether a survey or message shows”onSurveyDisplayAllowed and onMessageDisplayAllowed run before a survey or message shows. Return false to block it, true to let it show. Set them at initialization: they are the only hooks that send an answer back, and they are not accepted when you start a survey or message.
val hooks = ScreebHooks( version = "1.0.0", callbacks = mapOf( // Return false to keep the survey or message hidden. "onSurveyDisplayAllowed" to { payload -> true }, "onMessageDisplayAllowed" to { payload -> true }, ),)
Screeb.initSdk(channelId = "<YOUR-CHANNEL-ID>", hooks = hooks)Available hooks
Section titled “Available hooks”| Hook | Called when | Where you set it |
|---|---|---|
onReady |
The SDK is loaded and initialized | Initialization |
onSurveyDisplayAllowed |
A survey is about to show: return whether it may | Initialization |
onMessageDisplayAllowed |
A message is about to show: return whether it may | Initialization |
onSurveyShowed |
A survey appears on screen, including when it shows again after a reload | Initialization, survey start |
onSurveyStarted |
A survey starts | Initialization, survey start |
onQuestionReplied |
The user answers a question | Initialization, survey start, message start |
onSurveyCompleted |
The user reaches the end of a survey | Initialization, survey start |
onSurveyHidden |
A survey leaves the screen, for any reason | Initialization, survey start |
onMessageShowed |
A message appears on screen, including when it shows again after a reload | Initialization, message start |
onMessageStarted |
A message starts | Initialization, message start |
onMessageCompleted |
The user reaches the end of a message | Initialization, message start |
onMessageHidden |
A message leaves the screen, for any reason | Initialization, message start |
onAppStoreRatingTriggered runs when an app store rating question asks for a rating. Set it at initialization or when you start a survey or message.
Payloads
Section titled “Payloads”Every payload carries the channel and the user. Survey hooks add the survey, message hooks add the message, and most of them add the response:
channel { id: string, type: "widget" | "ios" | "android" }user { anonymous_id: string, user_id: string | null }survey { id: string, survey_format: "conversationnal" | "cards", survey_position: "center-left" | "center-center" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right", survey_size: 25 | 50 | 75 | 100 | 125 | 150 }message { id: string, message_size: 25 | 50 | 75 | 100 | 125 | 150 }item { question: { id: string, title: string, type: "text" | "video", url?: string }, answer: { replied_at?: string, fields?: field[] } }field { type: "string" | "number" | "boolean" | "none" | "time" | "url", text?: string, number?: number, boolean?: boolean, time?: string, button_url?: string, button_url_target?: "in-page" | "in-page-spa" | "new-tab", button_actions?: object[] }user_id is null until you identify the user. survey_format is spelled conversationnal, with two n, in the payloads.
| Hook | Payload |
|---|---|
onReady, onAppStoreRatingTriggered |
channel, user |
onSurveyDisplayAllowed |
channel, user, survey: { id }, ai_detection |
onMessageDisplayAllowed |
channel, user, message: { id }, ai_detection |
onSurveyStarted |
channel, user, survey, response: { id } |
onSurveyShowed, onSurveyCompleted |
channel, user, survey, response: { id, items: item[] } |
onSurveyHidden |
channel, user, survey, response: { id, items: item[], hide_reason } |
onMessageStarted |
channel, user, message, response: { id } |
onMessageShowed, onMessageCompleted |
channel, user, message, response: { id, items: item[] } |
onMessageHidden |
channel, user, message, response: { id, items: item[], hide_reason } |
onQuestionReplied |
channel, user, survey, response: { id, status, question, answer, items: item[] } |
hide_reasonandstatusare one of"displayed","started","ended"(the user reached the end),"closed"(the user closed it) or"interrupted"(your code or the SDK closed it).- In
onQuestionReplied,questionandanswerare the last answered item. For a message, thesurveyfield holds the message id and itsmessage_size. ai_detectiontells whether the visitor looks like an AI agent, or null when unknown:{ classification: "human" | "likely_human" | "likely_agent" | "agent", confidence_score: number, referrer_ai: string | null, is_ai_referral: boolean }.