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 server also decides every Condition node in that flow for the current user, from their stored attributes and segments, and removes the other path from the flow's navigation, so the device follows the chosen one. The flow's other screens are still sent to the device, so a Condition node decides where users go but does not keep the other path's content off the device.
6. 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.

Condition nodes inside the flow still apply: when showFlow fetches the flow, the server decides them from the attributes and segments stored for the current user. Call identifyUser before showFlow so those attributes are up to date (see User Identification).

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 \(event.actionType) on flow \(event.flowId)")
        }
        .onCustomAction { event in
            print("Custom action on flow \(event.flowId): \(event.data ?? [:])")
        }
}

// 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 ${event.actionType} on flow ${event.flowId}")
    }
    onCustomAction { event ->
        println("Custom action on flow ${event.flowId}: ${event.data}")
    }
}

Available lifecycle callbacks

The outcome of a paywall's purchase and restore buttons has its own callbacks, described in Purchases and paywalls.

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. onActionTriggered reports each one as its actionType, the same value on every SDK (on Android, the ActionType name in lower case):

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, permanently_denied, already_granted, or not_required. 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.