iOS Point SDK  15.2.0
BDLocationManager Class Reference

Entry-point for your Application's interaction with Point SDK. More...

#import <BDLocationManager.h>

+ Inheritance diagram for BDLocationManager:
+ Collaboration diagram for BDLocationManager:

Instance Methods

(void) - authenticateWithApiKey:
 
(void) - authenticateWithApiKey:requestAuthorization:
 
(void) - logOut
 
(void) - setPointDelegate:
 
(id< BDPAuthenticationDelegate > authenticationDelegate) - __attribute__
 
(void) - setZone:disableByApplication:
 
(BOOL) - isZoneDisabledByApplication:
 
(void) - applicationContainsDisabledZone:completion:
 
(NSString *) - installRef
 
(void) - notifyPushUpdateWithData:
 
(NSString *) - sdkVersion
 
(void) - setCustomEventMetaData:
 
(NSDictionary *) - customEventMetaData
 

Class Methods

(BDLocationManager *) + instance
 

Properties

CLAuthorizationStatus authorizationStatus
 
id< BDPLocationDelegatelocationDelegate
 
id< BDPSessionDelegatesessionDelegate
 
BDAuthenticationState authenticationState
 
NSSet * zoneInfos
 

Detailed Description

Entry-point for your Application's interaction with Point SDK.

Point SDK carries out location specific, conditional actions that you define in the Point Access web-interface. To start these behaviours with your Application, it is necessary only to call the authentication method on the shared singleton instance of BDLocationManager.

Calling the authentication method will start a session with Point Access. Upon success, Zones will be downloaded and associated actions will be executed by the library, without any further intervention.

In general, the shared, singleton instance of BDLocationManager should be used wherever the standard Core Location CLLocationManager class would have been used.

BDLocationManager is a subclass of CLLocationManager and is intended as a drop-in replacement while providing additional features.

BDLocationManager exposes two new delegate properties, in addition to the usual delegate property inherited from CLLocationManager:

  • sessionDelegate to which you should assign your own implementation of the BDPSessionDelegate protocol.
  • locationDelegate to which you should assign your own implementation of the BDPLocationDelegate protocol.

More fully, these features are:

Session Delegate

The BDPSessionDelegate protocol provides callbacks that inform the application of Point SDK's authentication state with it's supporting web-service. The rules defined in Point Access will only be observed while authenticated.

In addition, some methods of Point SDK classes may only be called while authenticated and will otherwise cause an exception to be thrown. Individual restrictions are documented clearly in this API reference. It is only necessary to authenticate once during the runtime of the application.

Location Delegate

Following the delegate pattern familiar throughout Apple's CocoaTouch frameworks, the locationDelegate property of BDLocationManager provides callbacks to notify your application when: Zone information is received. This typically occurs immediately after the authentication process completes. Any Custom Actions defined in the Point Access are triggered, in real-time.

Method Documentation

◆ __attribute__()

- (id<BDPAuthenticationDelegate> authenticationDelegate) __attribute__ ((deprecated("This has been superceded by BDPSessionDelegate and will be removed in a future release."))) 
Deprecated:
This has been superceded by BDPSessionDelegate and will be removed in a future release.

Provided by category BDLocationManager(BDPointSDK).

◆ applicationContainsDisabledZone:completion:()

- (void) applicationContainsDisabledZone: (NSString *)  zoneId
completion: (void(^)(BOOL))  completion 

Non-blocking method to determine if a user zone is in an enabled state.

Parameters
zoneIdzone UUID
completionclosure returns whenever zone is disabled or not

Provided by category BDLocationManager(BDPointSDK).

◆ authenticateWithApiKey:()

- (void) authenticateWithApiKey: ((deprecated("First deprecated in 1.14.0 - use method authenticateWithApiKey:requestAuthorization: instead")))  __attribute__

This method has been deprecated as of version 1.14.0; it will be removed in a future version.

Deprecated:
Use authenticateWithApiKey:requestAuthorization: (BDLocationManager(BDPointSDK))

Provided by category BDLocationManager(BDPointSDK).

◆ authenticateWithApiKey:requestAuthorization:()

- (void) authenticateWithApiKey: (NSString *)  apiKey
requestAuthorization: (BDAuthorizationLevel)  authorizationLevel 

Authenticate, and start a session with Point Access. This behaviour is asynchronous and this method will return immediately. Progress of the authentication process can be monitored by callbacks provided via the sessionDelegate property, or the KVO-enabled authenticationState property.

Location Services are required immediately after successful authentication.

It is the responsibility of the Application to respect the authentication life-cycle and ensure that BDLocationManager is not already Authenticated, or in the process of Authenticating, while calling this method.

Parameters
apiKeyAPI Key
authorizationLevelIt is mandatory to request authorization level during SDK authentication. Requesting with "authorizedAlways" option will show iOS location permission prompt with three options, "Always", "When in use" and "Never". Requesting with "authorizedWhenInUse" option will show iOS location permission prompt with two options, "When in use" and "Never".
Exceptions
BDPointSessionExceptionCalling this method while in an invalid state will result in a BDPointSessionException being thrown.

