Links

Sentiance

The Sentiance class is the main entry point for interacting with the SDK.

shared

The Singleton instance to get the shared instance of the SDK.
Usage: Sentiance.shared
+ (instancetype) shared;

sdkStatus

Get SDK status information
@property (nonatomic, readonly) SENTSDKStatus *sdkStatus;

initState

Return state of initialisation of the SDK: SENTNotInitialized, SENTInitInProgress, SENTInitialized.
@property (nonatomic, readonly) SENTSDKInitState initState;

detectionStatus

Get current detection status.
@property (nonatomic, readonly) SENTDetectionStatus detectionStatus;

userActivity

SDK current user activity state. It is a trip or stationary with some enriched information.
@property (nonatomic, readonly) SENTUserActivity * userActivity;

criteriaMaskForUserContextUpdates

This method is part of an Early Access feature, and is subject to change in the future.
The criteria for which the delegate property userContextDelegate will get invoked.
@property (nonatomic, assign) SENTUserContextUpdateCriteria criteriaMaskForUserContextUpdates;

userContextDelegate

This method is part of an Early Access feature, and is subject to change in the future.
Delegate property which gets notified when the userContext is updated
@property (nonatomic, weak) id<SENTUserContextDelegate> _Nullable userContextDelegate

version

SDK Version property
@property (nonatomic, readonly) NSString * version;

userId

Returns the user ID.
@property (nonatomic, readonly, nullable) NSString * userId;

userExists

Checks if a Sentiance user exists on the device. You may call this method without having initialized the SDK. Returns true if a Sentiance user exists.
@property (nonatomic, readonly) BOOL userExists;

isUserLinked

Checks if a Sentiance user exists on the device, and whether it is linked to your app's user. You may call this method without having initialized the SDK. Returns true if a Sentiance user exists and is linked.
@property (nonatomic, readonly) BOOL isUserLinked;

isVehicleCrashDetectionSupported

Checks if vehicle crash detection is supported on the device. The result depends on multiple criteria, such as if vehicle crash detection is enabled for your app, and if the necessary sensors are present on the device.
@property (nonatomic, readonly) BOOL isVehicleCrashDetectionSupported;

wifiQuotaLimit

SDK WiFi quota limit
@property (nonatomic, readonly) long wifiQuotaLimit;

wifiQuotaUsage

SDK WiFi quota usage
@property (nonatomic, readonly) long wifiQuotaUsage;

mobileQuotaLimit

SDK mobile data quota limit
@property (nonatomic, readonly) long mobileQuotaLimit;

mobileQuotaUsage

Get SDK mobile data quota usage
@property (nonatomic, readonly) long mobileQuotaUsage;

diskQuotaLimit

SDK disk quota limit
@property (nonatomic, readonly) long diskQuotaLimit;

diskQuotaUsage

SDK disk quota usage
@property (nonatomic, readonly) long diskQuotaUsage;

initWithConfig: success: failure:

Deprecated
This method is deprecated. Use initializeWithOptions: launchOptions: instead.
SDK initialization method. It sets up the modules internally and handles user authentication.
- (void) initWithConfig: (SENTConfig *) config
success: (void (^)(void)) success
failure: (void (^)(SENTInitIssue issue)) failure;
Parameter
config
The configuration used to authenticate the user.
success
The success block called when init succeeded.
failure
The failure block called when init failed. It takes a SENTInitIssue issue indicating the reason of the failure.
Init should only be called once, unless initialization fails.

initializeWithOptions: launchOptions:

Initializes the Sentiance SDK.
- (SENTInitializationResult *)initializeWithOptions:(SENTOptions *)options
launchOptions:(nullable NSDictionary *)launchOptions
NS_SWIFT_NAME(initialize(options:launchOptions:));
This method must be called on the main thread, inside
[AppDelegate application:application didFinishLaunchingWithOptions:launchOptions]
It must not be called asynchronously, as doing so does not guarantee that it will be invoked before application:didFinishLaunchingWithOptions: completes.
For more details on this, see SDK Initialization.
Most SDK methods require an initialized SDK before being invoked, otherwise they throw a runtime exception. Methods excluded from this requirement mention this in their respective documentation.
You should initialize the SDK at most once, during app startup. Initializing it multiple times will normally fail with reason SENTInitializationFailureReasonReinitializationNotAllowed
unless a user does not exist yet (e.g. before user creation or after an SDK reset), in which case multiple initializations are still allowed.
Parameter
Description
options
the SDK initialization options.
launchOptions
the launch options obtained from [AppDelegate application:application didFinishLaunchingWithOptions:launchOptions]

