AGSFenceGeotrigger Class Reference

Description

An AGSGeotrigger that defines regions or fences to be monitored using an AGSGeotriggerMonitor.

You can monitor areas of interest with an AGSFenceGeotrigger, using spatial rules like enter or exit. This type of operation is also known as "Geofencing".

Three main components comprise an AGSFenceGeotrigger:

• The AGSGeotriggerFeed that is monitored for changes - usually the device location read from an AGSLocationDataSource.
• The AGSFenceRuleType that describes the check that is performed with the feed and fence data - for example, "enters within 50 meters of".
• The AGSFenceParameters that the feed data are evaluated against. For example, a set of polygon features representing areas of interest. The AGSFenceParameters can cover many features or graphics that are checked.

An AGSFenceGeotrigger can also take into account floors within buildings. If the feature table used to create the AGSFeatureFenceParameters is referenced by an AGSFeatureLayer that is AGSFloorAware, and the AGSLocationDataSource used to create the AGSGeotriggerFeed includes AGSLocationSourcePropertiesKeys::floor information, then fences will only be entered when they are intersected by an AGSLocation on the correct floor. If the fence or location data does not include valid floor information, the floor is ignored and the fence is entered when it is intersected by the location.

A floor aware feature layer or table must be part of an AGSGeoModel that includes a valid AGSGeoModelFloorDefinition. All layers and tables that are used by the floor definition are loaded when the AGSGeotriggerMonitor is started.

An AGSLocation can contain floor property as part of AGSLocation::additionalSourceProperties. This is populated automatically by AGSIndoorsLocationDataSource, or can be supplied as part of your own implementation.

Since

100.12

Inheritance diagram for AGSFenceGeotrigger:

Instance Methods
(instancetype)	- initWithFeed:ruleType:fenceParameters:
(instancetype)	- initWithFeed:ruleType:fenceParameters:messageExpression:name:

Class Methods
(instancetype)	+ fenceGeotriggerWithFeed:ruleType:fenceParameters:
(instancetype)	+ fenceGeotriggerWithFeed:ruleType:fenceParameters:messageExpression:name:

Properties
AGSFenceEnterExitSpatialRelationship	enterExitSpatialRelationship
AGSGeotriggerFeed *	feed
AGSFenceGeotriggerFeedAccuracyMode	feedAccuracyMode
AGSFenceParameters *	fenceParameters
NSString *	geotriggerID
AGSArcadeExpression *	messageExpression
NSString *	name
NSArray< NSString * > *	requestedActions
AGSFenceRuleType	ruleType

Method Documentation

fenceGeotriggerWithFeed:ruleType:fenceParameters:

+ (instancetype) fenceGeotriggerWithFeed:		(AGSGeotriggerFeed *)	feed
ruleType:		(AGSFenceRuleType)	ruleType
fenceParameters:		(AGSFenceParameters *)	fenceParameters

Instantiates an AGSFenceGeotrigger.

Parameters

feed	The AGSGeotriggerFeed that is monitored for changes.
ruleType	The AGSFenceRuleType that describes the check that will be performed upon the feed data.
fenceParameters	The AGSFenceParameters that will be evaluated.

Since

100.12

fenceGeotriggerWithFeed:ruleType:fenceParameters:messageExpression:name:

+ (instancetype) fenceGeotriggerWithFeed:		(AGSGeotriggerFeed *)	feed
ruleType:		(AGSFenceRuleType)	ruleType
fenceParameters:		(AGSFenceParameters *)	fenceParameters
messageExpression:		(nullable AGSArcadeExpression *)	messageExpression
name:		(NSString *)	name

Instantiates an AGSFenceGeotrigger with an expression and a name.

Parameters

feed	The AGSGeotriggerFeed that is monitored for changes.
ruleType	The AGSFenceRuleType that describes the check that will be performed upon the feed data.
fenceParameters	The AGSFenceParameters that will be evaluated.
messageExpression	The AGSArcadeExpression that will be evaluated to create an AGSGeotriggerNotificationInfo::message.
name	The name for the AGSFenceGeotrigger.

Since

100.12

initWithFeed:ruleType:fenceParameters:

- (instancetype) initWithFeed:		(AGSGeotriggerFeed *)	feed
ruleType:		(AGSFenceRuleType)	ruleType
fenceParameters:		(AGSFenceParameters *)	fenceParameters

