SDK Initialization

What Does Initialization Do?

Initialization prepares the SDK to perform detections in the background.

If no Sentiance user exists on the device, initialization sets up the internal components required to create a user at a later stage.

If a Sentiance user is already present, the SDK initializes all components needed for detections, networking, and maintenance. Additionally, if detections were previously enabled, they are automatically resumed in the background without requiring any app intervention.

Why Initialize in the Application / AppDelegate Class?

During initialization, in addition to setting up internal components, the SDK registers the required delegates and listeners at the OS level. This enables it to receive system-generated events such as geofence exits, significant location changes, and visits.

When such an event occurs and the app is not running, the OS launches it in the background and expects these delegates and listeners to be set during the startup phase before delivering the event. To avoid missing events, the SDK must also complete its setup during this phase. For this reason, the SDK must be initialized as part of app startup.

On iOS, during initialization, the SDK not only sets up delegates but also registers its background processing tasks with the OS. This registration must happen during the app’s startup phase; otherwise, these tasks will not be scheduled or executed. On iOS, the startup phase ends when application(_:didFinishLaunchingWithOptions:) returns. On Android, it ends when Application.onCreate() returns.

Note that app startup logic runs on the main thread. If SDK initialization is offloaded to a background thread, there is no guarantee it will complete before the startup phase ends. It is therefore important to perform initialization on the main thread. The SDK is designed to initialize quickly and should not noticeably delay app startup.

Initialize On Every Startup, Once

You must initialize the SDK on every app startup. In most cases, initialization only needs to happen once during the app process lifetime. Any subsequent initialization attempts will fail unless the SDK has been reset.

Before a Sentiance user is created, it is technically possible to call initialization multiple times, for example to override previously provided options. However, once a user has been created, any further initialization attempts within the same app lifecycle will fail.

To verify whether the SDK has already been initialized, check the initState property of the Sentiance class.

SDK Reset

To remove all SDK data and user-related information from a device, call the .reset() method on the SDK’s core instance.

This will remove:

• Stored SDK data

• Settings and configurations

• Detection data

• All user-related data on the device

After a reset:

This method will remove the Sentiance user from the device and will require re-authentication. The user is removed from the device, but not necessarily from the Sentiance platform

Important Notes on Reset

• During an ongoing reset operation, other SDK method calls may be ignored, fail, or return default values

• Ensure the app remains in the foreground during the reset process (e.g., an activity is open or a foreground service is running) to avoid interruption. The SDK cannot guarantee completion if the app is backgrounded or terminated

• The reset() method can be called even if the SDK has not been initialized