Flutter SDK reference

engageapp_inapp renders full-screen in-app takeovers in Flutter apps (Flutter 3.27+). Add it with flutter pub add engageapp_inapp and use the EngageInApp.instance singleton.

Setup: navigator key

The SDK presents the takeover as a route, so it needs a GlobalKey<NavigatorState> that is attached to both your MaterialApp and the config. See the setup guide for the full wiring.

init(config)

EngageInAppConfig = { required publishableKey, apiBaseUrl = 'https://api.engageapp.xyz', navigatorKey?, httpClient?, videoBuilder?, closeAfterVideoEnds = Duration(seconds: 3) }. closeAfterVideoEnds closes a video or YouTube takeover that long after playback ends; pass null to turn it off. Throws ArgumentError if publishableKey or apiBaseUrl is empty.

videoBuilder: full-screen video and YouTube

Widget Function(BuildContext, TakeoverMedia). Optional. The SDK plays video and YouTube takeovers itself: video_player for direct video URLs and a webview for YouTube. Supply a builder only when you want your app's own player; the SDK renders your widget filling the takeover. TakeoverMedia carries type (image / video / youtube), url, posterUrl, isFullscreen, autoplay, loop, muted, plus videoId and vertical for embeds.

Branch on media.isYouTube: load media.embedUrl (the player URL with the author's options already applied) in a webview, or hand media.videoId to a YouTube player package. Otherwise play media.url. If your builder cannot handle a block, return TakeoverStillFrame(media: media), which shows media.thumbnail (the poster, or YouTube's own thumbnail) instead of a blank screen.

identify(externalId, {...})

Named optionals: email, firstName, lastName, device, identityHash. Async; safe to call repeatedly. identityHash is remembered for later fetches when identity verification is enabled. New workspaces require it: without a valid hash, calls return 401. See In-App Takeover setup, step 6.

setHandlers({...})

onButtonTap(action, message), onShown(message), onDismiss(message), onSurveyCompleted(message). An action carries type (deeplink / url / dismiss) and value.

Surveys

When a takeover carries a survey, the SDK's own takeover screen shows its questions under the copy (the list scrolls when it is long), sends the answers, shows the thank-you text and closes. Set EngageInApp.instance.surveyThankYouDelay to change how long the thank-you stays (default 1.8 seconds). If you use your own presenter, it keeps its signature and does not receive the survey; to show surveys yourself, build a TakeoverSurveyForm and send answers with EngageApiClient.submitSurvey.

onAppForeground()

Async Future<bool>; returns true when a takeover was shown. Same no-op guards as the Web SDK. Call it when your app resumes (e.g. from a WidgetsBindingObserver).

See the In-App Takeover setup guide for an end-to-end example.