Instantiates an AGSFenceGeotrigger.

Parameters

feed	The AGSGeotriggerFeed that is monitored for changes.
ruleType	The AGSFenceRuleType that describes the check that will be performed upon the feed data.
fenceParameters	The AGSFenceParameters that will be evaluated.

Since

100.12

initWithFeed:ruleType:fenceParameters:messageExpression:name:

- (instancetype) initWithFeed:		(AGSGeotriggerFeed *)	feed
ruleType:		(AGSFenceRuleType)	ruleType
fenceParameters:		(AGSFenceParameters *)	fenceParameters
messageExpression:		(nullable AGSArcadeExpression *)	messageExpression
name:		(NSString *)	name

Instantiates an AGSFenceGeotrigger with an expression and a name.

Parameters

feed	The AGSGeotriggerFeed that is monitored for changes.
ruleType	The AGSFenceRuleType that describes the check that will be performed upon the feed data.
fenceParameters	The AGSFenceParameters that will be evaluated.
messageExpression	The AGSArcadeExpression that will be evaluated to create an AGSGeotriggerNotificationInfo::message.
name	The name for the AGSFenceGeotrigger.

Since

100.12

Property Documentation

enterExitSpatialRelationship

- (AGSFenceEnterExitSpatialRelationship) enterExitSpatialRelationship

readwritenonatomicassign

The spatial relationship that determines whether a fence polygon has been entered or exited.

There are two spatial operations you can use to determine whether a feed entity has entered or exited a fence polygon.

Intersects: the feed geometry must intersect the fence polygon. Contains: the feed geometry must be contained by the fence polygon.

These operations determine whether a fence polygon has been entered, and also when it has been exited (the feed geometry no longer intersects or is no longer contained by the fence polygon). Because the contains condition is more strict that intersects (a geometry can intersect another geometry without being contained by it) it tends to result in fewer notifications when the two geometries are nearby. By using different combinations of these rules for enter and exit, you can control the likelihood that notifications will be sent.

Note that when the feed geometry is an AGSPoint, there is no difference between intersection and containment, so both options behave the same. When using an AGSLocationGeotriggerFeed, set AGSFenceGeotrigger::feedAccuracyMode to AGSFenceGeotriggerFeedAccuracyModeUseGeometryWithAccuracy in order to create a polygon geometry that accounts for the area of uncertainty around an AGSLocation::position. The default value is AGSFenceEnterExitSpatialRelationshipEnterIntersectsAndExitDoesNotIntersect.

Since

100.13

feed

- (AGSGeotriggerFeed*) feed

readnonatomicstronginherited

The AGSGeotriggerFeed that is monitored for changes.

You can construct an AGSLocationGeotriggerFeed from any AGSLocationDataSource. Typically, this shows the device location based on GPS, but can be any AGSLocationDataSource.

Since

100.12

feedAccuracyMode

- (AGSFenceGeotriggerFeedAccuracyMode) feedAccuracyMode

readwritenonatomicassign

Describes how an AGSFenceGeotrigger uses accuracy information from an AGSGeotriggerFeed.

This property controls how the accuracy information from an AGSGeotriggerFeed is used to provide the AGSGeometry for checking an AGSGeotrigger condition. In particular, you can choose how to use the AGSLocation::horizontalAccuracy property to reflect the uncertainty around a fixed AGSLocation::position. Due to various factors, GPS positions may be inaccurate, with AGSLocation::horizontalAccuracy representing a radius that defines the area containing the actual location. Spurious notifications may occur when the AGSLocation::position is inaccurate and is incorrectly reported as inside or outside of a fence. You can use the AGSLocation::horizontalAccuracy to account for that uncertainty.

This property is used in conjunction with AGSFenceGeotrigger::enterExitSpatialRelationship to affect when notifications are sent.

The default value is AGSFenceGeotriggerFeedAccuracyModeUseGeometry.

Note that you can also use an AGSArcadeExpression with the AGSLocationGeotriggerFeed::filter property to reject AGSLocation objects with a poor accuracy.

Since

100.13

fenceParameters

- (AGSFenceParameters*) fenceParameters

readnonatomicstrong

The AGSFenceParameters that will be evaluated.

