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;

BDPointSDK

  • 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:] instead

    This 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:] instead

    Authenticate, 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 a BDPointSessionException 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:] instead

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

    Note

    BDPointSessionException Thrown if BDLocationManager is already logged out.

    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 both BDPSessionDelegate and BDPLocationDelegate

  • Deprecated

    First deprecated in 15.4.0 - Features migrated to bluedotServiceDelegate or geoTriggeringEventDelegate

    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 a BDPointSessionException 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 events

    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<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 valid BDZoneInfo “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:] 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

  • 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. 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 GeoTriggering features of the Bluedot Point SDK. Please refer to -[BDLocationManager startGeoTriggeringWithAppRestartNotificationTitle:notificationButtonText:completion:] if you wish to implement 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 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:] instead

    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:(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:] instead

    Stop Tempo Tracking

    Note

    BDPointSessionException thrown if PointSDK is not logged in.

    Declaration

    Objective-C

    - (void)stopTempoTracking;