SDK

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.

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:

tvos location privacy entry

Make sure you provide a text that best describes why and how you are going to use the user’s location. This text will be displayed to the user the first time you request the use of location services. Users are more likely to trust your app with location data if they understand why you need it.

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 right after a device registration:

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {

    [[NotificarePushLib shared] registerDevice:deviceToken completionHandler:^(NSDictionary *info) {

        ...more code

        //Device is regsitered, here it's safe to start requesting location services
        [[NotificarePushLib shared] startLocationUpdates];

        ...more code

    } errorHandler:^(NSError *error) {
        //Handle error
    }];

}
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    NotificarePushLib.shared().registerDevice(deviceToken, completionHandler: {(_ info: [AnyHashable: Any]) -> Void in

        ...more code

        //Device is regsitered, here it's safe to start requesting location services
        NotificarePushLib.shared().startLocationUpdates()

        ...more code

    }, errorHandler: {(_ error: Error?) -> Void in
        //Handle error
    })
}

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 request the user's location and register it. After that point you will be able to 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 send notifications based on location should be enough to create engaging experiences.

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] checkLocationUpdates]){
        NSLog(@"Location Services enabled: %@", status);
    }
}
func notificarePushLib(_ library: NotificarePushLib, didReceiveLocationServiceAuthorizationStatus status: [AnyHashable: Any]) {
    if NotificarePushLib.shared().checkLocationUpdates() {
        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 *)locations{
    //Handle locations
}
func notificarePushLib(_ library: NotificarePushLib, didUpdateLocations locations: [Any]) {
    //Handle locations
}