For example, a set of polygon features representing areas of interest. The AGSFenceParameters can cover many features or graphics that will be checked.

There are three types of AGSFenceParameters:

• An AGSFeatureFenceParameters that is constructed from an AGSFeatureTable.
• An AGSGraphicFenceParameters that is constructed from an array of AGSGraphic objects.
• An AGSGraphicsOverlayFenceParameters that is constructed from an AGSGraphicsOverlay.

  Since

  100.12

geotriggerID

- (NSString*) geotriggerID

readnonatomiccopyinherited

A unique ID for the AGSGeotrigger.

Since

100.13

messageExpression

- (AGSArcadeExpression*) messageExpression

readwritenonatomicstronginherited

An AGSArcadeExpression that controls the notification details when an AGSGeotrigger is met.

The expression uses the Arcade language to generate notification information that can be:

• A string literal that is the same for all notifications relating to this AGSGeotrigger
• Information that is specific to the attributes of objects that met the AGSGeotrigger

The expression is evaluated whenever the AGSGeotrigger condition is met, in order to populate the AGSGeotriggerNotificationInfo::message property. Display this message to alert the user that the AGSGeotrigger condition has been met. Note that the expression cannot be changed when the AGSGeotriggerMonitor is running.

For example, with an AGSFenceGeotrigger, using the following expression:

"You have " + $fencenotificationtype + " " + $fencefeature.area_name

returns the AGSGeotriggerNotificationInfo::message "You have entered Area A", where "area_name" is an attribute field on the AGSFenceGeotriggerNotificationInfo::fenceGeoElement.

Optionally, the expression can return extra properties in addition to the message. For example, it could produce another string, suitable for logging to a database. To supply additional properties, write an arcade expression that evaluates to a dictionary of key value pairs.

• A value with the key "message" will populate the AGSGeotriggerNotificationInfo::message property.

• A value with the key "actions" will populate the AGSGeotriggerNotificationInfo::actions property.

• Any additional key value pairs are returned in the AGSGeotriggerNotificationInfo::messageProperties dictionary.

For example, the following expression results in an AGSGeotriggerNotificationInfo::message of: "Hello world" and an AGSGeotriggerNotificationInfo::actions list of either "startTracking" or "stopTracking":

var action = IIf($fencenotificationtype == 'enter', 'stopTracking', 'startTracking');
return {
  'message': 'Hello world',
  'actions': [ "showMessage", action ]
}

The AGSArcadeExpression must evaluate to either a string or a dictionary; see AGSArcadeExpression::returnType. Note that this property is an AGSArcadeExpression object, rather than a string.

The AGSArcadeExpression must evaluate to either a string or a dictionary - see AGSArcadeExpression::returnType.

For more information on the available profile variables and functions for creating the AGSGeotrigger::messageExpression, see the "Geotrigger Notification" profile at https://developers.arcgis.com/arcade/guide/profiles/.

Since

100.12

name

- (NSString*) name

readwritenonatomiccopyinherited

The name of the AGSGeotrigger.

Since

100.12

requestedActions

- (NSArray<NSString *>*) requestedActions

readwritenonatomiccopyinherited

An array of strings indicating the set of requested actions when a notification is delivered.

This property provides the full list of recommended actions that the AGSGeotrigger author intends to be taken. Note that there is no requirement to take any action when a notification is delivered, but these provide a way to understand the AGSGeotrigger author's intention. Use this property to:

• Display the expected behavior of an AGSGeotrigger to the user, prior to monitoring.
• Check that your app supports the expected actions for the AGSGeotrigger.

This list of strings is the full set of recommended actions for any notifications from this AGSGeotrigger. Individual AGSGeotriggerNotificationInfo events may include a subset of these actions. The specific actions for an individual notification event (for example, when a given fence is entered) are shown in AGSGeotriggerNotificationInfo::actions. To populate the array of actions for a notification, the AGSGeotrigger::messageExpression property must return a dictionary with the key "actions", and an array of action strings as the value.

The actions are simple strings, so you can use them to control any custom action you wish your app to perform.

Since

100.14

ruleType

- (AGSFenceRuleType) ruleType

readwritenonatomicassign

The AGSFenceRuleType that describes the check performed with the feed and fence data.

The rule controls the spatial query that will be used - for example "enter" or "exit".

Since

100.12