# Common Implementation Patterns

Once the SDK is installed and initialized (see [Installation](./flutter-installation)), the next decision is how you drive the onboarding flow. The Flutter SDK supports three integration patterns. They differ in two ways: where the flow is defined (in your app code versus on the Incode Dashboard) and how much control your host application keeps while the flow runs.

This page explains each pattern and when to use it. Pick the one that fits your product, then follow its dedicated page for the full walkthrough.

## Where flows are defined

The three patterns split into two configuration models:

- **Configured locally.** You build an `OnboardingFlowConfiguration` in code, adding the modules you want and the order they run in. Patterns 1 and 2 use this model. See [Modules](./flutter-modules) for the catalog of modules you can add and their per-module configuration parameters.
- **Configured online.** The flow is defined on the Incode Dashboard as a Flow or a Workflow. Your code references it by `configurationId`, so you can change the configuration on the Dashboard without shipping a new app build. Pattern 3 uses this model.

## The three patterns

### 1. Run flows configured online (recommended)

Define the flow on the Incode Dashboard as a Flow or a Workflow, then start it with `startFlow()` or `startWorkflow()`, respectively. The SDK pulls the modules and configuration from the Dashboard, so you do not define an `OnboardingFlowConfiguration` locally. Make sure the Flow or Workflow is activated on Dashboard before starting the session.

Use this when you want to change the onboarding flow from Dashboard without releasing a new app version.

Walkthrough: [Run Flows Configured Online](./flutter-run-flows-configured-online)

### 2. Configure flows locally and run end to end

Build an `OnboardingFlowConfiguration` in code, then hand the whole flow to the SDK with a single `startOnboarding()` call. The SDK runs every module in sequence and returns control to your app when the flow finishes.

Use this when you want the simplest integration and the SDK can own the full onboarding experience from start to finish.

Walkthrough: [Configure Flows Locally and Run End to End](./flutter-configure-flows-locally-and-run-end-to-end)

### 3. Configure flows locally and run step by step

Build the flow as one or more sections in code and run each section with `startNewOnboardingSection()`. Control returns to your host application between sections, so you can insert your own screens, run business logic, or branch the flow based on intermediate results before starting the next section.

Use this when you need to interleave your own UI or logic with the SDK modules, or split a long flow into discrete steps.

Walkthrough: [Configure Flows Locally and Run Step by Step](./flutter-configure-flows-locally-and-run-step-by-step)

## Choosing a pattern

| If you want to...                                         | Use                                 | Entry point                        |
| --------------------------------------------------------- | ----------------------------------- | ---------------------------------- |
| Change the flow from the Dashboard without an app release | Run flows configured online         | `startFlow()` or `startWorkflow()` |
| Run a full flow with the least code                       | Configure locally, run end to end   | `startOnboarding()`                |
| Insert your own screens or logic between SDK steps        | Configure locally, run step by step | `startNewOnboardingSection()`      |

## Example app

A working example app demonstrating these patterns is available on [GitHub](https://github.com/Incode-Technologies-Example-Repos/FlutterSampleApp). Contact your Customer Success Manager for access.

To run the example app, create a `.env` file in the example folder with your `apiKey` and `apiUrl` (provided by Incode). Run `flutter pub get`, then `flutter pub run build_runner build --delete-conflicting-outputs`, then launch the app. See the repo README for full setup details.

## Related pages

- [Modules](./flutter-modules): the module catalog for building an `OnboardingFlowConfiguration`.
- [Results](./flutter-results): the result and error objects returned when a flow finishes.
- [API Reference](./flutter-api-reference): the full specification of `startOnboarding()`, `startNewOnboardingSection()`, `startFlow()`, `startWorkflow()`, `OnboardingFlowConfiguration`, and `OnboardingSessionConfiguration`.

<br />