Engine  7.5.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) - stop
 
(void) - setBackgroundEnabled:
 
(void) - setVisitConfidence:
 
(enum VisitConfidence- getVisitConfidence
 
(void) - genPlaceCandidatesWithDelegate:
 
(void) - genPlaceCandidatesWithDelegate:mockLocation:
 
(void) - verifyPlacesFromCandidates:placeIds:
 
(void) - verifyPlacesFromCandidates:placeIds:userPlaces:appData:
 
(void) - registerActionWithId:listener:
 
(void) - registerActions:
 
(void) - unregisterActionWithId:
 
(nullable NSArray< NSString * > *) - getUnboundActionIds
 
(void) - registerCircumstance:
 
(void) - unregisterCircumstanceWithId:
 
(void) - enableCircumstanceWithId:
 
(void) - disableCircumstanceWithId:
 
(void) - runCircumstances
 
(void) - runCircumstancesWithMockLocation:
 
(void) - syncWithGarage
 
(void) - forceTelemetrySend
 
(nonnull NSString *) - getFactualDeviceId
 

Class Methods

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

Detailed Description

The main singleton for using Engine.

Method Documentation

◆ 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.

◆ 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.

◆ 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.

◆ getUnboundActionIds()

- (nullable NSArray<NSString *> *) getUnboundActionIds

◆ getVisitConfidence()

- (enum VisitConfidence) getVisitConfidence

Gets a parameter that increases some qualities of generated visits while decreasing others. There are three values of the enum VisitConfidence: LOW_CONFIDENCE (the default), MEDIUM_CONFIDENCE, and HIGH_CONFIDENCE. A higher confidence improves visit geolocation accuracy and increases detection precision (i.e. decreases false positive visits), but omits shorter-length visits and decreases detection recall (i.e. increases false negatives).

Returns
One of three VisitConfidence values: LOW_CONFIDENCE, MEDIUM_CONFIDENCE, and HIGH_CONFIDENCE. LOW_CONFIDENCE is the default state of Engine. A higher confidence improves visit geolocation accuracy and increases detection precision (i.e. decreases false positive visits), but omits shorter-length visits and decreases detection recall (i.e. increases false negatives).

◆ registerActions:()

- (void) registerActions: (nonnull NSDictionary< NSString *, id< FactualActionDelegate >> *)  actionMap

Registers FactualActionDelegates for the associated actionIds in the dictionary. When a circumstance is triggered, the FactualActionDelegate associated with circumstance's actionId will be called.

Parameters
actionMapA map of actionIds to FactualActionDelegates.

◆ registerActionWithId:listener:()

- (void) registerActionWithId: (nonnull NSString *)  actionId
listener: (nonnull id< FactualActionDelegate >)  listener 

Registers a FactualActionDelegate for a particular actionId. When a circumstance is triggered, the FactualActionDelegate associated with circumstance's actionId will be called.

Parameters
actionIdThe id of the action.
listenerThe FactualActionDelegate to be called when a circumstance with the associated actionId is triggered

◆ registerCircumstance:()

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

Registers a FactualCircumstance.

Parameters
circumstanceThe FactualCircumstance to register.

◆ runCircumstances()

- (void) runCircumstances

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

◆ runCircumstancesWithMockLocation:()

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

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

◆ sdkVersion()

+ (nonnull NSString *) sdkVersion

Returns the sdk's version string.

Returns
the sdk's version string

◆ 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.

◆ setVisitConfidence:()

- (void) setVisitConfidence: (enum VisitConfidence confidence

Sets a parameter that increases some qualities of generated visits while decreasing others. There are three values of the enum VisitConfidence: LOW_CONFIDENCE (the default), MEDIUM_CONFIDENCE, and HIGH_CONFIDENCE. A higher confidence improves visit geolocation accuracy and increases detection precision (i.e. decreases false positive visits), but omits shorter-length visits and decreases detection recall (i.e. increases false negatives).

Parameters
confidenceOne of three VisitConfidence values: LOW_CONFIDENCE, MEDIUM_CONFIDENCE, and HIGH_CONFIDENCE. LOW_CONFIDENCE is the default state of Engine. A higher confidence improves visit geolocation accuracy and increases detection precision (i.e. decreases false positive visits), but omits shorter-length visits and decreases detection recall (i.e. increases 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:actionMap:()

+ (void) startWithApiKey: (nonnull NSString *)  key
delegate: (nonnull id< FactualEngineDelegate >)  delegate
actionMap: (nullable NSDictionary< NSString *, id< FactualActionDelegate >> *)  actionMap 

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.
actionMapA map of action-ids to FactualActionDelegate objects.

◆ 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.

◆ startWithApiKey:delegate:userJourneyDelegate:actionMap:()

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

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.
actionMapA map of action-ids to FactualActionDelegate objects.

◆ 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.

◆ unregisterActionWithId:()

- (void) unregisterActionWithId: (nonnull NSString *)  actionId

Unregisters the FactualActionDelegate associated with the actionId. The action will no longer be called when a circumstance occurs.

Parameters
actionIdThe actionId of the FactualActionDelegate you'd to unregister.

◆ 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: