Engine  13.0.0
Factual's Engine SDK
Instance Methods | Class Methods | List of all members
FactualEngine Class Reference

#import <FactualEngine.h>

Inheritance diagram for FactualEngine:

Instance Methods

(void) - enableRemoteAnalytics
 
(void) - disableRemoteAnalytics
 
(BOOL) - isRemoteAnalyticsEnabled
 
(void) - enableActivityMonitoring
 
(void) - disableActivityMonitoring
 
(BOOL) - isActivityMonitoringEnabled
 
(void) - setAdId:
 
(void) - resetAdId
 
(void) - stop
 
(void) - setBackgroundEnabled:
 
(void) - setVisitSensitivity:
 
(enum VisitSensitivity- getVisitSensitivity
 
(void) - genPlaceCandidatesWithDelegate:
 
(void) - genPlaceCandidatesWithDelegate:mockLocation:
 
(void) - verifyPlacesFromCandidates:placeIds:
 
(void) - verifyPlacesFromCandidates:placeIds:userPlaces:appData:
 
(void) - registerCircumstance:
 
(void) - unregisterCircumstanceWithId:
 
(void) - enableCircumstanceWithId:
 
(void) - disableCircumstanceWithId:
 
(void) - runCircumstances
 
(void) - runCircumstancesWithMockLocation:
 
(void) - runCircumstancesWithInitiator:
 
(void) - runCircumstancesWithInitiator:mockLocation:
 
(void) - syncWithGarage
 
(void) - forceTelemetrySend
 
(nonnull NSString *) - getFactualDeviceId
 

Class Methods

(void) + startWithApiKey:delegate:
 
(void) + startWithApiKey:delegate:userJourneyDelegate:
 
(nonnull NSString *) + sdkVersion
 
(BOOL) + isEngineStarted
 

Detailed Description

The main singleton for using Engine.

Method Documentation

◆ disableActivityMonitoring()

- (void) disableActivityMonitoring

Disables activity monitoring. Activity monitoring is disabled by default.

◆ disableCircumstanceWithId:()

- (void) disableCircumstanceWithId: (nonnull NSString *)  circumstanceId

Disables circumstance monitoring for the particular circumstance. Circumstances are enabled by default.

Parameters
circumstanceIdThe id of the FactualCircumstance to disable.

◆ disableRemoteAnalytics()

- (void) disableRemoteAnalytics

Disables the sending of data to Factual to power remote analytics. Remote analytics is disabled by default.

◆ enableActivityMonitoring()

- (void) enableActivityMonitoring

Enables activity monitoring. Activity monitoring is disabled by default.

◆ enableCircumstanceWithId:()

- (void) enableCircumstanceWithId: (nonnull NSString *)  circumstanceId

Enables circumstance monitoring for the particular circumstance. Circumstances are enabled by default.

Parameters
circumstanceIdThe id of the FactualCircumstance to enable.

◆ enableRemoteAnalytics()

- (void) enableRemoteAnalytics

Enables the sending of data to Factual to power remote analytics. Remote analytics is disabled by default.

◆ forceTelemetrySend()

- (void) forceTelemetrySend

Forces telemetry to be sent to the telemetry server. The SDK must be started to call this. Success is notified by an info message stating "Forced telemetry send successful."

◆ genPlaceCandidatesWithDelegate:()

- (void) genPlaceCandidatesWithDelegate: (nonnull id< FactualPlacesDelegate >)  delegate

Starts an asynchronous request to get the list of Factual Places the user is either at or near. This function returns immediately. When the request is complete, FactualPlacesDelegate's placeCandidatesDidGenerate: function is called.

Parameters
delegateA FactualPlacesDelegate to receive place candidate callbacks.

◆ genPlaceCandidatesWithDelegate:mockLocation:()

- (void) genPlaceCandidatesWithDelegate: (nonnull id< FactualPlacesDelegate >)  delegate
mockLocation: (nonnull CLLocation *)  location 

Starts an asynchronous request to get the list of Factual Place's the user is either at or near. This function returns immediately. When the request is complete, FactualPlacesDelegate's placeCandidatesDidGenerate: function is called.

Parameters
delegateA FactualPlacesDelegate to receive place candidate callbacks.
locationA mock location at which to look for Factual Places.

◆ getFactualDeviceId()

- (nonnull NSString *) getFactualDeviceId

Gets Factual's identifier for the device. This will either be an ad-id, or instance specific UUID if the ad-id is not available.

Returns
The device's id.

◆ getVisitSensitivity()

- (enum VisitSensitivity) getVisitSensitivity

Gets a parameter that increases some qualities of generated visits while decreasing others. There are three values of the enum VisitSensitivity: RECALL_OPTIMIZED (the default), MEDIUM_RECALL, and PRECISION_OPTIMIZED. The non-default values improve visit geolocation accuracy and increase detection precision (i.e. decrease false positive visits), but omit shorter-length visits and decrease detection recall (i.e. increase false negatives).

Returns
One of three VisitSensitivity values: RECALL_OPTIMIZED, MEDIUM_RECALL, and PRECISION_OPTIMIZED. RECALL_OPTIMIZED is the default state of Engine. The non-default values improve visit geolocation accuracy and increase detection precision (i.e. decrease false positive visits), but omit shorter-length visits and decrease detection recall (i.e. increase false negatives).

◆ isActivityMonitoringEnabled()

- (BOOL) isActivityMonitoringEnabled

Returns whether activity monitoring is enabled.

Returns
whether activity monitoring is enabled.

◆ isEngineStarted()

+ (BOOL) isEngineStarted

Returns YES if Engine is started, NO otherwise.

Returns
YES if Engine is started, NO otherwise.

◆ isRemoteAnalyticsEnabled()

- (BOOL) isRemoteAnalyticsEnabled

Returns whether remote analytics is enabled (ie. whether data will be sent to Factual to power remote analytics).

Returns
Whether remote analytics is enabled.

◆ registerCircumstance:()

- (void) registerCircumstance: (nonnull FactualCircumstance *)  circumstance

Registers a FactualCircumstance.

Parameters
circumstanceThe FactualCircumstance to register.

◆ resetAdId()

- (void) resetAdId

Removes the ad-id from the SDK so that it is no longer associated with remote analytics. For example, this may be called when the user limits ad-tracking.

◆ runCircumstances()

- (void) runCircumstances

Begins an asynchronous call to check registered and enabled circumstances, at the current location. Checks only circumstances defined to trigger upon ingress at a visit. This should primarily be used for debugging.

◆ runCircumstancesWithInitiator:()

- (void) runCircumstancesWithInitiator: (enum CircumstanceInitiator initiator

Begins an asynchronous call to check registered and enabled circumstances, at the current location. This should primarily be used for debugging.

Parameters
initiatorOne of three CircumstanceInitiator values: ARRIVING, DEPARTING and IN_TRANSIT. ARRIVING limits the check to circumstances defined to trigger upon ingress at a visit. DEPARTING limits the check to those defined to trigger upon egress from a visit. IN_TRANSIT limits the check to those defined to trigger while the device is traveling between places, i.e. not visiting.

◆ runCircumstancesWithInitiator:mockLocation:()

- (void) runCircumstancesWithInitiator: (enum CircumstanceInitiator initiator
mockLocation: (nonnull CLLocation *)  location 

Begins an asynchronous call to check registered and enabled circumstances, at a mock location. This should primarily be used for debugging.

Parameters
initiatorOne of three CircumstanceInitiator values: ARRIVING, DEPARTING and IN_TRANSIT. ARRIVING limits the check to circumstances defined to trigger upon ingress at a visit. DEPARTING limits the check to those defined to trigger upon egress from a visit. IN_TRANSIT limits the check to those defined to trigger while the device is traveling between places, i.e. not visiting.

◆ runCircumstancesWithMockLocation:()

- (void) runCircumstancesWithMockLocation: (nonnull CLLocation *)  location

Begins an asynchronous call to check registered and enabled circumstances, at a mock location. Checks only circumstances defined to trigger upon ingress at a visit. This should primarily be used for debugging.

Parameters
locationThe mock location at which to check the circumstances.

◆ sdkVersion()

+ (nonnull NSString *) sdkVersion

Returns the sdk's version string.

Returns
the sdk's version string

◆ setAdId:()

- (void) setAdId: (nonnull NSString *)  adId

Sets the device's advertising-id in the SDK so that it will be associated with the remote analytics.

Parameters
adIdThe device's advertising-id

◆ setBackgroundEnabled:()

- (void) setBackgroundEnabled: (BOOL)  enabled

Enables or disables data collection in the background. By default, Engine will collect data and monitor for circumstances in the background if it has the appropriate permissions. To disable this feature, call this function with NO. To enable the feature call the function with YES.

Parameters
enabledYES if Engine should collect data and monitor for circumstances in the background. NO if Engine should do not. The default state of Engine is for this feature to be enabled.

◆ setVisitSensitivity:()

- (void) setVisitSensitivity: (enum VisitSensitivity sensitivity

Sets a parameter that increases some qualities of generated visits while decreasing others. There are three values of the enum VisitSensitivity: RECALL_OPTIMIZED (the default), MEDIUM_RECALL, and PRECISION_OPTIMIZED. The non-default values improve visit geolocation accuracy and increase detection precision (i.e. decrease false positive visits), but omit shorter-length visits and decrease detection recall (i.e. increase false negatives).

Parameters
sensitivityOne of three VisitSensitivity values: RECALL_OPTIMIZED, MEDIUM_RECALL, and PRECISION_OPTIMIZED. RECALL_OPTIMIZED is the default state of Engine. The non-default values improve visit geolocation accuracy and increase detection precision (i.e. decrease false positive visits), but omit shorter-length visits and decrease detection recall (i.e. increase false negatives).

◆ startWithApiKey:delegate:()

+ (void) startWithApiKey: (nonnull NSString *)  key
delegate: (nonnull id< FactualEngineDelegate >)  delegate 

Starts Engine asynchronously. Starting Engine loads configurations, starts sensor collection, and begins monitoring for circumstance occurrences. This function begins an asynchronous start task, and thus returns immediately. Once the entire start process is complete, the FactualEngineDelegate's engineDidStartWithInstance: will be called.

Parameters
keyA valid Factual api-key.
delegateA FactualEngineDelegate to receive Engine callbacks.

◆ startWithApiKey:delegate:userJourneyDelegate:()

+ (void) startWithApiKey: (nonnull NSString *)  key
delegate: (nonnull id< FactualEngineDelegate >)  delegate
userJourneyDelegate: (nullable id< UserJourneyDelegate >)  userJourneyDelegate 

Starts Engine asynchronously. Starting Engine loads configurations, starts sensor collection, and begins monitoring for circumstance occurrences. This function begins an asynchronous start task, and thus returns immediately. Once the entire start process is complete, the FactualEngineDelegate's engineDidStartWithInstance: will be called.

Parameters
keyA valid Factual api-key.
delegateA FactualEngineDelegate to receive Engine callbacks.
userJourneyDelegateA UserJourneyDelegate to receive user journey callbacks.

◆ stop()

- (void) stop

Stops Engine. Stopping Engine stops user journey monitoring, sensor collection, and circumstance monitoring. This function begins an asynchronous stop sequence, and thus returns immediately. Once the entire stop process is complete, the FactualEngineDelegate's engineDidStop function is called.

◆ syncWithGarage()

- (void) syncWithGarage

Requests an asynchronous on-demand sync with Garage. When the request is complete, the engineDidSyncWithGarage: callback will be called.

◆ unregisterCircumstanceWithId:()

- (void) unregisterCircumstanceWithId: (nonnull NSString *)  circumstanceId

Unregisters a FactualCircumstance.

Parameters
circumstanceIdThe id of the FactualCircumstance to unregister.

◆ verifyPlacesFromCandidates:placeIds:()

- (void) verifyPlacesFromCandidates: (nonnull PlaceCandidateResponse *)  candidates
placeIds: (nonnull NSArray< NSString * > *)  placeIds 

Allows the user to specify which place or places he/she is at. The placeIds list should include the place(s) in the PlaceCandidateResponse the user is at.

Parameters
candidatesThe PlaceCandidateResponse from a previous placeCandidatesDidGenerate: callback.
placeIdsThe place(s) in the PlaceCandidateResponse the user is at.

◆ verifyPlacesFromCandidates:placeIds:userPlaces:appData:()

- (void) verifyPlacesFromCandidates: (nonnull PlaceCandidateResponse *)  candidates
placeIds: (nonnull NSArray< NSString * > *)  placeIds
userPlaces: (nullable NSArray< NSString * > *)  userPlaces
appData: (nullable NSDictionary *)  appData 

Allows the user to specify which place or places he/she is at. The placeIds list should include the place(s) in the PlaceCandidateResponse the user is at.

Parameters
candidatesThe PlaceCandidateResponse from a previous placeCandidatesDidGenerate: callback.
placeIdsThe place(s) in the PlaceCandidateResponse the user is at.
userPlacesThe place(s) the user is at not in the PlaceCandidateResponse.
appDataAny json metadata attached to the verification.

The documentation for this class was generated from the following file: