# Setup

## Add the SDK to your project

SDK is available from pub.dev: <https://pub.dev/packages/didomi_sdk/install>

Add the Didomi SDK dependency:

```bash
 $ flutter pub add didomi_sdk
```

{% hint style="info" %}
This will add a line like this to your package's pubspec.yaml (and run an implicit `dart pub get`):

```
dependencies:
  didomi_sdk: ^1.0.1
```

Afterwards, to update the dependency to the latest version, you can use the command

```
$ flutter pub upgrade
```

{% endhint %}

{% hint style="warning" %}
On Android, the error `Module was compiled with an incompatible version of Kotlin.` may occur. Make sure `ext.kotlinVersion` is set to `1.5.31` in `android/build.gradle`.
{% endhint %}

Then you can import project from your dart code:

```
import 'package:didomi_sdk/didomi_sdk.dart';
```

## Initialize the SDK

Once our SDK has been added to your project, you need to initialize it. The initialization process will prepare the SDK for interactions with the user and your application. It is important to launch the SDK initialization as soon as possible.

In your code, call the `initialize` method and pass your API key:

{% tabs %}
{% tab title="Dart" %}

```dart
void initDidomi() {
  // Setup a listener to know when the SDK is ready
  DidomiSdk.onReady(() => {
    // The Didomi SDK is ready to go, you can call other functions
  });
  DidomiSdk.initializeWithParameters(
      DidomiInitializeParameters(apiKey:"<Your API key>",
      noticeId: "<Your Notice ID>"));
}
```

{% endtab %}
{% endtabs %}

�Keep in mind that the SDK initialization is an asynchronous process so you must avoid interacting with the `DidomiSdk` object until it is actually ready to handle your requests. Use the `onReady` event in dart to register a listener for the ready event.

