Getting Started with the iOS SDK

The Moonsense iOS SDK is designed to make integrating Moonsense into your iOS application or SDK as easy as possible. The SDK is managed as a Swift Package and only requires a Public Token for your app from the Moonsense Console to get started.

The sections below will walk you through configuring access to download and integrate the SDK, initializing the SDK, and recording a session.

Integrating the SDK

The Moonsense iOS SDK is available as two variants: a dynamically linked .xcframework and a statically linked .xcframework.

MoonsenseSDK.xcframework

The MoonsenseSDK.xcframework contains the dynamically linked variant of the Moonsense iOS SDK. When using the dynamically linked variant of the SDK, you must embed the framework within your target so the OS can load it at runtime. This approach works fine if you are building an application that directly consumes the SDK or are building your own framework that is being used internally. If you are building a framework that you are providing to another party and you don't wish for them to see that your framework depends on the Moonsense iOS SDK, see the MoonsenseSDK-static.xcframework section below.

MoonsenseSDK-static.xcframework

The MoonsenseSDK-static.xcframework contains the statically linked variant of the Moonsense iOS SDK. When using the statically linked variant of the SDK, the linker will embed the necessary code from the SDK into your target. The Moonsense-static.xcframework should NOT be embedded into your target. If you are building a framework that you are providing to another party, they will only see your public API and not the Moonsense iOS SDK public API.

Configuring .netrc for Authorizing Downloads

Downloading the Moonsense iOS SDK artifacts requires a REPO_ACCESS_TOKEN for dl.moonsense.io. This token is associated to your Moonsense Account and should have been provided to you. In case you do not have one contact support@moonsense.io. Add the following to your ~/.netrc file:

machine dl.moonsense.io login token password <REPO_ACCESS_TOKEN> protocol https

Swift Package Manager

The Moonsense iOS SDK is available as a Swift Package. Simply use the the link to the moonsense-ios-sdk repo, https://github.com/moonsense/moonsense-ios-sdk, as the Package URL when adding the Swift Package to your project.

Cocoapods

Cocoapods distribution is not currently available but will be supported in an upcoming release.

Manual Integration

The MoonsenseSDK.xcframework.zip, MoonsenseSDK-static.xcframework.zip and MoonsenseSDK.doccarchive.zip artifacts can also be manually integrated into your project. You can download the latest versions from the following links:

Once downloaded, unzip the files and drop the expanded files into your project.

Note: The downloads require the authorization token as outlined above. For best results download the artifacts using curl with the -n option. For example:

curl -n -o MoonsenseSDK.xcframework.zip "https://dl.moonsense.io/basic/sdk/raw/names/\ MoonsenseSDK.xcframework/versions/0.1.0/MoonsenseSDK.xcframework.zip"

Usage

The SDK requires some configuration information to be setup and associate correctly with your app. To continue, you will need to create a publicToken for you app on the Moonsense Console.

In order to obtain a token you need to:

  • Have a valid Moonsense account.
  • Set up a project for the SDK to use. The default can be used in case you do not want to create one.
  • Configure an application for the SDK to record to.
  • Once the app is set up, use the Create token button to obtain the secret and public token to use. The SDK requires the public token as a part of the initialize(publicToken:delegate:) invocation. You can hold on to the secret token to read from the Moonsense Cloud later.

Initialization

The SDK needs to be initialized before it can be used. Call the Moonsense.initialize(publicToken:delegate:) method prior to recording. The initialize(publicToken:delegate:) method also accepts an optional MoonsenseDelegate to receive events from the SDK. For example:

import MoonsenseSDK class ViewController: UIViewController { let publicToken = "<YOUR_TOKEN_HERE>" ... override func viewDidLoad() { super.viewDidLoad() ... Moonsense.initialize(publicToken: publicToken, delegate: self) } } extension ViewController: MoonsenseDelegate { func didStartSession(_ session: Session) { // Called each time a session has started } func didStopSession(_ session: Session) { // Called each time a session has stopped } func errorDidOccur(error: MoonsenseError) { // Called each time the Moonsense SDK experiences an error print("Moonsense Error occurred: \(error.localizedDescription)") } }

Recording

The SDK records in Sessions. A Session is defined as a single start and stop point in time. Once the SDK initialized you can use the startSession() and stopAllSessions() methods to start and stop recording sessions respectively. If you need finer control over stopping individual sessions, the startSession() call returns a Session object that includes a stopSession() method. For example:

import MoonsenseSDK class ViewController: UIViewController { var session: Session? ... @IBAction func startSession(_ sender: Any) { session = try? Moonsense.startSession(duration: 30, labels: ["SampleApp"]) } @IBAction func stopAllSessions(_ sender: Any) { Moonsense.stopAllSessions() } @IBAction func stopLastSession(_ sender: Any) { if let session = session { session.stopSession() session = nil } } }

Sample Applications

The moonsense-ios-sdk GitHub repository contains sample applications and a sample SDK that demonstrate the integration and use of the Moonsense iOS SDK. To get started, open the MoonsenseSamples.xcworkspace Xcode Workspace.

  • SampleApp - This sample app demonstrates the use of the Moonsense iOS SDK within a simple application. The example in this case is quite simple and minimal and can serve as a good starting point for developers looking for a quick integration. The SampleApp Xcode project contains two targets, SampleApp and SampleApp-Static. The SampleApp target consumes the MoonsenseSDK.xcframework dynamically linked variant. The SampleApp-Static target consumes the MoonsenseSDK-static.xcframework target.
  • SamplePaymentApp - This sample app demonstrates the library usage of the Moonsense iOS SDK. Note that the SamplePaymentApp does not directly depend on the Moonsense iOS SDK. Instead it includes a dependency to the SamplePaymentSDK which consumes the Moonsense iOS SDK statically linked variant. The app developer here does not have any visibility into the Moonsense iOS SDK as they only interface with the SamplePaymentSDK. The example is useful for SDK/library developers looking to integrate the Moonsense iOS SDK.