start:

Deprecated
This method is deprecated. Use enableDetectionsWithCompletionHandler: instead.
Start the SDK.
- (void) start: (void (^)(SENTSDKStatus* status)) completion;
Callback
completion
The completion block called when the SDK has started. SENTSDKStatus object indicates any issue that occurred when the SDK started.
start should be called only after the SDK has been successfully initialized.

startWithStopDate: completion:

Deprecated
This method is deprecated. Use enableDetectionsWithExpiryDate: completionHandler: instead.
Start the SDK with expiration date.
- (void)startWithStopDate:(NSDate *)sdkStopDate
completion:(void (^)(SENTSDKStatus *status))completion;
Parameter
sdkStopDate
Should be set with date in the future. Dates in past will cause imediate stop of SDK. Setting nil will start SDK as usual.
Callback
completion
The completion block called when the SDK has started. SENTSDKStatus object indicates any issue that occurred when the SDK started.

stop

Deprecated
This method is deprecated. Use disableDetectionsWithCompletionHandler: instead.
Stop the SDK.
- (void) stop;

enableDetectionsWithCompletionHandler:

Enables SDK detections.
Requires a Sentiance user to be present on the device. Enabling detections is persistent across app restarts. Therefore, you do not need to call this method on every app startup. Once detections are enabled, as long as the SDK is properly initialized during startup, detections will be resumed, until you disable them by calling disableDetections.
Enabling detections does not mean that the SDK is successfully able to start all detections. There may be unsatisfactory conditions that are blocking some detections. Check the DetectionStatus returned in the result to see if all detections are running and the SdkStatus to identify possible causes if not.
To automatically disable detections after some time, use the enableDetectionsWithExpiryDate: variant of this method.
method throws SdkException if the SDK is not initialized.
- (void) enableDetectionsWithCompletionHandler: (nullable SENTEnableDetectionsCompletionHandler) completionHandler;

enableDetectionsWithExpiryDate: completionHandler:

Enables SDK Detections with an expiry date at which detections get disabled.
Requires a Sentiance user to be present on the device. Enabling detections is persistent across app restarts. Therefore, you do not need to call this method on every app startup. Once detections are enabled, as long as the SDK is properly initialized during startup, detections will be resumed, until you disable them by calling disableDetections(), or they expire (see expirationDate).
Enabling detections does not mean that the SDK is successfully able to start all detections. There may be unsatisfactory conditions that are blocking some detections. Check the DetectionStatus returned in the result to see if all detections are running, and the sdkStatus to identify possible causes if not.
This method has the same behaviour as enableDetections:, except an expiration date can be specified, as an absolute Date object, to automatically disable detections some time in the future. After having called this method with a future expiration date, you can cancel the expiration any time by calling enableDetections: again.
- (void) enableDetectionsWithExpiryDate: (nullable NSDate*) expiryDate
completionHandler: (nullable SENTEnableDetectionsCompletionHandler) completionHandler
NS_SWIFT_NAME(enableDetections(expiryDate:completionHandler:));

disableDetectionsWithCompletionHandler:

Disables SDK detections.
Currently, this operation always succeeds. However, this behaviour may change in the future.
Also throws NSException – if the SDK is not initialized.
- (void) disableDetectionsWithCompletionHandler: (nullable SENTDisableDetectionsCompletionHandler) completionHandler;

createUserWithOptions: completionHandler:

Creates a Sentiance user if one does not yet exist.
Most SDK functionality requires a Sentiance user to be present on the device. Therefore, create a user first before enabling detections or interacting with other SDK features.
Parameter: Options - For creating a User.
Throws: NSException if the SDK is not initialized.
- (void)createUserWithOptions: (SENTUserCreationOptions*) options
completionHandler: (nullable SENTUserCreationCompletionHandler) completionHandler
NS_SWIFT_NAME(createUser(options:completionHandler:));

linkUserWithLinker: completionHandler:

Links the Sentiance user to your app's user on the Sentiance Platform.
During the linking process, the SDK will invoke the supplied SENTUserLinker, and will pass to it an installation ID. Your app must then forward this installation ID to the Sentiance backend (via your backend), and initiate user linking. Finally, when the linking completes, you must invoke the proper linker callback to complete the process.
Here are the complete steps:
  1. 1.
    Call this method and supply a linker.
  2. 2.
    Your linker will be invoked during the process, and an installation ID will be supplied.
  3. 3.
    In your linker, forward the installation ID to your backend to initiate a linking request towards the Sentiance backend. This request will include the installation ID and your app's user identifier.
  4. 4.
    Retrieve the response from the Sentiance backend and forward the result to the app.
  5. 5.
    Based on the result, invoke the linker callback's success or failure method. The callback is supplied to your linker along with the installation ID.
  6. 6.
    If it was successful, the SDK will confirm the result with the Sentiance backend to complete the link.
This method is useful if you want to link a Sentiance user that was created without specifying a linker in the user creation options (thereby having created an unlinked user).
With this method, a Sentiance user cannot be linked to an app user that already exists on the Sentiance Platform (i.e. with an app user identifier that you already supplied to Sentiance during a past linking request).
You can only link to an app user that is new to Sentiance. This is because an existing app user will already have a corresponding Sentiance user on the platform, and that Sentiance user cannot be restored here anymore. To restore that user, you must reset the SDK and recreate a linked Sentiance user instead.
parameter: linker: the linker that the SDK will pass the installation ID to and execute success and failure closures according to result.
throws: SdkException if the SDK is not initialized.
- (void)linkUserWithLinker: (SENTUserLinker) linker
completionHandler: (nullable SENTUserLinkingCompletionHandler) completionHandler;

linkUserWithAuthCode: completionHandler:

Links the Sentiance user to your app's user on the Sentiance Platform.
Uses the supplied authentication code to find the app user. Therefore, before calling this method, make sure that you have obtained a valid code from the backend Sentiance API (thereby having initiated the first linking step). This code request is authenticated using a Sentiance API key, which must never be transmitted to the app. Hence why the request must come from your backend.
Here are the complete steps:
  1. 1.
    Retrieve the code in your app and supply it to this method.
  2. 2.
    Initiate an authentication code request via your backend towards the Sentiance backend. This request will include your app's user identifier, which will be temporarily coupled to the code that you will receive.
  3. 3.
    The SDK will forward the code to the Sentiance backend to complete the link.
This method is useful if you want to link a Sentiance user that was previously created without specifying a linker in the user creation options (thereby having created an unlinked user).
With this method, a Sentiance user cannot be linked to an app user that already exists on the Sentiance Platform (i.e. with an app user identifier that you already supplied to Sentiance during a past authentication code request). You can only link to an app user that is new to Sentiance.
This is because an existing app user will already have a corresponding Sentiance user on the platform, and that Sentiance user cannot be restored here anymore. To restore that user, you must reset the SDK and recreate a linked Sentiance user instead.
parameters: authCode - a code obtained from the backend Sentiance API.
throws: NSException if the SDK is not initialized.
- (void)linkUserWithAuthCode: (NSString *)authCode
completionHandler: (nullable SENTUserLinkingCompletionHandler) completionHandler
NS_SWIFT_NAME(linkUser(authCode:completionHandler:));

requestUserAccessTokenWithCompletionHandler:

Returns the user's API access token as a Token object, via the completion Handler.
The token might be refreshed during this call, in which case, a valid network connection is required. You can use this token to query the Sentiance API for the user's data.
throws: NSException if the SDK is not initialized.
- (void)requestUserAccessTokenWithCompletionHandler: (SENTUserAccessTokenCompletionHandler) completionHandler;

requestUserContextWithCompletionHandler:

Fetches the userContext which holds the information about events, activeMoments, activeSegments, lastKnownLocation, home and work venues.
- (void)requestUserContextWithCompletionHandler: (SENTRequestUserContextCompletionHandler) completionHandler;

getUserId

Deprecated
getUserId is deprecated. Use userId instead.
Returns the user ID
- (NSString *) getUserId;

getUserAccessToken:

Deprecated
getUserAccessToken is deprecated. Use requestUserAccessToken instead.
Returns the users Access Token if the user is authenticated
- (void) getUserAccessToken: (void (^)(NSString *token)) success
failure: (void (^)(void)) failure;

addUserMetadataField: value:

