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

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

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.shared.showFlow(flowId: "YOUR_FLOW_ID")

// Android
Setgreet.showFlow("YOUR_FLOW_ID")

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

showFlow('YOUR_FLOW_ID');

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

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

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

Dismiss reasons

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

Action types

Buttons and interactive components can trigger these actions:

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

Permission actions

The SDK declares no permissions of its own. A permission prompt appears only when a flow uses one of the request actions and your app has made the platform declaration below. When the declaration is missing, the SDK logs a message, reports the permission as not required, and the flow moves on. It never crashes.

Every request fires onPermissionRequested with the permission type and a result: granted, denied, permanentlyDenied, alreadyGranted, or notRequired. On iOS, limited photo library access counts as granted. The flow advances after any result; a primer screen's job is to explain the request, not to block on it.

A screen can also skip itself when the permission it asks for is already granted. See Skip when already granted.