Provided by category BDLocationManager(BDPointSDK).

◆ customEventMetaData()

- (NSDictionary *) customEventMetaData

Returns the custom metadata set by calling setCustomEventMetaData.

Provided by category BDLocationManager(BDPointSDK).

◆ installRef()

- (NSString *) installRef

Returns the installation reference of this Point SDK enabled App. This is the same as the Install Ref that appears in a Zone's Activity Log in Point Access, or queried via Open API. This reference is randomly generated at the first run-time of the App and remains fixed for the duration of the App installation.

Provided by category BDLocationManager(BDPointSDK).

◆ instance()

+ (BDLocationManager *) instance
Returns
The singleton instance of BDLocationManager

◆ isZoneDisabledByApplication:()

- (BOOL) isZoneDisabledByApplication: ((deprecated("First deprecated in 1.13 - use method applicationContainsDisabledZone:completion: instead")))  __attribute__

Blocking method to determine if a user zone is in an enabled state.

Parameters
zoneIdzone UUID.
Returns
Returns whenever zone is disabled or not
Deprecated:
Use applicationContainsDisabledZone:completion: (BDLocationManager(BDPointSDK))

Provided by category BDLocationManager(BDPointSDK).

◆ logOut()

- (void) logOut

Immediately ends a currently active session with Point Access. According to the authentication lifecycle, this method should only be called when authenticationState is BDAuthenticationStateAuthenticated. Otherwise, a BDPointSessionException will be thrown.

Exceptions
BDPointSessionExceptionThrown if BDLocationManager is already logged out.

Provided by category BDLocationManager(BDPointSDK).

◆ notifyPushUpdateWithData:()

- (void) notifyPushUpdateWithData: (NSDictionary *)  data

Notifies Point SDK that the push notification has been received with given data.

Parameters
dataPush data passed through AppDelegate callback methods.

Provided by category BDLocationManager(BDPointSDK).

◆ sdkVersion()

- (NSString *) sdkVersion

Returns the version of the Point SDK as a NSString.

Provided by category BDLocationManager(BDPointSDK).

◆ setCustomEventMetaData:()

- (void) setCustomEventMetaData: (NSDictionary *)  data

Sets custom metadata for Notification events. The custom metadata set through this API will be available on the backend in checkin activity log and via webhooks. Only up to 20 custom meta data fields are allowed. Throws BDCustomEventMetadataCountException exception if the number of custom fields exceeded. Only String Type is allowed. Throws BDCustomEventMetadataDataFormatException exception if data contains non-String type.

Provided by category BDLocationManager(BDPointSDK).

◆ setPointDelegate:()

- (void) setPointDelegate: (id< BDPointDelegate >)  pointDelegate

Equivalent to setting locationDelegate and sessionDelegate

.

Parameters
pointDelegateObject implementing BDPointDelegate, equivalent to both BDPSessionDelegate and BDPLocationDelegate

Provided by category BDLocationManager(BDPointSDK).

◆ setZone:disableByApplication:()

- (void) setZone: (NSString *)  zoneId
disableByApplication: (BOOL)  disable 

Disabled or re-enable a specific zone. Information about valid zones, including their respective zoneId's for use in this method, is delivered to didUpdateZoneInfo: (BDPLocationDelegate-p).

Provided by category BDLocationManager(BDPointSDK).

Property Documentation

◆ authenticationState

- (BDAuthenticationState) authenticationState
readatomicassign

Read-only property, providing the current authentication authenticationState. This property is KVO compliant, meaning that it can be observed for changes with Key-Value Observing.

Provided by category BDLocationManager(BDPointSDK).

◆ authorizationStatus

- (CLAuthorizationStatus) authorizationStatus
readnonatomicassign

Key-Value Observable representation of the current, underlying CoreLocation authorization status for this Application.

◆ locationDelegate

- (id<BDPLocationDelegate>) locationDelegate
readwriteatomic

Provided by category BDLocationManager(BDPointSDK).

◆ sessionDelegate

- (id<BDPSessionDelegate>) sessionDelegate
readwriteatomic

Applications using Point SDK must authenticate before using its features.

Which classes and methods require authentication is set out clearly in the API documentation. Authentication is performed simply by calling authenticateWithApiKey: (BDLocationManager(BDPointSDK)) with the API credentials provided in your Point Access management portal.

Implement the callbacks in your own implementation of BDPSessionDelegate, and assign it to this property to receive feedback on the outcome of authentication, and to tell your application when it can start fully using Point SDK. Attempting to call protected features when not authenticated will case a BDPointSessionException to be thrown.

Provided by category BDLocationManager(BDPointSDK).

◆ zoneInfos

- (NSSet*) zoneInfos
readnonatomicassign

A collection of BDZoneInfo objects, corresponding to the Zones you created for this application, in the Point Access web-interface.

Provided by category BDLocationManager(BDPointSDK).