Overview

note

Please also check out our full featured, interactive Hello Causal tutorial. It is TypeScript focused, but still a great way to learn about about Causal.

This is the user’s guide for the Causal native iOS SDK, which integrates Causal with native iOS apps. It covers how to integrate the SDK into an app, as well as various configuration options.

Core components of the SDK are located in a CausalLabs iOS framework. Additional code is generated in Swift by compiling an FDL file. The SDK is fully compatible with both Swift and Objective-C.

Requirements

To use the iOS SDK, you first need to ensure that the following software is installed:

• Xcode 14 or higher, running on Mac OS X Monterey or higher.
• An iOS package manager. The Causal SDK supports Cocoapods, Swift Package Manager, and manual integration. Full source code of the SDK is provided, for integration into other package managers if desired.
• Java 11 JDK or higher, optimized for Arm or Intel depending on your Mac. OpenJDK builds are available here.

The SDK is supported on iOS 13.0 and above, for both Swift and Objective-C.

Obtaining the SDK

Obtain and unzip the file causallabs_ios_release.zip from our team at support@causallabs.io.

Integration using Cocoapods

With Cocoapods, the SDK may be integrated as a local pod within an existing repository. The examples/SampleAppCocoapods directory in the distribution contains an example integration.

The Podfile to depend on the CausalLabs SDK looks as follows:

platform :ios, '13.0'

use_frameworks!

target 'SampleAppCocoapods' do
    pod 'CausalLabs', :path => '../../CausalLabs'

    script_phase :name => 'CausalLabs FDL Generation',
        :script => '${PROJECT_DIR}/../../CausalLabs/scripts/fdlgen.sh ${PROJECT_DIR}/causal.fdl ${PROJECT_DIR}/SampleAppCocoapods/Generated/Generated.swift',
        :execution_position => :before_compile,
        :input_files => ['causal.fdl'],
        :output_files => ['SampleAppCocoapods/Generated/Generated.swift']
end

The causal.fdl file contains the Causal features for which code should be generated. In the Podfile, include a script_phase that runs the fdlgen.sh script on this fdl file. That script takes in two parameters, the absolute path to the FDL file, and the absolute path to the Swift file which should be generated. Ensure that the relative paths to the FDL file, and generated Swift file, are also specified to Cocoapods in the :input_files and :output_files parameters, in order for incremental builds to function properly.

The SampleAppCocoapods/Generated/Generated.swift file should not be committed to the codebase, but instead is generated on builds based on the FDL file. Add this path to your .gitignore file.

Causal recommends generating code from the FDL at build time in order to pick up updates whenever the FDL file has changed. However, if you wish to instead generate FDL ahead of time, omit the script phase and instead run this script manually, and commit the Generated.swift file into the repository.

Manual integration

The SDK may be manually integrated as well. The example project located under examples/SampleAppManualIntegration shows an example of this.

To set up manual integration, open up an existing Xcode project, and add in the CausalLabs subdirectory from the SDK into the same git repository as the existing Xcode project. Drag the CausalLabs/CausalLabs.xcodeproj project, from the Finder, into the existing Xcode project, such that it appears nested, with a relative path reference to the CausalLabs.xcodeproj file.

Select the project, and corresponding target, within the sidebar within Xcode, of the target which will depend on the Causal SDK. In Xcode, select the General tab, and expand the "Frameworks, Libraries, and Embedded Content" section, then tap the + button, and select CausalLabs.framework to add.

Switch from the General tab to the Build Phases tab, tap +, and add a new Run Script phase. Drag the Run Script phase upwards to above the Compile Sources phase. Expand it out, and within the shell paste ${PROJECT_DIR}/../../CausalLabs/scripts/fdlgen.sh ${PROJECT_DIR}/causal.fdl ${PROJECT_DIR}/SampleAppManualIntegration/Generated/Generated.swift. Within Input Files add causal.fdl. Within Output Files add SampleAppManualIntegration/Generated/Generated.swift

Make sure that the file Generated/Generated.swift is added to your target as a Source file (it is ok to create an empty file in this location if it does not exist yet.

The app may now be built and run.

Integration using Swift Package Manager

Integration with Swift Package Manager is still experimental. The CausalLabs target itself may be delivered via Swift Package Manager, but code generation from the FDL file is still best done using a custom Run Script, as with Manual integration, rather than via a Swift Package plugin.

The example project located under examples/SampleAppSPM contains an example integration using Swift Package Manager.

First, as with Manual integration and Cocoapods, ensure that the CausalLabs SDK directory is first part of the same git repository as the main workspace & project which will depend on the SDK.

Within an existing project, select the target that will contain the dependency on the SDK. In the General tab within Xcode, scroll down to Frameworks, Libraries, and Embedded Content, tap +, tap Add Other, tap Add Package Dependency, tap Add Local... and select the CausalLabs directory, to add CausalLabs as a local SPM dependency.

Then, within the same target, go to the Build Phases tab. Under Target Dependencies, select the CausalLabs framework, then tap Add. Expand Link Binary with Libraries, tap +, and select the CausalLabs framework.

Lastly, add a new Run Script phase. Drag the Run Script phase upwards to above the Compile Sources phase. Expand it out, and within the shell paste ${PROJECT_DIR}/../../CausalLabs/scripts/fdlgen.sh ${PROJECT_DIR}/causal.fdl ${PROJECT_DIR}/SampleAppSPM/Generated/Generated.swift. Within Input Files add causal.fdl. Within Output Files add SampleAppSPM/Generated/Generated.swift

Add an empty file SampleAppSPM/Generated/Generated.swift as a source file within the target, and add this entry to a .gitignore file. The file will be populated after the first build.

Additional resources

• Reference Manual