Interface method to set metadata for user. Metadata is any additional data that enclosing app is willing to set for this user/app combination This metadata could contain vital information related to procesing wrt to the enclosing app.
- (void) addUserMetadataField: (NSString*) label
value: (NSString*) value;
Parameter
label
Field name for the new entry.
value
Value for the new entry.

addUserMetadataFields:

Interface method to set metadata for user. Metadata is any additional data that enclosing app is willing to set for this user/app combination This metadata could contain vital information related to processing wrt to the enclosing app.
- (void) addUserMetadataFields: (NSDictionary *) metadata;
Parameter
metadata
Key value pair data from enclosing app, could have any structure as long as it can be contained in a dictionary.

removeUserMetadataField:

Method to remove user data field to the sdk metadata (locally as well as on backend).
- (void) removeUserMetadataField:(NSString*)label;
Parameter
label
Field name for the new entry.

addTripMetadata:

add metadata pertaining to the ongoing external trip. All added metadata will be aggregated and added to the trip payload. Returns NO if there's no ongoing external trip.
- (BOOL)addTripMetadata:(NSDictionary *)metadata;
Parameter
metadata
key value pair data from enclosing app, could have any structure as long as it can be contained in a dictionary. The only time we return NO is when a trip is not ongoing, metadata contains NSNull objects or nil itself.

startTripWithMetadata: transportModeHint: completionHandler:

Starts an external trip. Requires a Sentiance user to be present on the device.
Calling this method interrupts any ongoing SDK detection, and forces the SDK to stay in a data collection mode. Trips started with this method may time out, in which case, the TripTimeoutListener set using setTripTimeoutListener(TripTimeoutListener) will be invoked.
The timeout duration can be configured for your app by Sentiance.
- (void)startTripWithMetadata: (nullable NSDictionary *) metadata
transportModeHint: (SENTTransportMode)mode
completionHandler: (nullable SENTStartTripCompletionHandler) completionHandler
NS_SWIFT_NAME(startTrip(metadata:transportModeHint:completionHandler:));
parameters:
metadata - A map of metadata pertaining to the newly started trip, which will be saved along with
the trip data, and made available in backend API query results and offloads. May be null.
mode - A hint of the transport mode being used, if known. May be <code>null</code>.
throws: NSException if the SDK is not initialized.

startTrip: transportModeHint: success: failure:

Deprecated
This method is deprecated. Use startTripWithMetadata: transportModeHint: completionHandler: instead.
Start a Trip manually
- (void) startTrip: (NSDictionary*) metadata
transportModeHint: (SENTTransportMode) mode
success: (void (^)(void)) success
failure: (void (^)(SENTSDKStatus* status)) failure;
Parameter
metadata
Key value pair data from enclosing app, could have any structure as long as it can be contained in a dictionary.
transportModeHint
Suggest of transport mode

stopTrip: failure:

Deprecated
This method is deprecated. Use stopTripWithCompletionHandler: instead.
Stop a trip.
- (void) stopTrip: (void (^)(void)) success
failure: (void (^)(SENTSDKStatus* status)) failure;

stopTripWithCompletionHandler:

Stops the currently ongoing external trip (i.e one that was started by calling startTrip()
Throws: NSException if the SDK is not initialized.
- (void)stopTripWithCompletionHandler: (nullable SENTStopTripCompletionHandler) completionHandler;

setTripTimeOutListener:

Set a trip timeout block.
- (void) setTripTimeOutListener: (void (^)(void)) tripDidTimeOut;
tripDidTimeOut block will be called each time trip will time out

isVehicleCrashDetectionSupported:

Checks if vehicle crash detection is supported on the device for the specified trip type.
The result depends on multiple criteria, such as if vehicle crash detection is enabled for your app, and if the necessary sensors are present on the device.
- (BOOL)isVehicleCrashDetectionSupported:(SENTTripType)tripType;
Parameter
tripType
The type of trip for which you want to check

invokeDummyVehicleCrash

Invokes a dummy vehicle crash event. Use this method to test your vehicle crash detection integration.
Calling this method will invoke the handler from setVehicleCrashHandler:or setCrashListener:depending on which handler was set last.
- (void)invokeDummyVehicleCrash;
This method is intended for testing your integration, and not for production use.

setCrashListener:

Deprecated
setCrashListener: is deprecated. Use setVehicleCrashHandler: instead.
Set vehicle crash detection block.
- (void)setCrashListener:(void (^)(NSDate *date, CLLocation *lastKnownLocation))crashCallback;

setVehicleCrashHandler:

Sets a handler that is invoked when a vehicle crash is detected with an instance of SENTVehicleCrashEvent.
- (void)setVehicleCrashHandler:(void (^)(SENTVehicleCrashEvent *crashEvent))vehicleCrashHandler;

setUserActivityListener:

This method provides the enclosing app the ability to get SDK detection updates. So when the SDK is in a trip or a stationary, it informs the app via a callback, providing some extra information.
- (void)setUserActivityListerner:(void (^)(SENTUserActivity *userActivity))onChange;

getUserActivity

This method provides the enclosing app the ability to get SDK current user activity state. It is a trip or stationary with some enriched information.
- (SENTUserActivity *)getUserActivity;

isTripOngoing:

Interface method to check if trip is in progress or not.
- (BOOL) isTripOngoing: (SENTTripType) tripType;
Parameter
tripType
Type of ongoing trip, SDK - started by SDK, External - started by the application

submitDetections: failure:

Deprecated
This method is deprecated. Use submitDetectionsWithCompletionHandler: instead.
Submits all the pending detections to backend, without considering any quota related updates and returns the status of these submissions via a callback to the enclosing app.
- (void) submitDetections: (void (^)(void)) success
failure: (void (^)(void)) failure;
Parameter
success
Success block which is to be called when forced submission completes.
failure
Failure block which is to be called when forced submission completes.

submitDetectionsWithCompletionHandler:

Submits any pending SDK detection to the Sentiance API.
This method will bypass any network quota limitation set for the SDK. A typical use case would be when the enclosing app determines (via diskQuotaUsage or diskQuotaStatus) that there are too many detections on disk that have not yet been submitted.
Throws: NSException if the SDK is not initialized.

getInitState

Deprecated
This method is deprecated. Use initState property instead.
Return state of inialization of the SDK: SENTNotInitialized, SENTInitInProgress, SENTInitialized
- (SENTSDKInitState) getInitState;

getSdkStatus

Deprecated
Use sdkStatus property instead.
Get SDK status information
- (SENTSDKStatus*) getSdkStatus;

getVersion

Deprecated
Use version property instead.
Get SDK version
- (NSString *) getVersion;

getWifiQuotaLimit

Deprecated
Use wifiQuotaLimit: property instead.
Get SDK WiFi quota limit
- (long) getWifiQuotaLimit;

getWiFiQuotaUsage

Deprecated
Use wifiQuotaUsage property instead.
Get SDK WiFi quota usage
- (long) getWiFiQuotaUsage;

getMobileQuotaLimit

Deprecated
Use mobileQuotaLimit instead.
Get SDK mobile data quota limit
- (long) getMobileQuotaLimit;

getMobileQuotaUsage

Deprecated
Use mobileQuotaUsage instead.
Get SDK mobile data quota usage
- (long) getMobileQuotaUsage;

getDiskQuotaLimit

Deprecated
Use diskQuotaLimit property instead.
Get SDK disk quota limit
- (long) getDiskQuotaLimit;

getDiskQuotaUsage

Deprecated
Use diskQuotaUsage: instead.
Get SDK disk quota usage
- (long) getDiskQuotaUsage;

resetWithCompletionHandler:

Resets the Sentiance SDK.
Calling this method results in stopping of all SDK operations and the deletion of all user data from the device. To avoid losing unsubmitted detection data, you can call submitDetections() before resetting the SDK as a final (best effort) attempt. However, keep in mind that this can introduce a delay to your reset process, since it is impacted by the network capability and the number of pending detections.
During an ongoing reset operation, calling any other SDK method will be ignored, fail, or will return a default result. After the reset operation completes, you do not have to reinitialize the SDK, but can do so by calling initialize(SentianceOptions)} again (e.g. to supply a different SentianceOptions).
While resetting, make sure that your app is in the foreground to prevent process termination (i.e. an activity is open, or a foreground service is running). The SDK cannot guarantee the completion of this operation otherwise.
You may call this method without having initialized the SDK.
Parameter
Text
completionHandler
a completion handler to receive the result of the reset operation.
- (void)resetWithCompletionHandler: (nullable SENTResetCompletionHandler)completionHandler;