Take a look at our [sample app](https://github.com/didomi/flutter/tree/main/example) to see how the setup is done.

## Use FlutterFragmentActivity instead of FlutterActivity (Android)

The Didomi SDK requires a FragmentActivity to display the notice. By default, Flutter projects use FlutterActivity which extends Activity: to use the SDK, it must be changed to a FlutterFragmentActivity instead.

The activity class should be present in folder `android/app/src/main/kotlin/` under the package name described in `android/app/src/main/AndroidManifest.xml`. Update it to use FlutterFragmentActivity.

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
package <Your package name>

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity() {
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Some sdk users reported a dependency conflict after updating the MainActivity class. They solved it by adding the dependency

`implementation "androidx.activity:activity-ktx:1.3.1"`

in the file `android/app/build.gradle` .
{% endhint %}

## �Setup the SDK UI

{% hint style="info" %}
Note: the `setupUI` method should be called only from your contexts where the application starts.

You do not need to call `onReady`, `isReady` or `shouldConsentBeCollected` before calling `setupUI` because they are called internally. Therefore, by calling this method the consent notice will be displayed if it is required and only once the SDK is ready.
{% endhint %}

Call the `setupUI` function of the SDK in your context where the application starts:

{% tabs %}
{% tab title="Dart" %}

```dart
class _MyHomePageState extends State<MyHomePage> {

  @override
  void initState() {
    super.initState();
    DidomiSdk.setupUI();
  }
}
```

{% endtab %}
{% endtabs %}

### �Deep links

If you are using deep links or have multiple pages in your Flutter app, make sure that the `setupUI` function is called on every context that the user can launch the app on.\
\
This will ensure that consent is always collected as needed and there is no path where the user can launch the app without consent being collected. If `setupUI` is missing in some entry points, you will see lower consent rates as users will be using the app without giving consent.

## Configure the SDK

We support three options for configuring the UI and the behavior of the SDK:

* [Didomi Console](#from-the-console-recommended): the SDK is configured remotely from the Didomi Console
* [Local file](#local-file): the SDK is configured from a `didomi_config.json` file embedded in your app package
* [Remote file](#remote-file): the SDK is configured from a remote `didomi_config.json` file

### From the Console (Recommended)

You can configure the consent notice in your app by creating a notice in your Didomi Console. It will automatically be linked to your app through your API Key and, optionally, your notice id. You can access the Didomi console [here](http://console.didomi.io).

In order to enable this option, make sure to pass the `disableDidomiRemoteConfig` parameter as `false` (default value) when calling the initialize method as shown below.

{% tabs %}
{% tab title="Dart" %}

```dart
  DidomiSdk.initializeWithParameters(
      DidomiInitializeParameters(
          apiKey: "<Your API key>",
          disableDidomiRemoteConfig: false,
          noticeId: "<Your notice ID>"
      )
  );
```

{% endtab %}
{% endtabs %}

The SDK will automatically use the remote configuration hosted by Didomi and cache it locally. The cached version is refreshed every 60 minutes.\
If there is no connection available to download the remote configuration and no locally cached version, the SDK will try to use a local `didomi_config.json` configuration file as a fallback. See the Local option below for more information on how to configure the SDK through a local configuration file.

### Local file (Deprecated)

{% hint style="danger" %}
Using a local file automatically disables the TCF integration.\
If your app uses the TCF, you must use a configuration from the Didomi Console.
{% endhint %}

{% hint style="warning" %}
Using a local file will prevent you to support multiple regulations.
{% endhint %}

With this option, you create your own SDK configuration file and embed it in your app package.

The SDK behavior is configured in a `didomi_config.json` file that must be placed in the Android and iOS folders of your project.

You can create a file with the following content to get started:

{% tabs %}
{% tab title="didomi\_config.json" %}

```javascript
{
    "app": {
        "name": "My App Name",
        "privacyPolicyURL": "http://www.website.com/privacy",
        "vendors": {
            "iab": {
                "all": true
            }
        },
        "gdprAppliesGlobally": true,
        "gdprAppliesWhenUnknown": true
    }
}
```

{% endtab %}
{% endtabs %}

For Android, the configuration file must be placed in the assets folder of the Android platform code (in this example: `android/app/src/main/assets`)

![](https://1703900661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LDh8ZWDZrXs8sc4QKEQ%2Fuploads%2Fgit-blob-4b7e36be9d87f82a3281177a6b11787b3ec00d90%2FCapture%20d%E2%80%99%C3%A9cran%202021-06-03%20%C3%A0%2014.10.51.png?alt=media)

For iOS, the configuration file must be placed in the `Resources` group (make sure `project.pbxproj` file is updated)

![](https://1703900661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LDh8ZWDZrXs8sc4QKEQ%2Fuploads%2Fgit-blob-71b59a24a791cf02c36153c23698996a94bad142%2FCapture%20d%E2%80%99%C3%A9cran%202021-06-03%20%C3%A0%2014.14.02.png?alt=media)

You also need to disable loading the remote configuration to ensure that only the local file is loaded and that no HTTP request is sent. Update your [`initialize`](https://developers.didomi.io/cmp/mobile-sdk/reference#initialize) call to set the `disableDidomiRemoteConfig` parameter to `true`:

{% tabs %}
{% tab title="Dart" %}

```dart
 DidomiSdk.initializeWithParameters(
      DidomiInitializeParameters(
            apiKey: "<Your API key>",
            disableDidomiRemoteConfig: true,
            noticeId: "<Your notice ID>"
      )
);
```

{% endtab %}
{% endtabs %}

Your SDK is now setup. [Read the Getting started section](https://developers.didomi.io/cmp/mobile-sdk/consent-notice/getting-started) of our Mobile SDKs to learn more about how to configure it to match your app UI and requirements.

### Remote file

{% hint style="info" %}
Enabling this option will prevent the configuration from being loaded from the Didomi Console.
{% endhint %}

You can provide a remote URL for the SDK to download the `didomi_config.json` configuration file from. That allows you to update the SDK configuration without having to re-publish you mobile application.

When that configuration is enabled, the SDK will automatically use the remote configuration and cache it locally. The cached version is refreshed every 60 minutes. If there is no connection available to download the remote file and no locally cached version, the SDK will try to use the local `didomi_config.json` (described above) as a fallback.

To enable that option, change your call to [initialize](https://developers.didomi.io/cmp/mobile-sdk/reference#initialize) to provide the remote file URL:�

{% tabs %}
{% tab title="Dart" %}

```dart
 DidomiSdk.initializeWithParameters(
      DidomiInitializeParameters(
            apiKey: "<Your API key>",
            remoteConfigurationURL: "http://www.website.com/didomi_config.json",
            disableDidomiRemoteConfig: false
      )
);

```

{% endtab %}
{% endtabs %}

Also see the [reference documentation of the initialize function](https://developers.didomi.io/cmp/mobile-sdk/reference#initialize) for more information.