Introduction to Modules
The iOS SDK comprises four modules. Every integration requires the Core Module, and this integration is covered in this document.
The Core Module provides no functionality on its own, so you will need to integrate at least one of the three additional modules:
| IPS module | Required for any indoor positioning. Supports iBeacon format only. Can be used on its own, or combined with the CoreBluetooth module. |
| CoreBluetooth module | Used in addition to the IPS module to support Eddystone format beacons. Can only be used combined with the IPS module. |
| Geo Module | Required for any GPS positioning. Can be used on its own. |
Foreground vs Background usage
This guide enables positioning while the app is in foreground, for navigation. If you want to collect location data from phones while the app is running but doesn't have focus (in the background), then you will need to follow the additional steps in the Background Operation guide.
Adding the dependency
Cocaopods
Add the following dependencies to your Podfile:
pod 'CrowdConnectedCore', '1.4.0'
When integrating SDK 1.4.0 and above using CocoaPods, besides CrowdConnectedCore also add the following dependency in the Podfile:
pod 'AWSKinesis', '2.28.0’
Swift Package Manager (SPM)
Open your project in Xcode and navigate to File -> Swift Packages -> Add Package Dependency and one at a time the following packages:
https://github.com/crowdconnected/crowdconnected-core-ios
Carthage
In your Cartfile file add the following:
github "aws-amplify/aws-sdk-ios"
binary "https://crowdconnected-public-maven.s3.eu-west-1.amazonaws.com/iOSSources/crowdconnected-core-sources" == 1.3.0
binary "https://crowdconnected-public-maven.s3.eu-west-1.amazonaws.com/iOSSources/crowdconnected-shared-sources" == 1.3.0
Run the following command in terminal:
carthage update --use-xcframeworks --no-use-binaries
On your application targets’ General settings tab, in the Embedded Binaries section, drag and drop each xcframework you need to use from the Carthage/Build folder on disk. You will need:
AWSCognitoIdentityProvider.xcframework
AWSCognitoIdentityProviderASF.xcframework
AWSCore.xcframework
CrowdConnectedCore.xcframework
CrowdConnectedShared.xcframework
When integrating SDK version 1.4.0 and above using Carthage, in the Embedded Binaries section, besides the 5 frameworks above, also add:
AWSKinesis.xcframework
Capabilities
In your app's target inspector view, navigate to the Signing & Capabilities tab and add 'Access Wifi Information'.
Also, Location in Background Mode must be enabled from the project’s Capabilities section or by adding the following in the Info.plist file. Without this, the app may work in testing, but will crash as soon as the SDK is fully enabled OTA. Foregrounded only uses cases are supported using OTA configuration, but the following must still always be included in the project's capabilities.
<key>UIBackgroundModes</key>
<array>
<string>location</string>
</array>
Getting Permission
Location permission should be requested within your app onboarding process. It should be granted before starting the library.
This requires having the following location permission descriptor in the Info.plist file:
<key>NSLocationWhenInUseUsageDescription</key>
<string>YOUR DESCRIPTIVE TEXT HERE</string>
Request 'When In Use' location permission at an appropriate time, for instance when the user first opens a map:
class MyClass: NSObject {
let locationManager = CLLocationManager()
locationManager.requestWhenInUseAuthorization()
}
Starting the library
Using versions 1.1 and below: Make sure you never start the library without first having location permission. On every app start, check for location permission, and start the library only if it has been granted. And then whenever requesting location permission, start the library when it has successfully been granted.
From version 1.2.0, you can start the library (regardless of location permission) on every app start. The library will then listen for changes to location permission.
The library must be started and the completion called before other methods are called.
import CrowdConnectedCore
//Activate any other modules here
CrowdConnected.shared.start(appKey: "YOUR_APP_KEY", token: "YOUR_TOKEN", secret: "YOUR_SECRET") { deviceId, error in
// If the completion returns a non-nil Error, then the SDK has failed to start and is not functional.
// Otherwise, the completion will provide a valid device ID and a nil Error
}
SDK Status
The current status of the SDK can be verified using the two properties.
CrowdConnected.shared.isSuccessfullyRunning (Is `true` if the SDK has established a successful connection with the server and has started functionality. Is `false` otherwise)
CrowdConnected.shared.isNavigationRunning (Is `true` if the navigation feature is running. Is `false` otherwise).
App key, token and secret
When you start the library, you need an app key, a token and a secret. If you don't have an app key, you can register for a new account here.
Once you have an account, you can follow the Tokens guide to generate the token and secret.
Register the Position Callback
Create a location provider:
class LocationProvider: CrowdConnectedDelegate {
func didUpdateLocation(_ locations: [Location]) {
// Use the location updates here
}
}
Set the delegate for the SDK:
let locationProvider = LocationProvider()
CrowdConnected.shared.delegate = locationProvider
Remove the Position Callback
For stopping the location updates stream, either deinitialize the location provider object or reset the delegate as follows:
CrowdConnected.shared.delegate = nil
Navigation sessions
Navigation sessions provide GPS data at a higher rate. They can be started and ended when the app is in the foreground, providing navigation services.
This can be done by calling `CrowdConnected.shared.startNavigation()` and `CrowdConnected.shared.stopNavigation()`.
Stopping the library
Stop the library when the user navigates away from the map
CrowdConnected.shared.stop()