Android
Last updated
Last updated
Version 6.x brings a lot of improvements and new features to the Sentiance SDK, like a simpler API for initialization, user creation, authentication and linking users. Some of these improvements result in breaking changes in the existing integration. This section describes all the changes that were made since version 4.22.1, and provides two code migration paths: a minimal one that utilizes existing (but deprecated) APIs, and a full one that utilizes only the new APIs.
We have bumped the minimum supported Android version to 6.0 (Marshmallow—API level 23). If you target an older version of Android, please see troubleshooting guide to learn how to resolve related issues.
Version 6.x makes use of Java 8 language features. Make sure your app is configured to support Java 8. See guide.
Version 4.x automatically applied the following rule when compiling your app:
Though beneficial for using stack traces, there was no way for developers to omit this rule if desired to do so. In version 6.x, we have omitted this rule from our libraries.
Important
If you want to retain debugging information for your app (e.g. to troubleshoot crashes), make sure that this rule exists in your app's own proguard rules file.
We have updated the minimum required version of the Google Play Services location library (com.google.android.gms:play-services-location) to 18.0.0. If your app targets a different version, please note that Gradle will automatically pick the highest one. You can verify which version is being picked by running:
You should see something similar to line 6 above. However, if you have explicitly excluded the location library from the Sentiance SDK's transitive dependencies (see the below example), please either omit this exclusion, or update the location library version defined in your app's dependencies.
After making the above change, run ./gradlew app:dependencies to verify the chosen library version.
As version 4.x targeted an older version of the Google Play Service location library, it brought along with it some old android-support transitive dependencies. With the version 18.0.0, these support libraries have now been replaced with their AndroidX counterparts.
If you reference our SDK as a local aar file inside your project, or by hosting it in a private repository, please make sure all of the new dependencies are met, including transitive ones.
The core Sentiance functionality is provided by the com.sentiance:sdk artifact. This includes operations like creating a Sentiance user, and starting detections. Other library artifacts act as extensions that include additional Sentiance features and functionality. For example, com.sentiance:sdk-crash-detection includes the crash detection feature.
To enable these additional features, you need to add the corresponding artifact as a dependency in your app. You can make use of the SDK's bill of materials (BOM) artifact to reference a single version and avoid incompatibility issues:
Some features must be activated by Sentiance before you can start using them. Please reach out to our support team to make sure that the feature you want to use is activated.
We have updated the SDK API methods and classes to make it easier to integrate our SDK into your app. By doing so, we have deprecated some existing API methods and classes. These APIs will still function properly, however we plan to remove them in the next major release.
The following classes and interfaces under the com.sentiance.sdk package have been renamed:
MetaUserLinker
UserLinker
MetaUserLinkerAsync
UserLinkerAsync
MetaUserLinkerCallback
UserLinkerCallback
The setMetaUserLinker method of the SdkConfig.Builder class has been renamed to setUserLinker.
The startStatus field has been deprecated. The new detectionStatus field has been added as its successor.
Crash detection is now made available via a separate library artifact. You therefore need to add com.sentiance:sdk-crash-detection as a dependency to your app, in order to activate the feature.
The new entry point for crash detection related functionality is the CrashDetectionApi class. The following methods have therefore been removed from the Sentiance class and are now available in the CrashDetectionApi class:
invokeDummyVehicleCrash (no signature change)
setVehicleCrashListener (no signature change)
isVehicleCrashDetectionSupported (signature update: the TripType parameter has been removed)
Additionally, the following classes and interfaces have been moved to the com.sentiance.sdk.crashdetection.api package:
VehicleCrashEvent (the existing properties of this class are no longer nullable).
VehicleCrashListener
Lastly, the following (previously deprecated) API classes and methods have been removed:
com.sentiance.sdk.crashdetection.CrashCallback
Sentiance.setCrashCallback(CrashCallback callback)
PendingOperation allows you to set success, failure, and completion handlers to asynchronously handle an operation's result.
Moreover, it offers the possibility to wait for the result up to a certain duration, or until completion.
The existing SDK initializer served two purposes:
Create a Sentiance user if one does not exist;
initialize internal SDK components and resume detections.
We have deprecated the existing initializer init in favor of a new method called initialize. This new method does not create a Sentiance user. Instead, if a Sentiance user already exists, it initializes the SDK internally and resumes detections (if detections were enabled in the past).
To create a Sentiance user, we have added a new method called createUser. You can use this method to create a Sentiance user anywhere in your app. Note that you can only create one user at any time. To create a different user, you must first reset the SDK.
Given that user creation is not part of initialization anymore, we expect apps to initialize the SDK during app startup, without postponing or delaying it. The new initializer can safely be called when a Sentiance user does not exist yet, as it will only do minimal work to prepare the SDK for user creation.
As long as a Sentiance user exists on the device, you are expected to initialize the SDK during app startup, without delay or postponement. If you intend to not run detections for a brief period, simply call disableDetections instead. If you intend to not run detections for a longer duration, simply reset the SDK to remove the user from the device.
The deprecated method isInitialized() from Sentiance has also been removed. Use getInitState() instead.
You can use the new userExists() method to find out whether a Sentiance user already exists. And to check whether the user has been successfully linked (i.e. user linking), you can call isUserLinked().
Unlike the other SDK methods, these two methods can be called without needing to initialize the SDK first.
If your app makes use of the vehicle crash detection feature, add the com.sentiance:sdk-crash-detection dependency.
Replace the SDK status isLocationPermGranted field usage with locationPermission.
Replace isInitialized() usage with getInitState().
If your app makes use of the vehicle crash detection feature, add the com.sentiance:sdk-crash-detection dependency.
In your existing integration, you initialize the Sentiance SDK by calling init from within your Application's onCreate method. Replace init with the new initialize method. This method accepts a SentianceOptions object which you can create using its Builder. You can set a custom Android notification that the SDK can use via this Builder.
The following options are no longer available as initialization options:
Base URL (i.e. Sentiance platform URL): you will only need to specify this once, when creating a Sentiance user.
User linker: you will need to pass a linker when creating a user instead.
Sentiance credentials (i.e. app ID & secret): you will only need to specify these once, when creating a Sentiance user.
SDK status update handler: use the setSdkStatusUpdateListener method from Sentiance.
The Sentiance SDK must be initialized before creating a user. Therefore, remove any conditional checks that require the presence of a user before initializing the SDK. Calling initialize during app startup when there is no Sentiance user yet will not create a user. It will only do the necessary setup to make it possible to create a user later on.
Initialization is now always synchronous, and therefore you will receive the result as an InitializationResult object after calling initialize.
In your existing integration, you will likely have some conditional logic that calls init to create a Sentiance user. Replace this call with createUser. This method accepts UserCreationOptions, allowing you to specify the Sentiance app credentials (app ID and secret), the Sentiance platform URL (optional), and a user linker. If your existing integration does not make use of user linking, pass UserLinker.NO_OP as the linker.
createUser returns the newly introduced PendingOperation, which you can use to capture the user creation result.
We have deprecated the existing start() and stop() methods, and replaced them with enableDetections() and disableDetections() respectively. We believe these new methods give more clarity on what start and stop did in the past, as calling start did not always start detections, for example, due to a detection issue (e.g. in case of insufficient permissions).
These new methods are persistent across app restarts and device reboots. Therefore, you only need to call them once, and the SDK will automatically resume (or halt) detections upon initialization.
Additionally, we've added a new method called getDetectionStatus() which we believe offers better clarity on the status of the detections. The possible results are: DISABLED, EXPIRED, ENABLED_BUT_BLOCKED, and ENABLED_AND_DETECTING. For cases when the detections are blocked, the SdkStatus is still available to get more information about what is blocking detections (e.g. insufficient permissions).
Replace the usage of the following asynchronous SDK methods with their new PendingOperation returning counterparts:
reset(ResetCallback)
reset()
getUserAccessToken(TokenResultCallback)
requestUserAccessToken()
startTrip(Map, TransportMode, StartTripCallback)
startTrip(Map, TransportMode)
stopTrip(StopTripCallback)
stopTrip()
submitDetections(SubmitDetectionsCallback)
submitDetections()
The new methods return a PendingOperation result which you can use to capture the operation's result.
Replace the SDK status isLocationPermGranted field usage with locationPermission.
Replace isInitialized() usage with getInitState().
The stopAfter(seconds) method is no longer available.
User metadata methods no longer accept MetadataCallback as a 3rd parameter. Adding and removing metadata is now done asynchronously via the payload submission system.
Registering external events is no longer available.
All callback and listener methods are now executed on the application's main thread. If you perform any long running or network operations directly in the callbacks, please take care to move them to a background thread instead.
getWiFiLastSeenTimestamp() is no longer available.
The CrashCallback's Location parameter is now @Nullable.
Version 6.x breaks down SDK features and functionality into multiple artifacts, each with its own dependencies. Check to see all the artifacts and dependencies.
The that are applied by the Sentiance SDK have been updated. If you have overwritten the backup rules in your app's manifest, please update it by including any missing SDK rule. See troubleshooting guide.
The boolean status field isLocationPermGranted has been removed, and replaced with a new enum field .
Existing asynchronous SDK methods have been deprecated. New asynchronous methods have been added, that return a , which is similar to the .
To learn more about what PendingOperation offers, see the API reference page .
The following steps describe the minimal changes that you have to do, in order to compile and run your app with v6.x of the Sentiance SDK. Depending on your development environment and integration method, you might need to make additional changes that are not mentioned here. If you haven't already done so, please go through the section in order to get a complete list of the changes that were made in version 6.x.
Make sure your app supports Java 8. See guide.
In your app, update the Sentiance SDK dependency to use the BOM artifact, and reference v6.x of the SDK. See .
If you have specified custom backup rules in your app's manifest file, add the missing SDK rules. See .
For user linking, update the class and interface names. See .
For vehicle crash detection, update the package name of the imported classes and utilize the CrashDetectionApi class to access the crash detection methods with their updated signatures. See . If you were using the deprecated crash detection methods from the Sentiance class, migrate to the new ones.
The following steps describe all the changes that you have to do, in order to replace deprecated Sentiance API usage with non-deprecated counterparts, and successfully compile and run your app after updating to v6.x. Depending on your development environment and integration method, you might need to make additional changes that are not mentioned here. If you haven't already done so, please go through the section in order to get a complete list of the changes that were made in version 6.x.
Make sure your app supports Java 8. See guide.
In your app, update the Sentiance SDK dependency to use the BOM artifact, and reference v6.x of the SDK. See .
If you have specified custom backup rules in your app's manifest file, add the missing SDK rules. See .
: it's not possible to set this flavor programmatically anymore. This must be configured for your app on the Sentiance platform. Please reach out to our support team to make sure it is configured properly.
We expect apps to initialize the Sentiance SDK during app startup, without any postponement. Therefore, the new initializer must be called synchronously on the main thread, before Application.onCreate() completes ().
In addition to the user-linker based approach of creating users, we have introduced an improved linked-user creation mechanism, which replaces the Sentiance app credentials with a temporary authentication code, obtained from Sentiance at the moment of user creation. This is our recommended approach for creating users in all new integrations. You can read more about it .
Update the package name of the imported classes and utilize the CrashDetectionApi class to access the crash detection methods with their updated signatures. See . If you were using the deprecated crash detection methods from the Sentiance class, migrate to the new ones.
Initializing the SDK is done by calling the method and passing an object. now expects a notification as the 3rd parameter. enableForeground(notification) is no longer available for this purpose. The SDK will show a notification depending on the OS version, targeted API level, and remote app configuration.
and methods now require and parameters respectively.
The SDK no longer returns a Trip object when a trip is stopped. The method of no longer returns a Trip object. Similarly, the onTripStopped() method of no longer exists. This interface now provides an and methods.
The method now expects a parameter of type .