Sentiance
The Sentiance class is the main entry point for interacting with the SDK.
The Singleton instance to get the shared instance of the SDK.
Usage: Sentiance.shared
+ (instancetype) shared;
Get SDK status information
@property (nonatomic, readonly) SENTSDKStatus *sdkStatus;
Return state of initialisation of the SDK: SENTNotInitialized, SENTInitInProgress, SENTInitialized.
@property (nonatomic, readonly) SENTSDKInitState initState;
Get current detection status.
@property (nonatomic, readonly) SENTDetectionStatus detectionStatus;
SDK current user activity state. It is a trip or stationary with some enriched information.
@property (nonatomic, readonly) SENTUserActivity * userActivity;
The criteria for which the delegate property
userContextDelegate will get invoked.@property (nonatomic, assign) SENTUserContextUpdateCriteria criteriaMaskForUserContextUpdates;
Delegate property which gets notified when the userContext is updated
@property (nonatomic, weak) id<SENTUserContextDelegate> _Nullable userContextDelegate
SDK Version property
@property (nonatomic, readonly) NSString * version;
Returns the user ID.
@property (nonatomic, readonly, nullable) NSString * userId;
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;
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;
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;
SDK WiFi quota limit
@property (nonatomic, readonly) long wifiQuotaLimit;
SDK WiFi quota usage
@property (nonatomic, readonly) long wifiQuotaUsage;
SDK mobile data quota limit
@property (nonatomic, readonly) long mobileQuotaLimit;
Get SDK mobile data quota usage
@property (nonatomic, readonly) long mobileQuotaUsage;
SDK disk quota limit
@property (nonatomic, readonly) long diskQuotaLimit;
SDK disk quota usage
@property (nonatomic, readonly) long diskQuotaUsage;
Deprecated
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.
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.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
SENTInitializationFailureReasonReinitializationNotAllowedunless 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] |
Deprecated
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.
Deprecated
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. |
Deprecated
Stop the SDK.
- (void) stop;
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;
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:));
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;
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.
Throws: NSException if the SDK is not initialized.
- (void)createUserWithOptions: (SENTUserCreationOptions*) options
completionHandler: (nullable SENTUserCreationCompletionHandler) completionHandler
NS_SWIFT_NAME(createUser(options: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.Call this method and supply a linker.
- 2.Your linker will be invoked during the process, and an installation ID will be supplied.
- 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.Retrieve the response from the Sentiance backend and forward the result to the app.
- 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.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;
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.Retrieve the code in your app and supply it to this method.
- 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.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:));
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;
Fetches the userContext which holds the information about events, activeMoments, activeSegments, lastKnownLocation, home and work venues.
- (void)requestUserContextWithCompletionHandler: (SENTRequestUserContextCompletionHandler) completionHandler;
Deprecated
Returns the user ID
- (NSString *) getUserId;
Deprecated
Returns the users Access Token if the user is authenticated
- (void) getUserAccessToken: (void (^)(NSString *token)) success
failure: (void (^)(void)) failure;
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. |
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. |
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. |
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. |
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.
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 |
Deprecated
Stop a trip.
- (void) stopTrip: (void (^)(void)) success
failure: (void (^)(SENTSDKStatus* status)) failure;
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;
Set a trip timeout block.
- (void) setTripTimeOutListener: (void (^)(void)) tripDidTimeOut;
tripDidTimeOut block will be called each time trip will time out
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 |
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.
Deprecated
Set vehicle crash detection block.
- (void)setCrashListener:(void (^)(NSDate *date, CLLocation *lastKnownLocation))crashCallback;
Sets a handler that is invoked when a vehicle crash is detected with an instance of
SENTVehicleCrashEvent.- (void)setVehicleCrashHandler:(void (^)(SENTVehicleCrashEvent *crashEvent))vehicleCrashHandler;
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;
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;
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 |
Deprecated
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. |
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.
Deprecated
Return state of inialization of the SDK: SENTNotInitialized, SENTInitInProgress, SENTInitialized
- (SENTSDKInitState) getInitState;
Deprecated
Get SDK status information
- (SENTSDKStatus*) getSdkStatus;
Deprecated
Get SDK version
- (NSString *) getVersion;
Deprecated
Get SDK WiFi quota limit
- (long) getWifiQuotaLimit;
Deprecated
Get SDK WiFi quota usage
- (long) getWiFiQuotaUsage;
Deprecated
Get SDK mobile data quota limit
- (long) getMobileQuotaLimit;
Deprecated
Get SDK mobile data quota usage
- (long) getMobileQuotaUsage;
Deprecated
Get SDK disk quota limit
- (long) getDiskQuotaLimit;
Deprecated
Get SDK disk quota usage
- (long) getDiskQuotaUsage;
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;