BDLocationManager

@interface BDLocationManager : CLLocationManager

@brief 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 @ref BDLocationManager#instance “shared singleton instance” of @ref BDLocationManager.

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

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

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

@ref 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 @ref BDPSessionDelegate protocol.
  • locationDelegate to which you should assign your own implementation of the @ref BDPLocationDelegate protocol.

More fully, these features are:

Session Delegate

The @ref 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 @ref 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.

@copyright Bluedot Innovation

  • Declaration

    Objective-C

    + (BDLocationManager *)instance;

    Return Value

    The singleton instance of @ref BDLocationManager

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

    Declaration

    Objective-C

    @property (nonatomic, readonly) CLAuthorizationStatus authorizationStatus;

BDPointSDK

  • Deprecated

    First deprecated in 1.14.0 - use method authenticateWithApiKey:requestAuthorization: instead

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

    @deprecated Use @ref authenticateWithApiKey:requestAuthorization:

    Declaration

    Objective-C

    - (void)authenticateWithApiKey:(NSString *)apiKey;
  • 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 @ref BDLocationManager is not already Authenticated, or in the process of Authenticating, while calling this method.

    Declaration

    Objective-C

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

    Parameters

    apiKey

    API Key

    authorizationLevel

    It 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”. @exception BDPointSessionException Calling this method while in an invalid state will result in a @ref BDPointSessionException being thrown.

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

    @exception BDPointSessionException Thrown if @ref BDLocationManager is already logged out.

    Declaration

    Objective-C

    - (void)logOut;
  • Equivalent to setting locationDelegate and sessionDelegate

    .

    Declaration

    Objective-C

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

    Parameters

    pointDelegate

    Object implementing @ref BDPointDelegate, equivalent to both @ref BDPSessionDelegate and @ref BDPLocationDelegate

  • Undocumented

    Declaration

    Objective-C

    @property id<BDPLocationDelegate> locationDelegate
  • 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 BDLocationManager::authenticateWithApiKey: with the API credentials provided in your Point Access management portal.

    Implement the callbacks in your own implementation of @ref 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 @ref BDPointSessionException to be thrown.

    Declaration

    Objective-C

    @property id<BDPSessionDelegate> sessionDelegate;
  • Applications using Point SDK must authenticate before using its features. Attempting to call protected features when not authenticated will case a BDPointSessionException to be thrown.

    Declaration

    Objective-C

    @property id<BDPTempoTrackingDelegate> tempoTrackingDelegate;
  • 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.

    Declaration

    Objective-C

    @property id<BDPAuthenticationDelegate> authenticationDelegate;
  • 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.

    Declaration

    Objective-C

    @property (readonly) BDAuthenticationState authenticationState;
  • A collection of @ref BDZoneInfo objects, corresponding to the Zones you created for this application, in the Point Access web-interface.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSSet *zoneInfos;
  • Disabled or re-enable a specific @ref BDZoneInfo “zone”. Information about valid @ref BDZoneInfo “zones”, including their respective zoneId‘s for use in this method, is delivered to BDPLocationDelegate::didUpdateZoneInfo:.

    Declaration

    Objective-C

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

    First deprecated in 1.13 - use method applicationContainsDisabledZone:completion: instead

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

    Declaration

    Objective-C

    - (BOOL)isZoneDisabledByApplication:(NSString *)zoneId;

    Parameters

    zoneId

    zone UUID.

    Return Value

    Returns whenever zone is disabled or not @deprecated Use @ref applicationContainsDisabledZone:completion:

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

    Declaration

    Objective-C

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

    Parameters

    zoneId

    zone UUID

    completion

    closure returns whenever zone is disabled or not

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

    Declaration

    Objective-C

    - (NSString *)installRef;
  • Notifies Point SDK that the push notification has been received with given data.

    Declaration

    Objective-C

    - (void)notifyPushUpdateWithData:(NSDictionary *)data;

    Parameters

    data

    Push data passed through AppDelegate callback methods.

  • Returns the version of the Point SDK as a NSString.

    Declaration

    Objective-C

    - (NSString *)sdkVersion;
  • 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.

    Declaration

    Objective-C

    - (void)setCustomEventMetaData:(NSDictionary *)data;
  • Returns the custom metadata set by calling setCustomEventMetaData.

    Declaration

    Objective-C

    - (NSDictionary *)customEventMetaData;
  • Start Tempo Tracking for destination id provided

    Note

    BDPointSessionException thrown if PointSDK is not logged in.

    Note

    NSException with the name “BDTempoTrackingAlreadyStartedException” thrown if Tempo Tracking is currently already in progress

    Note

    NSException with the name “BDTempoDestinationIdEmptyException” thrown if destinationId is empty

    Declaration

    Objective-C

    - (void)startTempoTracking:(nonnull NSString *)destinationId;

    Parameters

    destinationId

    The destinationId to be tracked

  • Stop Tempo Tracking

    Note

    BDPointSessionException thrown if PointSDK is not logged in.

    Declaration

    Objective-C

    - (void)stopTempoTracking;