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 Canvas 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 Canvas.
Upon success, 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: - `BDLocationManager.sessionDelegate` - to which you should assign your own implementation of the `BDPSessionDelegate` protocol. The property provides callbacks that inform the application of Point SDK‘s authentication state with it’s supporting web-service. The rules defined in Canvas will only be observed while authenticated. - `BDLocationManager.locationDelegate` - to which you should assign your own implementation of the `BDPLocationDelegate` protocol. The property 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 Canvas are also triggered, in real-time. - `BDLocationManager.etaTrackingDelegate` - to which you should assign your own implementation of the `BDPEtaTrackingDelegate` protocol. This property provides callbacks to notify your application of Eta (Estimated time of arrival) related events.
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.
-
Declaration
Objective-C
+ (BDLocationManager *)instance;
Return Value
The singleton instance of
BDLocationManager
-
Key-Value Observable representation of the current, underlying CoreLocation authorization status for this Application.
Declaration
Objective-C
@property (nonatomic, readonly) CLAuthorizationStatus authorizationStatus;
-
Initialize Bluedot Point SDK with projectId.
Note
Bluedot SDK will not start triggering Geofeatures immediately after initialization as per previous API. You will have to make the call explicitly to start/stop Geo-triggering.
Note
Bluedot Point SDK no longer requests for OS location permission on authentication/initialization as per previous API.
We encourage you to request OS location permission that you requires (Always or When in Use), at an opportune moment from within your app, to get the best conversion rate. For example, when customer places an order within the mobile app, at this point you can start geotriggering, as well as requesting for location permission. To request for OS location permission, you can make the calls via our BDLocationManager Singleton, for example:
[BDLocationManager.instance requestAlwaysAuthorization]; [BDLocationManager.instance requestWhenInUseAuthorization];
Declaration
Objective-C
- (void)initializeWithProjectId:(NSString *_Nonnull)projectId completion: (void (^_Nonnull)(NSError *_Nullable))completion;
Parameters
projectId
The projectId to be initialised. You can find your projectId on Bluedot Canvas
completion
A mandatory completion handler called once processing completed. If the initialization is successful, error will be returned as nil. However, if the initilialization fails, an error will be provided.
-
Method to determine if Point SDK is initialized.
Declaration
Objective-C
- (BOOL)isInitialized;
Return Value
Returns whether Bluedot Point SDK is initialized or not
-
Reset Bluedot Point SDK (only if you wish to switch to a different projectId)
Call this method only if you need to switch to a different projectId, this will reset the Bluedot Point SDK to its original state. Upon completion callback, you can make the call
-initializeWithProjectId:completion:
to initialize with a different projectId.Declaration
Objective-C
- (void)resetWithCompletion:(void (^_Nonnull)(NSError *_Nullable))completion;
Parameters
completion
A mandatory completion handler called once processing completed. If the initialization is successful, error will be returned as nil. However, if the initilialization fails, an error will be provided.
-
Deprecated
First deprecated in 1.14.0 - use method
-[BDLocationManager initializeWithProjectId:completion:]
insteadThis method has been deprecated as of version 1.14.0; it will be removed in a future version.
Declaration
Objective-C
- (void)authenticateWithApiKey:(NSString *)apiKey;
-
Deprecated
First deprecated in 15.4.0 - use method
-[BDLocationManager initializeWithProjectId:completion:]
insteadAuthenticate, and start a session with Canvas. 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.Note
BDPointSessionException
Calling this method while in an invalid state will result in aBDPointSessionException
being thrown.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”.
-
Deprecated
First deprecated in 15.4.0 - use method
-[BDLocationManager resetWithCompletion:]
insteadImmediately ends a currently active session with Canvas. According to the authentication lifecycle, this method should only be called when authenticationState is
BDAuthenticationStateAuthenticated
. Otherwise, aBDPointSessionException
will be thrown.Declaration
Objective-C
- (void)logOut;
-
Deprecated
First deprecated in 15.4.0 - Please implement individual delegates separately
Equivalent to setting locationDelegate and sessionDelegate.
Declaration
Objective-C
- (void)setPointDelegate:(id<BDPointDelegate>)pointDelegate;
Parameters
pointDelegate
Object implementing
BDPointDelegate
, equivalent to bothBDPSessionDelegate
andBDPLocationDelegate
-
Deprecated
First deprecated in 15.4.0 - Features migrated to
bluedotServiceDelegate
orgeoTriggeringEventDelegate
Undocumented
Declaration
Objective-C
@property id<BDPLocationDelegate> locationDelegate
-
Deprecated
First deprecated in 15.4.0 - initialization related delegate callbacks are now returned in completion callbacks. Please refer to
-[BDLocationManager initialize:completion:]
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:requestAuthorization:]
with the API credentials provided in your Canvas 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 aBDPointSessionException
to be thrown.Declaration
Objective-C
@property id<BDPSessionDelegate> sessionDelegate;
-
Implement the callbacks in your own implementation of
BDPTempoTrackingDelegate
, and assign it to this property to receive Tempo related eventsApplications using Point SDK must initialize before using its features. Attempting to call protected features when not initialized will case a
BDPointSessionException
to be thrown.Declaration
Objective-C
@property id<BDPTempoTrackingDelegate> tempoTrackingDelegate;
-
Implement the callbacks in your own implementation of
BDPBluedotServiceDelegate
, and assign it to this property to receive bluedot service related callbacks (for e.g. location permission changed, accuracy authorization changed, e.t.c.Applications using Point SDK must initialize before using its features. Attempting to call protected features when not initialized will case a
BDPointSessionException
to be thrown.Declaration
Objective-C
@property id<BDPBluedotServiceDelegate> _Nullable bluedotServiceDelegate;
-
Implement the callbacks in your own implementation of
BDPGeoTriggeringEventDelegate
, and assign it to this property to receive Geotriggering e related callbacks (for e.g. zone updates, fence checkin e.t.c.)Applications using Point SDK must initialize before using its features. Attempting to call protected features when not initialized will case a
BDPointSessionException
to be thrown.Declaration
Objective-C
@property id<BDPGeoTriggeringEventDelegate> _Nullable geoTriggeringEventDelegate;
-
Deprecated
First deprecated in 1.14.0 - initialization related delegate callbacks are now returned in completion callbacks. Please refer to
-[BDLocationManager initialize:completion:]
This method has been deprecated as of version 1.14.0; it will be removed in a future version.
Declaration
Objective-C
@property id<BDPAuthenticationDelegate> authenticationDelegate;
-
Deprecated
First deprecated in 15.4.0 - This will be removed in future version. To check if Point SDK is initialized, please refer to
-[BDLocationManager isInitialized]
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
BDZoneInfo
objects, corresponding to the Zones you created for this project, in the Canvas web-interface.Declaration
Objective-C
@property (nonatomic, readonly) NSSet *zoneInfos;
-
Disabled or re-enable a specific
BDZoneInfo
“zone”. Information about validBDZoneInfo
“zones”, including their respective zoneId‘s for use in this method, is delivered to-[BDPGeoTriggeringEventDelegate onZoneInfoUpdate:]
.Declaration
Objective-C
- (void)setZone:(NSString *)zoneId disableByApplication:(BOOL)disable;
-
Deprecated
First deprecated in 1.13 - use method
-[BDLocationManager applicationContainsDisabledZone:completion:]
insteadBlocking 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
-
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 Canvas, 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. ThrowsBDCustomEventMetadataDataFormatException
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 GeoTriggering features of the Bluedot Point SDK. Please refer to
-[BDLocationManager startGeoTriggeringWithAppRestartNotificationTitle:notificationButtonText:completion:]
if you wish to implement App Restart FeatureNote
You can start Geo-triggering feature only while your App is in the Foreground.Note
An error will be returned if your App does not have either Always or When In Use location permission.Declaration
Objective-C
- (void)startGeoTriggeringWithCompletion: (void (^_Nonnull)(NSError *_Nullable))completion;
Parameters
completion
A mandatory completion handler called once Start GeoTriggering processing completed. If the GeoTriggering feature is started successful, error will be returned as nil. However, if the Start GeoTriggering feature fails, an error will be provided.
-
Start GeoTriggering features of the Bluedot Point SDK with App Restart feature. Note that Always location permission is required for the App Restart feature.
Note
You can start Geo-triggering feature only while your App is in the Foreground.Note
An error will be returned if your App does not have Always location permission.Note
An error will be returned if notification permission is not granted.Declaration
Objective-C
- (void) startGeoTriggeringWithAppRestartNotificationTitle: (NSString *_Nonnull)notificationTitle notificationButtonText: (NSString *_Nonnull)notificationButtonText completion:(void (^_Nonnull)( NSError *_Nullable)) completion;
Parameters
notificationTitle
the string to be used in the title of the banner or alert to be used in the local notification to restart the app.
notificationButtonText
the string to be used in the text of the action button to be used in the local notification to restart the app.
completion
A mandatory completion handler called once Start GeoTriggering processing completed. If the GeoTriggering feature is started successful, error will be returned as nil. However, if the Start GeoTriggering feature fails, an error will be provided.
-
Method to determine if GeoTriggering is running
Declaration
Objective-C
- (BOOL)isGeoTriggeringRunning;
Return Value
Returns whether GeoTriggering is running
-
Stop GeoTriggering features of the Bluedot Point SDK
Note
Stopping Geo-triggering feature has the intended effect of stopping location services on the device, thereby conserving battery on your user’s device unless another feature such as Tempo, is active.Declaration
Objective-C
- (void)stopGeoTriggeringWithCompletion: (void (^_Nullable)(NSError *_Nullable))completion;
Parameters
completion
A mandatory completion handler called once Stop Geotriggering processing completed. If the Geotriggering feature is stopped successful, error will be returned as nil. However, if the Stop Geotriggering fails, an error will be provided.
-
Start Tempo Tracking for destination id provided
Note
An error will be returned if your App does not have Always location permission.Declaration
Objective-C
- (void)startTempoTrackingWithDestinationId:(NSString *_Nonnull)destinationId completion:(void (^_Nonnull)( NSError *_Nullable))completion;
Parameters
destinationId
The destinationId to be tracked
completion
A mandatory completion handler called once Start Tempo processing completed. If the Tempo is started successful, error will be returned as nil. However, if the Start Tempo fails, an error will be provided.
-
Deprecated
First deprecated in 15.4.0 - use method
-[BDLocationManager startTempoTrackingWithDestinationId:completion:]
insteadStart 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 progressNote
NSException with the name “BDTempoDestinationIdEmptyException” thrown if destinationId is emptyDeclaration
Objective-C
- (void)startTempoTracking:(NSString *_Nonnull)destinationId;
Parameters
destinationId
The destinationId to be tracked
-
Stop Tempo Tracking
Declaration
Objective-C
- (void)stopTempoTrackingWithCompletion: (void (^_Nonnull)(NSError *_Nullable))completion;
Parameters
completion
A mandatory completion handler called once Stop Tempo processing completed. If the Tempo is stopped successful, error will be returned as nil. However, if the Start Tempo fails, an error will be provided.
-
Method to determine if Tempo is running
Declaration
Objective-C
- (BOOL)isTempoRunning;
Return Value
Returns whether Tempo is running
-
Deprecated
First deprecated in 15.4.0 - use method
-[BDLocationManager stopTempoTrackingWithCompletion:]
insteadStop Tempo Tracking
Note
BDPointSessionException
thrown if PointSDK is not logged in.Declaration
Objective-C
- (void)stopTempoTracking;