Initialize the App SDK

Requires the lifecycle-process dependency

This snippet uses ProcessLifecycleOwner, which needs androidx.lifecycle:lifecycle-process on your app’s classpath. Add it to your app’s build.gradle(.kts) if it isn’t already there:

implementation("androidx.lifecycle:lifecycle-process:<latest_version>")

// Register on Application.onCreate() — the observer fires on the
// first genuine foreground start, not on process creation
import androidx.lifecycle.DefaultLifecycleObserver
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.ProcessLifecycleOwner
import com.usercentrics.sdk.*
import java.util.concurrent.atomic.AtomicBoolean

class MyApplication : Application() {
    private val didInitialize = AtomicBoolean(false)

    override fun onCreate() {
        super.onCreate()
        ProcessLifecycleOwner.get().lifecycle.addObserver(object : DefaultLifecycleObserver {
            override fun onStart(owner: LifecycleOwner) {
                if (didInitialize.compareAndSet(false, true)) {
                    val options = UsercentricsOptions(settingsId = <SettingsID>)
                    Usercentrics.initialize(this@MyApplication, options)
                }
            }
        })
    }
}

// e.g place this inside the [initState] of the Entry Point Widget
import 'package:usercentrics_sdk/usercentrics_sdk.dart';

Usercentrics.initialize(
    settingsId: <SettingsID>,
);

// On your App entrypoint
import { Usercentrics, UsercentricsOptions } from '@usercentrics/react-native-sdk';

// React hooks
useEffect(() => {
    let options = new UsercentricsOptions(<SettingsID>);
    Usercentrics.configure(options);
}, []);

// Or via constructor
constructor(props: any) {
    super(props)

    let options = new UsercentricsOptions(<SettingsID>)
    Usercentrics.configure(options)
}

If you are using Unity, there are two ways to initialize the SDK. Choose the one that best fits your needs:

• Auto initialization:

  • When using this option, the SDK initializes when the scene starts, and the banner is shown immediately afterward.

  • Only supports using the Usercentrics UI (customizable in the Usercentrics Admin Interface).

  • Enable this option in the Inspector tab, under AutoInitialize. After that, you can skip the rest of this chapter and continue with the Handle consent chapter to finish the integration.
    
    

• Programmatic initialization:

  • You have more control over when to show the banner.

  • You can create your own banner.

using Unity.Usercentrics;

Use isReady to fetch the latest consent status (see UsercentricsReadyStatus in the UsercentricsCore API page). This status will let you know if you need to show the banner to collect consent or only apply the already collected consent.

import com.usercentrics.sdk.*
Usercentrics.isReady({ status ->
    if (status.shouldCollectConsent) {
        // Display banner to collect consent
    } else {
        // Apply consent with status.consents
    }
}, { error ->
    // Handle non-localized error
})

See UsercentricsReadyStatus in the UsercentricsCore API page. This status will let you know if you need to show the banner to collect consent or only apply the already collected consent.

import 'package:usercentrics_sdk/usercentrics_sdk.dart';
try {
    final status = await Usercentrics.status;
    if (status.shouldCollectConsent) {
        // Show banner to collect consent
    } else {
        // Apply consent with status.consents
    }
} catch (error) {
    // Handle non-localized error
}

See UsercentricsReadyStatus in the UsercentricsCore API page. This status will let you know if you need to show the banner to collect consent or only apply the already collected consent.

import { Usercentrics } from '@usercentrics/react-native-sdk';
try {
    const status = await Usercentrics.status();
    if (status.shouldCollectConsent) {
        // Show banner to collect consent
    } else {
        // Apply consent with status.consents
    }
} catch(error) {
    // Handle error
}

On scene start, call Initialize() from a Usercentrics instance. On success, evaluate status.shouldCollectConsent.

Usercentrics.Instance.Initialize((status) => {
    if (status.shouldCollectConsent) 
    { 
        // Collect Consent
    }
    else
    {
        // Apply Consent with status.consents
    }
},(errorMessage) => {
    // Failure: Returns non-localized error
});    

Requires the lifecycle-process dependency

This snippet uses ProcessLifecycleOwner, which needs androidx.lifecycle:lifecycle-process on your app’s classpath. Add it to your app’s build.gradle(.kts) if it isn’t already there:

implementation("androidx.lifecycle:lifecycle-process:<latest_version>")

// Register on Application.onCreate() — the observer fires on the
// first genuine foreground start, not on process creation
import androidx.lifecycle.DefaultLifecycleObserver
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.ProcessLifecycleOwner
import com.usercentrics.sdk.*
import java.util.concurrent.atomic.AtomicBoolean

class MyApplication : Application() {
    private val didInitialize = AtomicBoolean(false)

    override fun onCreate() {
        super.onCreate()
        ProcessLifecycleOwner.get().lifecycle.addObserver(object : DefaultLifecycleObserver {
            override fun onStart(owner: LifecycleOwner) {
                if (didInitialize.compareAndSet(false, true)) {
                    val options = UsercentricsOptions(ruleSetId = "<RulesetID>")
                    Usercentrics.initialize(this@MyApplication, options)
                }
            }
        })
    }
}

// e.g place this inside the [initState] of the Entry Point Widget
import 'package:usercentrics_sdk/usercentrics_sdk.dart';

Usercentrics.initialize(
    ruleSetId: "<RulesetID>"
);

// On your App entrypoint
import { Usercentrics, UsercentricsOptions } from '@usercentrics/react-native-sdk';

// React hooks
useEffect(() => {
    let options: UsercentricsOptions = { ruleSetId: "<RulesetID>" };
    Usercentrics.configure(options);
}, []);

// Or via constructor
constructor(props: any) {
    super(props)

    let options: UsercentricsOptions = { ruleSetId: "<RulesetID>" };
    Usercentrics.configure(options)
}

If you are using Unity, there are two ways to initialize the SDK. Choose the one that best fits your needs:

• Auto initialization:

  • When using this option, the SDK initializes when the scene starts, and the banner is shown immediately afterward.

  • Only supports using the Usercentrics UI (customizable in the Usercentrics Admin Interface).

  • Enable this option in the Inspector tab, under AutoInitialize. After that, you can skip the rest of this chapter and continue with the Handle consent chapter to finish the integration.
    
    

• Programmatic initialization:

  • You have more control over when to show the banner.

  • You can create your own banner.

Import Usercentrics to the scene:

using Unity.Usercentrics;

Use isReady to get the geolocationRuleset (see GeolocationRuleset in the UsercentricsCore API page). This object will let you know if the banner is required according to the configurations and the user's location.

import com.usercentrics.sdk.*
Usercentrics.isReady({ status ->
    if (status.geolocationRuleset != null && status.geolocationRuleset?.bannerRequiredAtLocation == false) {
        // banner is not required at this location
        return@isReady
    }
    if (status.shouldCollectConsent) {
        // Show banner to collect consent
    } else {
        // Apply consent with status.consents
    }
}, { error ->
    // Handle non-localized error
})

import 'package:usercentrics_sdk/usercentrics_sdk.dart';

try {
    final status = await Usercentrics.status;

    if (status.geolocationRuleset != null && status.geolocationRuleset?.bannerRequiredAtLocation == false) {
        // banner is not required at this location
        return;
    }

    if (status.shouldCollectConsent) {
        // Show banner to collect consent
    } else {
        // Apply consent with status.consents
    }
} catch (error) {
    // Handle non-localized error
}

import { Usercentrics } from '@usercentrics/react-native-sdk';

try {
    const status = await Usercentrics.status();

    if (status.geolocationRuleset != null && status.geolocationRuleset?.bannerRequiredAtLocation == false) {
        // banner is not required at this location
        return
    }

    if (status.shouldCollectConsent) {
        // Show banner to collect consent
    } else {
        // Apply consent with status.consents
    }
} catch(error) {
    // Handle error
}

Usercentrics.Instance.Initialize((status) => {

    if (status.geolocationRuleset.bannerRequiredAtLocation == false)
    {
        return;
    }

    if (status.shouldCollectConsent)
    { 
        // Collect Consent
    } 
    else
    {
        // Apply Consent with status.consents
    }

},(errorMessage) => {
    // Failure: Returns non-localized error
});

Read the Display banner page to learn how to show the banner to collect consent.