Displaying Flows

Flows can appear in your app automatically based on trigger conditions, or you can show them manually by ID. This page explains both approaches and the lifecycle callbacks you can listen for.

Automatic display

By default, the SDK forwards user signals to the Setgreet API whenever the user state changes -- after an identifyUser call, an event track, or a screen track. The server evaluates trigger conditions for the current user and, if a flow matches, returns it in the response. The SDK then displays the returned flow automatically.

This is the recommended approach for most use cases. You configure targeting in the dashboard, and the SDK handles the rest.

How trigger evaluation works

The SDK sends a signal (identify, track event, or screen view) to the Setgreet API.
The server checks all published flows to see if any trigger conditions match the current user state.
If a match is found, the server returns the flow in its response.
If multiple flows match, the server returns the one with the highest priority (set in the dashboard).
The SDK renders the returned flow on the device.

Trigger evaluation is server-side, so the SDK requires a network connection to show flows. Offline caching is not supported today.

Manual display

If you want to show a specific flow at a specific moment in your app's code, use the showFlow method with the flow's ID:

// iOS
Setgreet.showFlow(flowId: "flow_abc123")

// Android
Setgreet.showFlow("flow_abc123")

// React Native
import { showFlow } from '@setgreet/react-native-sdk';

showFlow('flow_abc123');

// Flutter
await Setgreet.showFlow("flow_abc123");

Manual display ignores the flow's trigger conditions -- the flow is shown immediately regardless of user attributes, events, or segments.

You can find the flow ID in the dashboard by opening a flow -- it appears in the URL (for example, app.setgreet.com/flows/flow_abc123).

Flow callbacks

Register callbacks to listen for flow lifecycle events. This lets your app respond to what happens during a flow -- for example, navigating to a screen after the flow closes, or logging a custom event.

// iOS
Setgreet.shared.setFlowCallbacks { callbacks in
    callbacks
        .onFlowStarted { event in
            print("Flow started: \(event.flowId)")
        }
        .onFlowCompleted { event in
            print("Flow completed: \(event.flowId)")
        }
        .onFlowDismissed { event in
            print("Flow dismissed: \(event.flowId), reason: \(event.reason)")
        }
        .onActionTriggered { event in
            print("Action triggered on flow \(event.flowId)")
        }
}

// Android
Setgreet.setFlowCallbacks {
    onFlowStarted { event ->
        println("Flow started: ${event.flowId}")
    }
    onFlowCompleted { event ->
        println("Flow completed: ${event.flowId}")
    }
    onFlowDismissed { event ->
        println("Flow dismissed: ${event.flowId}, reason: ${event.reason}")
    }
    onActionTriggered { event ->
        println("Action triggered on flow ${event.flowId}")
    }
}

Available lifecycle callbacks

Callback	Description
`onFlowStarted`	The flow began and the first screen appeared.
`onFlowCompleted`	The user reached the flow's final screen.
`onFlowDismissed`	The flow closed without being completed.
`onScreenChanged`	The user navigated to another screen within the flow.
`onActionTriggered`	A button or component action was triggered.
`onPermissionRequested`	A permission request action fired (notifications, location, camera).
`onTrackEvent`	An in-flow `Track Event` action fired.
`onCustomAction`	A custom action defined in the dashboard fired.
`onError`	An error occurred while loading or rendering the flow.

Dismiss reasons

When onFlowDismissed fires, the event includes a reason explaining why the flow closed:

Reason	Description
`userClose`	The user tapped the close button.
`userSkip`	The user tapped a skip button.
`backPress`	The user pressed the hardware or system back button (Android).
`swipeDown`	The user swiped a bottom sheet flow down.
`replaced`	The flow was replaced by another flow with higher priority.
`programmatic`	The flow was closed by app code.
`completed`	The flow reached its end and closed naturally.

Action types

Buttons and interactive components can trigger these actions:

Action type	Description
`next`	Navigate to the next screen in the flow.
`previous`	Navigate to the previous screen.
`skip`	Skip the current step and move on.
`dismiss`	Close the flow.
`url`	Open an external URL in the system browser.
`requestNotificationPermission`	Trigger the notification permission prompt.
`requestLocationPermission`	Trigger the location permission prompt.
`requestCameraPermission`	Trigger the camera permission prompt.
`requestReview`	Present the native "rate this app" prompt.
`share`	Open the native share sheet.
`openSettings`	Open the device settings page for the app.
`trackEvent`	Fire an event through the SDK's tracking pipeline.
`custom`	A custom action handled by your app via `onCustomAction`.

Use these action callbacks to integrate flow outcomes with your app's navigation, state management, or business logic.

Displaying Flows

On this page