Location

The SDK uses iOS location services to collect significant location changes in the foreground and background. The host application must declare the purpose of location access, enable the required capability, and decide when to enable or explicitly disable collection according to its own business, consent, and privacy flows.

Integration Model

The intended integration is to call startLocation() once when the host application enables location collection. After activation, iOS and the Digital Reef SDK manage location events automatically; the client does not need to call the method periodically.

stopLocation() is not part of a recurring start → stop → start → stop cycle. Call it only when the host application's own flow or policies require Digital Reef to stop collecting location data.

SDK initialized → startLocation() once → automatic significant-location monitoring
                                             └─ stopLocation() only when the host app decides to disable collection

1. Add Location Permissions

Add the following keys to the host application's Info.plist. Replace the example text with a clear explanation of how location data is actually used:

<key>NSLocationWhenInUseUsageDescription</key>
<string>[Explain the benefit of using location while the application is in use]</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>[Explain why location access is also required in the background]</string>

❗
Location Permission Messages
These messages must describe the actual use of the data and comply with the application's privacy and consent policies. iOS cannot properly process an authorization request when the required keys are missing.

2. Enable Background Location

In the host application's main target, open Signing & Capabilities, add Background Modes, and select Location updates.

The equivalent Info.plist configuration is:

<key>UIBackgroundModes</key>
<array>
    <string>location</string>
</array>

3. Enable Location Collection

Call startLocation() once when the host application flow enables location collection. The client is responsible for determining the appropriate activation point according to its functional, legal, and consent requirements.

This method requests permanent (Always) authorization when necessary and registers significant-location-change monitoring. After it is enabled, Core Location delivers events automatically according to device movement and iOS system conditions. Do not invoke startLocation() on a timer or before every expected sample.

Swift

import DigitalReefSDK

DigitalReef.shared.startLocation()

#import <DigitalReefSDK/DigitalReefSDK.h>

[[DigitalReef shared] startLocation];

❗
Manual Initialization
Only when the Digital Reef configuration uses manual initialization (manualInitialization = true), the host application must call setUp() before startLocation(). With automatic initialization, call startLocation() directly.

❗
iOS Authorization
The host application controls when it asks the SDK to start collecting location data, but iOS controls the permission prompt and the access level that is ultimately granted. The client must not assume that calling startLocation() means authorization was granted.

Significant Location Changes

startLocation() does not request an immediate location or keep GPS continuously active. Therefore, the location icon may not remain visible, and a new sample may not appear while the device remains near the last stored location.

4. Disable Location Collection

Call stopLocation() only when the host application intentionally decides to disable Digital Reef location collection. Examples include a change in an application-specific setting or a business, consent, or privacy rule that requires collection to end.

The client does not need to call stopLocation() after a location is received or after a fixed period. If the host application does not have a flow that disables collection, this method does not need to be called.

The SDK stops monitoring and internally stores the collection state as disabled.

Swift

DigitalReef.shared.stopLocation()

[[DigitalReef shared] stopLocation];

❗
Stop Location
This method does not revoke the permission granted by iOS or immediately delete locations already stored by the SDK. It stops location collection managed by Digital Reef. If the host application later makes an explicit decision to enable collection again, call startLocation() once more.