# Sentiance ### shared The Singleton instance to get the shared instance of the SDK. Usage: Sentiance.shared ```objectivec + (instancetype) shared; ``` ### sdkStatus Get SDK status information ```objectivec @property (nonatomic, readonly) SENTSDKStatus *sdkStatus; ``` ### initState Return state of initialisation of the SDK: SENTNotInitialized, SENTInitInProgress, SENTInitialized. ```objectivec @property (nonatomic, readonly) SENTSDKInitState initState; ``` ### detectionStatus Get current detection status. ```objectivec @property (nonatomic, readonly) SENTDetectionStatus detectionStatus; ``` ### userActivity SDK current user activity state. It is a trip or stationary with some enriched information. ```objectivec @property (nonatomic, readonly) SENTUserActivity * userActivity; ``` ### criteriaMaskForUserContextUpdates The criteria for which the delegate property `userContextDelegate` will get invoked. ```objectivec @property (nonatomic, assign) SENTUserContextUpdateCriteria criteriaMaskForUserContextUpdates; ``` ### userContextDelegate Delegate property which gets notified when the userContext is updated ```objectivec @property (nonatomic, weak) id _Nullable userContextDelegate ``` ### smartGeofenceEventsDelegate Delegate property which gets notified when Smart Geofence events are detected ```objectivec @property (nonatomic, weak) id _Nullable smartGeofenceEventsDelegate ``` ### version SDK Version property ```objectivec @property (nonatomic, readonly) NSString * version; ``` ### userId Returns the user ID. ```objectivec @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. ```objectivec @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. ```objectivec @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. ```objectivec @property (nonatomic, readonly) BOOL isVehicleCrashDetectionSupported; ``` ### wifiQuotaLimit SDK WiFi quota limit ```objectivec @property (nonatomic, readonly) long wifiQuotaLimit; ``` ### wifiQuotaUsage SDK WiFi quota usage ```objectivec @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; ``` ### drivingInsightsProcessedDelegate Sets a delegate that will be invoked when the driving insights for a completed transport becomes ready. Set `nil` to remove a previously set delegate. Note: setting or accessing this delegate on an uninitialized SDK will throw an NSException. ```objectivec @property (nonatomic, strong) id _Nullable drivingInsightsProcessedDelegate; ``` ### eventTimelineDelegate A delegate that will be invoked when the event timeline is updated. An update can be triggered by the start of a new event, and the update or end of an existing one. Every invocation will deliver an event that has a `lastUpdateDate` that is equal to or greater than the previously delivered event's `lastUpdateDate`. You can use this delegate along with [getTimelineUpdatesAfter:](#gettimelineupdatesafter) to stay up to date with the latest events in the timeline. For example, to make sure you don't miss out on timeline updates, you can first set this delegate, then follow up by calling [getTimelineUpdatesAfter:](#gettimelineupdatesafter) to query for potential updates since the last update you received. Note: setting or accessing this delegate on an uninitialized SDK will throw an NSException. ```objectivec @property (nonatomic, strong) id _Nullable eventTimelineDelegate; ``` ### allowedToUseMobileData Sets or returns whether the Sentiance SDK is allowed to use mobile data for uploading and downloading configuration and detection data. This setting applies to most types of data transfers done by the SDK, with the exception of a few lightweight data payloads. The setting is persisted across app restarts, but is reset to a default value of true when the SDK is reset. Note: setting or accessing this delegate on an uninitialized SDK will throw an NSException. ```objectivec @property (nonatomic) BOOL allowedToUseMobileData; ``` ### feedback Provides an API for submitting feedback on SDK detections. Returns `nil` if there is no Sentiance user. See [SENTFeedback](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/feedback/sentfeedback). Note: accessing this property on an uninitialized SDK will throw an NSException. ```swift var feedback: SENTFeedback? ``` ### tripLocations Provides an API for receiving locations during trips. Returns `nil` if there is no Sentiance user. See [TripLocations](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/triplocations). Note: accessing this property on an uninitialized SDK will throw an NSException. ```swift var tripLocations: TripLocations? ``` ### initWithConfig: success: failure: {% hint style="warning" %} **Deprecated** This method is deprecated. Use [initializeWithOptions: launchOptions:](#initializewithoptions-launchoptions) instead. {% endhint %} SDK initialization method. It sets up the modules internally and handles user authentication. ```objectivec - (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. | {% hint style="warning" %} Init should only be called once, unless initialization fails. {% endhint %} ### initializeWithOptions: launchOptions: Initializes the Sentiance SDK, thereby preparing it to resume detections if a Sentiance user exists and if detections were last enabled. If a user does not exist, this method does only minimal work to allow user creation. To create a user, call `createUserWithOptions:completionHandler:` To ensure proper continuity of SDK detections across app restarts, this method must be called on the main thread, inside AppDelegate's `application(_:didFinishLaunchingWithOptions:)` before it returns. This method 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](https://docs.sentiance.com/important-topics/sdk/appendix/sdk-initialization). This method returns [SENTInitializationResult](https://app.gitbook.com/s/-LTy4edu-AQHCZBbSxqI/sdk/api-reference/ios/sentinitializationresult). {% hint style="info" %} 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. {% endhint %} {% hint style="warning" %} 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. {% endhint %} ```objectivec - (SENTInitializationResult *)initializeWithOptions:(SENTOptions *)options launchOptions:(nullable NSDictionary *)launchOptions NS_SWIFT_NAME(initialize(options:launchOptions:)); ```
ParameterDescription
optionsthe SDK initialization options.
launchOptionsthe launch options obtained from application(_:didFinishLaunchingWithOptions:)s]
### initializeAsyncWithOptions: launchOptions: completionHandler: Asynchronously initializes the Sentiance SDK, thereby preparing it to resume detections if a Sentiance user exists and if detections were last enabled. If a user does not exist, this method does only minimal work to allow user creation. To create a user, call `createUserWithOptions:completionHandler:` This is the asynchronous variant of the initializeWithOptions:launchOptions: method. Use this variant if you want to minimize the impact of the SDK initialization on the startup duration of your app. However, note that interacting with most Sentiance SDK APIs requires an initialized SDK. Therefore, make sure to handle a delayed or failed initialization in other parts of your app, by utilizing the result returned to the completion handler. To ensure proper continuity of SDK detections across app restarts, this method must still be called on the main thread, inside AppDelegate's `application(_:didFinishLaunchingWithOptions:)` before it returns. This method 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](https://docs.sentiance.com/important-topics/sdk/appendix/sdk-initialization). The initialization result is returned to the completion handler. {% hint style="info" %} 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. {% endhint %} {% hint style="warning" %} 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. {% endhint %} ```objectivec - (void)initializeAsyncWithOptions:(SENTOptions *)options launchOptions:(nullable NSDictionary *)launchOptions completionHandler:(SENTAsyncInitializationCompletionHandler)completionHandler; ```
ParameterDescription
optionsthe SDK initialization options.
launchOptionsthe launch options obtained from application(_:didFinishLaunchingWithOptions:)
completionHandlerthe handler that will receive a SENTAsyncInitializationResult object if initialization succeeds, and a SENTAsyncInitializationError object if it fails. See SENTAsyncInitializationCompletionHandler.
### start: {% hint style="warning" %} **Deprecated** This method is deprecated. Use [enableDetectionsWithCompletionHandler: ](#enabledetectionswithcompletionhandler)instead. {% endhint %} Start the SDK. ```objectivec - (void)start:(void (^)(SENTSDKStatus* status))completion; ``` | Callback | | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **completion** | The completion block called when the SDK has started. [SENTSDKStatus](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/sentsdkstatus) object indicates any issue that occurred when the SDK started. | {% hint style="info" %} start should be called only after the SDK has been successfully initialized. {% endhint %} ### ### startWithStopDate: completion: {% hint style="warning" %} **Deprecated** This method is deprecated. Use [enableDetectionsWithExpiryDate: completionHandler:](#enabledetectionswithexpirydate-completionhandler) instead. {% endhint %} Start the SDK with expiration date. ```objectivec - (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](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/sentsdkstatus) object indicates any issue that occurred when the SDK started. | ### ### stop {% hint style="warning" %} **Deprecated** This method is deprecated. Use [disableDetectionsWithCompletionHandler: ](#disabledetectionswithcompletionhandler)instead. {% endhint %} Stop the SDK. ```objectivec - (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. Note: calling this method on an uninitialized SDK will throw an NSException. ``` - (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. ```objectivec - (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. ```objectivec - (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 - options or creating a user. See [SENTUserCreationOptions](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/user-creation-and-linking/user-creation/sentusercreationoptions). Throws: NSException if the SDK is not initialized. ```objectivec - (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. 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). {% hint style="info" %} 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. {% endhint %} **parameter:** [linker](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/user-creation-and-linking/user-linking/metauserlinker): the linker that the SDK will pass the installation ID to and execute success and failure closures according to result. **throws:** NSException if the SDK is not initialized. ```objectivec - (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. 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). {% hint style="info" %} 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. {% endhint %} **parameters:** authCode - a code obtained from the backend Sentiance API. **throws:** NSException if the SDK is not initialized. ```objectivec - (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. ```objectivec - (void)requestUserAccessTokenWithCompletionHandler: (SENTUserAccessTokenCompletionHandler)completionHandler; ``` ### requestUserContextWithCompletionHandler: Retrieves the user's current context. Events in the user context are final. The result is returned to the completion handler. See [SENTRequestUserContextCompletionHandler](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/user-context/sentrequestusercontextcompletionhandler). ```objectivec - (void)requestUserContextWithCompletionHandler:(SENTRequestUserContextCompletionHandler)completionHandler; ```
Parameters
completionHandler completion handler that will receive the SENTUserContext result. See SENTRequestUserContextCompletionHandler.
### requestUserContextIncludingProvisionalEvents:completionHandler: Retrieves the user's current context. The result is returned to the completion handler. See [SENTRequestUserContextCompletionHandler](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/user-context/sentrequestusercontextcompletionhandler). ```objectivec - (void)requestUserContextIncludingProvisionalEvents:(BOOL)includeProvisionalEvents completionHandler:(SENTRequestUserContextCompletionHandler)completionHandler; ```
Parameters
includeProvisionalEventsindicates whether the SENTUserContext result will include provisional events. To learn more about provisional events, see isProvisional.
completionHandlerthe completion handler that will receive the SENTUserContext result. See SENTRequestUserContextCompletionHandler.
### getUserId {% hint style="warning" %} **Deprecated** `getUserId` is deprecated. Use [userId](#userid) instead. {% endhint %} Returns the user ID ```objectivec - (NSString *) getUserId; ``` ### getUserAccessToken: {% hint style="warning" %} **Deprecated** `getUserAccessToken` is deprecated. Use [requestUserAccessToken](#requestuseraccesstokenwithcompletionhandler) instead. {% endhint %} Returns the users Access Token if the user is authenticated ```objectivec - (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. ```objectivec - (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. ```objectivec - (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. ```objectivec - (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. ```objectivec - (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 \null\. **throws:** NSException if the SDK is not initialized. ### startTrip: transportModeHint: success: failure: {% hint style="warning" %} **Deprecated** This method is deprecated. Use [startTripWithMetadata: transportModeHint: completionHandler:](#starttripwithmetadata-transportmodehint-completionhandler) instead. {% endhint %} Start a Trip manually ```objectivec - (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: {% hint style="warning" %} **Deprecated** **T**his method is deprecated. Use [stopTripWithCompletionHandler:](#stoptripwithcompletionhandler) instead. {% endhint %} Stop a trip. ```objectivec - (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. ```objectivec - (void) setTripTimeOutListener: (void (^)(void)) tripDidTimeOut; ``` {% hint style="info" %} **tripDidTimeOut** block will be called each time trip will time out {% endhint %} ### 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. ```objectivec - (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:`](#setvehiclecrashhandler)or [`setCrashListener:`](#setcrashlistener)depending on which handler was set last. ```objectivec - (void)invokeDummyVehicleCrash; ``` {% hint style="info" %} This method is intended for testing your integration, and not for production use. {% endhint %} ### setCrashListener: {% hint style="warning" %} **Deprecated** [`setCrashListener:`](#setcrashlistener) is deprecated. Use [`setVehicleCrashHandler:`](#setvehiclecrashhandler) instead. {% endhint %} Set vehicle crash detection block. ```objectivec - (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`](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/sentvehiclecrashevent). ```objectivec - (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. ```objectivec - (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. ```objectivec - (SENTUserActivity *)getUserActivity; ``` ### isTripOngoing: Interface method to check if trip is in progress or not. ```objectivec - (BOOL) isTripOngoing: (SENTTripType) tripType; ``` | Parameter | | | --------- | ------------------------------------------------------------------------------------- | | tripType | Type of ongoing trip, *SDK* - started by SDK, *External* - started by the application | ### submitDetections: failure: {% hint style="warning" %} **Deprecated** This method is deprecated. Use [submitDetectionsWithCompletionHandler:](#submitdetectionswithcompletionhandler) instead. {% endhint %} 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. ```objectivec - (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 {% hint style="warning" %} **Deprecated** This method is deprecated. Use [initState](#initstate) property instead. {% endhint %} Return state of inialization of the SDK: **SENTNotInitialized**, **SENTInitInProgress**, **SENTInitialized** ```objectivec - (SENTSDKInitState) getInitState; ``` ### ### getSdkStatus {% hint style="warning" %} **Deprecated** Use [sdkStatus](#sdkstatus) property instead. {% endhint %} Get SDK status information ```objectivec - (SENTSDKStatus*) getSdkStatus; ``` ### getVersion {% hint style="warning" %} **Deprecated** Use [version](#version) property instead. {% endhint %} Get SDK version ```objectivec - (NSString *) getVersion; ``` ### getWifiQuotaLimit {% hint style="warning" %} **Deprecated** Use [`wifiQuotaLimit:`](#wifiquotalimit) property instead. {% endhint %} Get SDK WiFi quota limit ```objectivec - (long) getWifiQuotaLimit; ``` ### getWiFiQuotaUsage {% hint style="warning" %} **Deprecated** Use [wifiQuotaUsage](#wifiquotausage) property instead. {% endhint %} Get SDK WiFi quota usage ```objectivec - (long) getWiFiQuotaUsage; ``` ### getMobileQuotaLimit {% hint style="warning" %} **Deprecated** Use [`mobileQuotaLimit`](#mobilequotalimit) instead. {% endhint %} Get SDK mobile data quota limit ```objectivec - (long) getMobileQuotaLimit; ``` ### getMobileQuotaUsage {% hint style="warning" %} **Deprecated** Use [mobileQuotaUsage](#mobilequotausage) instead. {% endhint %} Get SDK mobile data quota usage ```objectivec - (long) getMobileQuotaUsage; ``` ### getDiskQuotaLimit {% hint style="warning" %} **Deprecated** Use [diskQuotaLimit](#diskquotalimit) property instead. {% endhint %} Get SDK disk quota limit ```objectivec - (long) getDiskQuotaLimit; ``` ### getDiskQuotaUsage {% hint style="warning" %} **Deprecated** Use [diskQuotaUsage:](#diskquotausage) instead. {% endhint %} Get SDK disk quota usage ```objectivec - (long) getDiskQuotaUsage; ``` ### resetWithCompletionHandler: {% hint style="danger" %} The reset functionality is intended for removing all data in the device to handle a case such as a different user logging into an app, or a user requesting data deletion in the local app. It should not be used for disabling SDK detections, or for logging out a user (if the same user is expected to log in again in the near future). {% endhint %} 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
completionHandlera completion handler to receive the result of the reset operation.
```objectivec - (void)resetWithCompletionHandler: (nullable SENTResetCompletionHandler)completionHandler; ``` ### reset: failure: {% hint style="warning" %} **Deprecated** Use [resetWithCompletionHandler\*\*:\*\*](#resetwithcompletionhandler) instead. {% endhint %} {% hint style="info" %} The reset functionality is intended for removing all data in the device to handle a case such as a user logging out from an app or user requesting data deletion in the local app. It should not be used to reset the internal state of the SDK. {% endhint %} Resets the Sentiance SDK. Calling this method results in stopping of all SDK operations and deleting all SDK user data from the device. Additionally, the SDK will be uninitialized, allowing reinitialization and new Sentiance user creation. The reset operation may take a while, in which case the SDK's initialization state will be set to [InitState](https://docs.sentiance.com/important-topics/sdk/api-reference/sentsdkstatus#sentsdkinitstate) **SENTResetting** until it is complete. Calling any other SDK method during this time will either be ignored or return a default value. Note that calling this method during intermediate initialization states (i.e. [InitState ](https://docs.sentiance.com/important-topics/sdk/api-reference/sentsdkstatus#sentsdkinitstate)**SENTInitInProgress**} and [InitState](https://docs.sentiance.com/important-topics/sdk/api-reference/sentsdkstatus#sentsdkinitstate) **SENTResetting** will fail. ```objectivec - (void)reset:(void(^)(void))success failure:(void(^)(SENTResetFailureReason reason))failure; ``` | Parameter | | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | success | Success block callback when reset successfully done | | failure | Failure callback when with one of [SENTResetFailureReason](https://docs.sentiance.com/important-topics/sdk/api-reference/sentsdkstatus#sentresetfailurereason) happened | ### setDidReceiveSdkStatusUpdateHandler: Sets a handler that is invoked when the SDK's status is updated. ```objectivec - (void) setDidReceiveSdkStatusUpdateHandler:(void (^) (SENTSDKStatus * status))handler; ``` | Parameter | | | --------- | ------------------------------------------------------------------------------------- | | handler | a handler to receive SDK status updates, or nil to remove the previously set handler. | ### setVehicleCrashDiagnosticHandler: Sets a handler that is invoked when a vehicle crash diagnostic is detected.
Parameter
vehicleCrashDiagnosticHandlera handler to receive vehicle crash diagnostics of type SENTVehicleCrashDiagnostic
**throws:** NSException if the SDK is not initialized. ```objectivec - (void)setVehicleCrashDiagnosticHandler:(void (^)(SENTVehicleCrashDiagnostic *vehicleCrashDiagnostic))vehicleCrashDiagnosticHandler; ``` ### setTransmittableDataTypes: Set the data types that are allowed to be sent to the Sentiance Cloud Platform. This configuration is persistent across app restarts, but will be cleared upon SDK reset. **Note:** this configuration is not applicable to logging and diagnostic data that may get uploaded to the Sentiance Cloud Platform (if enabled for your app).
Parameter
transmittableDataTypesdata types of type SENTTransmittableDataType.
**throws:** NSException if the SDK is not initialized. ```objectivec - (void)setTransmittableDataTypes:(NSSet *)transmittableDataTypes NS_REFINED_FOR_SWIFT; ``` ### transmittableDataTypes Returns a set of [SENTTransmittableDataType](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/senttransmittabledatatype) data types that are allowed to be sent to the Sentiance Cloud Platform. **throws:** NSException if the SDK is not initialized. ```objectivec - (NSSet *)transmittableDataTypes NS_REFINED_FOR_SWIFT; ``` ### `enableTransportSessionRecording` Enables transport session recording. This setting is persistent across app restarts, so you only need to enable session recording once. Note however that the setting is reset to `disabled` after an SDK reset. See [reset](#resetwithcompletionhandler). Recorded sessions are stored on the device until the time that you request their deletion. See [`deleteTransportSession(String)`](#deletetransportsession). Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec - (void)enableTransportSessionRecording; ``` ### disableTransportSessionRecording Disables transport session recording. This setting is persistent across app restarts, so you only need to disable session recording once. If you no longer need session recording, make sure to delete previously recorded sessions if you no longer need them. See [`deleteAllTransportSessions()`](#deletealltransportsessions). Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec - (void)disableTransportSessionRecording; ``` ### getAvailableTransportSessions Returns a list of recorded and completed transport sessions. Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec - (NSArray *)getAvailableTransportSessions; ``` ### isTransportSessionRecordingEnabled Returns whether transport session recording is enabled. Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec - (BOOL)isTransportSessionRecordingEnabled; ``` ### setTransportSessionHandler: Sets a handler that will be invoked to deliver transport sessions. A session is delivered after a transport ends. Transport sessions are stored on the device until the time that you request their deletion. See [`deleteTransportSession(String)`](#deletetransportsession). Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec - (void)setTransportSessionHandler:(void (^)(SENTTransportSession *transportSession))transportSessionHandler; ```
Parameters
transportSessionHandlerA transportSessionHandler to receive transport sessions, or nil to remove a previously set handler.
### deleteAllTransportSessions Deletes all recorded transport sessions. Recorded sessions are stored on the device. It is your responsibility to call this method, or [`deleteTransportSession(String)`](#deletetransportsession), to request their deletion, when you no longer need them. Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec - (void)deleteAllTransportSessions; ``` ### deleteTransportSession: Deletes the transport session with the specified ID. Recorded sessions are stored on the device. It is your responsibility to call this method, or [`deleteAllTransportSessions`](#deletealltransportsessions), to request their deletion, when you no longer need them. Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec - (void)deleteTransportSession:(NSString *)sessionId NS_SWIFT_NAME(deleteTransportSession(sessionId:)); ```
Parameters
sessionIdThe ID of the session to delete.
### getDrivingInsightsForTransportId: Returns the [driving insights](https://github.com/sentiance/v4-docs/blob/main/sdk/api-reference/ios/broken-reference/README.md) for a given transport, or `nil` if there are no driving insights or the transport ID is invalid. Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec - (SENTDrivingInsights * _Nullable)getDrivingInsightsForTransportId:(NSString * _Nonnull)transportId; ```
Parameters
transportIdThe ID of the desired transport.
### getHarshDrivingEventsForTransportId: Returns the [harsh driving events](https://github.com/sentiance/v4-docs/blob/main/sdk/api-reference/ios/broken-reference/README.md) for a completed transport. Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec - (NSArray * _Nonnull)getHarshDrivingEventsForTransportId:(NSString * _Nonnull)transportId; ```
Parameters
transportIdThe ID of the desired transport.
### getPhoneUsageEventsForTransportId: Returns the [phone usage events](https://github.com/sentiance/v4-docs/blob/main/sdk/api-reference/ios/broken-reference/README.md) for a completed transport. Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec - (NSArray * _Nonnull)getPhoneUsageEventsForTransportId:(NSString * _Nonnull)transportId; ```
Parameters
transportIdThe ID of the desired transport.
### getCallEvents(forTransportId:) Returns the [call events](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/driving-insights/callevent) for a completed transport. Note: calling this method on an uninitialized SDK will throw an NSException. ```swift func getCallEvents(forTransportId transportId: String) -> [CallEvent] ```
Parameters
transportIdThe ID of the desired transport.
### getCallsWhileMovingEventsForTransportId: {% hint style="warning" %} This method was deprecated in v6.20.0 in favor of getCallEvents(forTransportId:) {% endhint %} Returns the [call while moving events](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/driving-insights/sentcallwhilemovingevent) events for a completed transport. Note: calling this method on an uninitialized SDK will throw an NSException. ``` - (NSArray * _Nonnull)getCallsWhileMovingEventsForTransportId:(NSString * _Nonnull)transportId; ```
Parameters
transportIdThe ID of the desired transport.
### getSpeedingEventsForTransportId: Returns the [speeding events](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/driving-insights/sentspeedingevent) for a completed transport. Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec - (NSArray * _Nonnull)getSpeedingEventsForTransportId:(NSString * _Nonnull)transportId; ```
Parameters
transportIdThe ID of the desired transport.
### getTimelineEventWithEventId: Returns the [timeline event](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/event-timeline/senttimelineevent) with the specified ID, or `nil` if no such event exists. Note: calling this method on an uninitialized SDK will throw an NSException. ```swift @objc func getTimelineEvent(withEventId eventId: String) -> SENTTimelineEvent? ```
Parameters
eventIdThe ID of the desired timeline event.
### getTimelineEventsFrom: to: Returns [timeline events](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/event-timeline/senttimelineevent), such as transport and stationary events, that were captured during the specified date range. The events are ordered from oldest to newest, and are not provisional (see [isProvisional](https://docs.sentiance.com/important-topics/sdk/api-reference/event-timeline/senttimelineevent#isprovisional)). Events that were captured outside of the specified date range are not returned, even if they were updated during this date range. To get all updates, regardless of when an event was captured, use [getTimelineUpdatesAfter:](#gettimelineupdates) instead. Note: calling this method on an uninitialized SDK will throw an NSException. ```swift @objc func getTimelineEvents(from dateFrom: Date, to dateTo: Date) -> [SENTTimelineEvent] ```
Parameters
dateFromThe start date of the date range. The specified date is inclusive.
dateToThe end date of the date range. The specified date is inclusive.
### getTimelineEventsIncludingProvisionalOnesFrom: to: Returns [timeline events](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/event-timeline/senttimelineevent), such as transport and stationary events, that were captured during the specified date range. The events are ordered from oldest to newest, and may include provisional ones (see [isProvisional](https://docs.sentiance.com/important-topics/sdk/api-reference/event-timeline/senttimelineevent#isprovisional)). Events that were captured outside of the specified date range are not returned, even if they were updated during this date range. To get all updates, regardless of when an event was captured, use [getTimelineUpdatesAfter:](#gettimelineupdates) instead. Note: calling this method on an uninitialized SDK will throw an NSException. ```swift @objc func getTimelineEventsIncludingProvisionalOnes( from dateFrom: Date, to dateTo: Date ) -> [SENTTimelineEvent] ```
Parameters
dateFromThe start date of the date range. The specified date is inclusive.
dateToThe end date of the date range. The specified date is inclusive.
### getTimelineUpdatesAfter: Returns all updated [events](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/event-timeline/senttimelineevent) in the event timeline after the specified date, sorted by the last update time. The events will not include provisional ones (see [isProvisional](https://docs.sentiance.com/important-topics/sdk/api-reference/event-timeline/senttimelineevent#isprovisional)). This method returns all events that started after the date, but it may also return events that started before the date, if they were updated afterwards. The returned result is not necessarily the complete list of events that were captured by the SDK from the result's first event until the last, because events that were not updated will be excluded. To get a complete and ordered list of events for a given date range, use [getTimelineEventsFrom:to:](#gettimelineevents) instead. You can use this method along with eventTimelineDelegate to stay up to date with the latest events in the timeline. For example, to make sure you don't miss out on timeline updates, you can first set the delegate, then follow up by using this method to query for potential updates since the last update you received. Note: calling this method on an uninitialized SDK will throw an NSException. ```swift @objc func getTimelineUpdates(after date: Date) -> [SENTTimelineEvent] ```
Parameters
dateThe date to retrieve updates from. The specified date is exclusive.
### getTimelineUpdatesIncludingProvisionalEventsAfter: Returns all updated [events ](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/event-timeline/senttimelineevent)in the event timeline after the specified date, sorted by the last update time. The events may include provisional ones (see [isProvisional](https://docs.sentiance.com/important-topics/sdk/api-reference/event-timeline/senttimelineevent#isprovisional)). This method returns all events that started after the date, but it may also return events that started before the date, if they were updated afterwards. The returned result is not necessarily the complete list of events that were captured by the SDK from the result's first event until the last, because events that were not updated will be excluded. To get a complete and ordered list of events for a given date range, use [getTimelineEventsFrom:to:](#gettimelineevents) instead. You can use this method along with eventTimelineDelegate to stay up to date with the latest events in the timeline. For example, to make sure you don't miss out on timeline updates, you can first set the delegate, then follow up by using this method to query for potential updates since the last update you received. Note: calling this method on an uninitialized SDK will throw an NSException. ```swift @objc func getTimelineUpdatesIncludingProvisionalEvents(after date: Date) -> [SENTTimelineEvent] ```
Parameters
dateThe date to retrieve updates from. The specified date is exclusive.
### smartGeofenceDetectionMode Returns the geofence entry/exit detection mode. See [SmartGeofenceDetectionMode](#smartgeofencedetectionmode). Note: calling this method on an uninitialized SDK will throw an NSException. ```swift @objc var smartGeofenceDetectionMode: SmartGeofenceDetectionMode ``` ### refreshSmartGeofencesWithCompletionHandler: Refreshes the list of geofences that the SDK monitors. The SDK obtains the list of geofences that it monitors from the Sentiance Cloud Platform, and refreshes it several times a day. Use this method to initiate a refresh, for instance, when you have created a new geofence directly on the Sentiance Platform, and want it to be immediately monitored by the SDK. Note that refresh requests are throttled to once every 30 seconds. Note: calling this method on an uninitialized SDK will throw an NSException. ```objectivec (void)refreshSmartGeofencesWithCompletionHandler:(SENTSmartGeofencesRefreshHandler)handler; ```
Parameters
handlerThe handler to to receive geofence refresh result / error. See SENTSmartGeofencesRefreshHandler.
### setTransportTags Sets the tags that will be assigned to a detected transport. The provided tags will be assigned to a transport at the moment the transport ends. When you receive a [SENTTransportEvent](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/event-timeline/senttimelineevent/senttransportevent) representing the ended transport, it will include these tags. The supplied tags are persisted and assigned to future transports, even after the app is restarted. By calling this method again, you will replace the tags that will be assigned to future transports. You can include up to 6 tags (key-value pairs), and each tag component (key or value) must be at most 256 characters. Do not include sensitive personal data in the tags. Throws: * **NSException** if the SDK is not initialized. * **NSError** with domain "SENTTransportTaggingDomain" if a Sentiance user does not exist, or if the supplied set of tags do not adhere to the maximum allowed tag count, or if a key/value component has more than the maximum allowed characters. ```swift func setTransportTags(_ tags: [String: String]) throws ```
Parameters
tagsThe tags that will be set.
### averageOverallSafetyScore Returns the average overall safety score for a given set of parameters, or `nil` if the score couldn't be calculated. Throws NSException if the SDK is not initialized. ```swift func averageOverallSafetyScore(_ params: SafetyScoreRequestParameters) -> Float? ```
Parameters
paramsThe parameters for which the score will be calculated. See SafetyScoreRequestParameters.
### getWrongWayDrivingEvents Returns the [wrong way driving events](https://docs.sentiance.com/important-topics/sdk/api-reference/ios/driving-insights/sentspeedingevent-1) for a completed transport. Throws NSException if the SDK is not initialized. ```swift func getWrongWayDrivingEvents(forTransportId transportId: String) -> [WrongWayDrivingEvent] ```
Parameters
transportIdThe ID of the desired transport.