Location Services

In this page you'll dive deeper into functionality like using GPS signals to get the user's location. These services will bring a new level of contextuality to your app, allowing you to send notifications based on location.

:markdown Tracking a user location in tvOS will require the user's authorization, this means that your app must declare usage description texts explaining why it needs to track location. In tvOS location can only be retrieved when your app is on the foreground, so you must include the NSLocationWhenInUseUsageDescription entry in your app's .plist file:

Location Updates

Location services can only be requested after a successful device registration. To make sure this happens correctly, the best place to request location services is in the following delegate method:

-(void)notificarePushLib:(NotificarePushLib *)library didRegisterDevice:(NotificareDevice *)device {
    [[NotificarePushLib shared] startLocationUpdates];
}

func notificarePushLib(_ library: NotificarePushLib, didRegister device: NotificareDevice) {
    NotificarePushLib.shared().startLocationUpdates()
}

The first time this is requested, it will prompt the user with a permission dialogue. If the user agrees to share location with your app, Notificare will automatically start monitoring significant location changes (roughly every 500m/1,640ft). It will also start monitoring for the nearest regions and beacons you might have created in our dashboard or API. This is basically all it takes to use location services, at this point you should be able to manage all your regions, geo-triggers, beacons and send geo-targeted notifications through our dashboard or API.

Location Services Delegates

In order for you to update your app's UI, react programmatically to location updates or any other custom implementation you might want to add, you should implement the following delegates. Please note that the implementation of these delegates is optional and simply using the dashboard or API to create interactions using location should be enough to create engaging experiences.

- (void)notificarePushLib:(NotificarePushLib *)library didReceiveLocationServiceAuthorizationStatus:(NSDictionary *)status{
    if([[NotificarePushLib shared] locationServicesEnabled]){
        NSLog(@"Location Services enabled: %@", status);
    }
}

func notificarePushLib(_ library: NotificarePushLib, didReceiveLocationServiceAuthorizationStatus status: [AnyHashable: Any]) {
    if NotificarePushLib.shared().locationServicesEnabled() {
        print("Location Services enabled: \(status)")
    }
}

This delegate will be triggered whenever you start tracking location. When this delegate is triggered, it is possible to request the authorization status for location services:

- (void)notificarePushLib:(NotificarePushLib *)library didReceiveLocationServiceAuthorizationStatus:(NSDictionary *)status{
    if([[NotificarePushLib shared] locationServicesEnabled]){
        NSLog(@"Location Services enabled: %@", status);
    }
}

func notificarePushLib(_ library: NotificarePushLib, didReceiveLocationServiceAuthorizationStatus status: [AnyHashable: Any]) {
    if NotificarePushLib.shared().locationServicesEnabled() {
        print("Location Services enabled: \(status)")
    }
}

The following delegate will be triggered if locations services could not be started. Typically you can use this delegate to retry again in case it's a network related error or find out why your app is incorrectly configured to use location services:

- (void)notificarePushLib:(NotificarePushLib *)library didFailToStartLocationServiceWithError:(NSError *)error{

    //Handle error

}

func notificarePushLib(_ library: NotificarePushLib, didFailToStartLocationServiceWithError error: Error?) {

    //Handle error

}

This following delegate will be called when location updates are received. It will contain an array of one or more CLLocation objects. This array always contains at least one object representing the current location. If updates were deferred or if multiple locations arrived before they could be delivered, the array may contain additional entries. The objects in the array are organized in the order in which they occurred. Therefore, the most recent location position is at the end of the array.

- (void)notificarePushLib:(NotificarePushLib *)library didUpdateLocations:(NSArray<NotificareLocation*> *)locations {
    //Handle Locations
}

func notificarePushLib(_ library: NotificarePushLib, didUpdateLocations locations: [NotificareLocation]) {
    //Handle Locations
}

Opt-out from Location Services

In our 2.2.0 release, we've added the possibility to opt-out from Notificare's Location Services. Since CLLocationManager is a singleton class shared by any implementation of location services in your app, Notificare will automatically receive location updates even when you implement this class yourself without invoking any of the methods above. To allow you to disable this behaviour we've added a new configuration property under OPTIONS in the Notificare.plist. It's called DISABLE_LOCATION_SERVICES and when present we will ignore any attempt to invoke the methods above as well as storing any location data.

Additionally, when using this new behaviour, you can also clear any location data previously stored for a device by using the following method:

[[NotificarePushLib shared] clearDeviceLocation:^(id  _Nullable response, NSError * _Nullable error) {

}];

NotificarePushLib.shared().clearDeviceLocation({(_ response: Any?, _ error: Error?) -> Void in

})