# Migration to v4.0

This guide will assist developers to move from Flagship 3.X to Flagship 4.X.

The main breaking changes are:

* Consent Management
* Visitor Status

See the full change log on [Github](https://github.com/flagship-io/flagship-flutter-sdk).

## Consent Management

The version 4.X introduces a required consent parameter when creating a Visitor `instance`:

\**`VisitorBuilder newVisitor({required String visitorId, required bool hasConsented, Instance instanceType = Instance.SINGLE_INSTANCE})`*

```swift
// 1-  In the version 4.X we added a label for visitorId parameter and introduce required consent parameter.
// 2-  Remove from the builder .hasConsented function.
   var  visitor = Flagship.newVisitor(visitorId: "visitorId", hasConsented: true).withContext({"isVip": true}).build();
```

```swift
import Flagship
// When omitted default consent value was true.
Visitor visitor1 = Flagship.newVisitor("visitor_1").withContext({"isVip": true}).hasConsented(true).isAuthenticated(true).build();
```

## Flagship SDK Status

### Status Listener

The `withStatusListener` renamed to [onSdkStatusChanged](https://docs.abtasty.com/server-side/sdks/flutter/archived-versions/flutter-reference#getstatus-method)*and the type of parameter from***Status***to***FSSdkStatus**\_

* **`ConfigBuilder onSdkStatusChanged(SdkStatusChanged pSdkStatusChanged)`**

```groovy
// Define a custom configuration 
FlagshipConfig customConfig = ConfigBuilder()
        .withMode(Mode.DECISION_API)
        .onSdkStatusChanged((newStatus) {
      // Do things when status change ...
    }).build();
```

```groovy
// Define a custom configuration 
FlagshipConfig customConfig = ConfigBuilder()
    .withMode(Mode.DECISION_API)
    .withStatusListener((newStatus) {
      // Do things when status change ...
    }).build();
```

### Get Status

```groovy
// Get the current flagship sdk
FSSdkStatus currentStatus = Flagship.getStatus();
```

```groovy
// Get the current flagship sdk
Status currentStatus = Flagship.getStatus()
```

### Status Values

| FSSdkStatus                 | Description                                                                                                                                                          |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ***SDK\_NOT\_INITIALIZED*** | The SDK has not been started                                                                                                                                         |
| ***SDK\_INITIALIZING***     | The SDK still starting, in *bucketing mode* the sdk needs to download the ressources (bucketing file) before start. if the file exist already this status is skipped |
| ***SDK\_INITIALIZED***      | The SDK is ready to use.                                                                                                                                             |
| ***SDK\_PANIC***            | The SDK is ready but is running in Panic mode: All visitor's features are disabled except 'fetchFlags' which refreshes this status.                                  |

## Flag

The `defaultValue` in 4.X is provided at the reading [value](https://docs.abtasty.com/server-side/sdks/flutter/archived-versions/flutter-reference#value-method) method through the flag instance and not as 3.X which is provided at `getFlag` method.

### Get Flag

You can retrieve [Flag](https://docs.abtasty.com/server-side/sdks/flutter/archived-versions/flutter-reference#flagship-class) by using the following functions from the Visitor instance:

* **`Flag getFlag<T>(String key)`**

```swift
import 'package:flagship/flagship.dart';
import 'package:flagship/model/flag.dart';

// Create visitor "visitor" and fetch flags
//Get flag for vip feature
Flag flag = visitor.getFlag("displayVipFeature");
```

```swift
import 'package:flagship/flagship.dart';
import 'package:flagship/model/flag.dart';

// Create visitor "visitor" and fetch flags

// Get flag for vip feature with default value 
Flag flag = visitor.getFlag("displayVipFeature", false);
```

### Reading Flag Value

To read the current flag's value, simply call `value()` method of the [Flag](https://docs.abtasty.com/server-side/sdks/flutter/archived-versions/flutter-reference#flagship-class) object.

* **`dynamic value<T>(T? defaultValue, {bool visitorExposed = true})`**

```swift
import 'package:flagship/flagship.dart';
import 'package:flagship/model/flag.dart';

// Create visitor "visitor" and fetch flags

// Ex: get flag for vip feature
Flag flag = currentVisitor.getFlag("displayVipFeature");

// Read the value for flag and provide a default at the same call 
bool shouldDisplayVipFeature = flag.value(false);

```

```swift
import 'package:flagship/flagship.dart';
import 'package:flagship/model/flag.dart';

// Create visitor "visitor" and fetch flags

// Ex: get flag for vip feature
Flag flag = currentVisitor.getFlag("displayVipFeature", false);
/
/ Use this flag value to enable displaying the vip feature
bool shouldDisplayVipFeature = flag.value();
```