Installing Trace for iOS apps

Trace works by installing the Trace SDK to your application during the Bitrise build process. You can do this manually on any device to test it, and once you’re ready to automate your process, you can simply use our dedicated Step on Bitrise.

There are three ways to install Trace for an iOS app:

  • Using Cocoapods.

  • Using the Swift Package Manager.

  • Using the dedicated Add Trace SDK Step.

Xcode version requirement

To add Trace to your iOS app, you must use Xcode 11.5 or higher! Trace is not compatible with older versions of Xcode.

Installing Trace using Cocoapods

Before adding Trace to your apps on Bitrise, try it out first. We’ll walk you through the process using a sample app - but of course you can use any of your own repositories instead of our sample!

In this example, we’re going to use CocoaPods to install the Trace SDK. Let’s see how!

Please note that once you installed Trace, it can take up to an hour for it to start process your data - until then you won’t see any data on your Trace dashboard.

  1. Clone the app and go to its directory on your machine:

    $ git clone https://github.com/bitrise-io/BookStore-iOS.git
    $ cd BookStore-iOS/
  2. Open the Podfile of the app and add the Trace SDK to it:

    # Podfile
        
    target 'YOUR_TARGET_NAME' do
      pod 'BitriseTrace'
    end        
  3. Install the SDK by running pod install.

    If you’ve done everything right, the Pod installation complete! message should appear.

  4. Open Trace on Bitrise: go to your app, click the Add-ons tab, find Trace, and click Go to Add-on.

  5. If it’s your first time setting up Trace for an app, you are automatically taken to the Getting started page. If it’s not your first time, you’re taken to the Trace home page: in the top-right, click Getting started.

  6. Choose Cocoapods from the install options.

    trace_cocoapods.png
  7. Find the Download Config file step, and click Download.

  8. Open your app in Xcode:

    $ open BookStore.xcworkspace/ 
  9. Add the bitrise_configuration.plist file to your app by dragging and dropping it to the root of the project.

    trace-6.png
  10. If prompted to choose from different options for adding the files, choose your project - BookStore in our example -, and click Finish.

    trace-7.png
  11. Build and run the app in a simulator or on a device.

Installing Trace with the Swift Package Manager

The Swift Package Manager (SPM) is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies. You can use the SPM to install the Trace SDK.

The installation process has three stages:

  1. Adding the bitrise_configuration.plist file to your Xcode project.

  2. Initializing the Trace SDK with the SPM.

  3. Configuring your Xcode project to be able to run Trace.

Adding the config file to your app

To use Trace on Bitrise, you need to have a bitrise_configuration.plist file in your Xcode project.

  1. On your own machine, clone the repository of your app, and enter its directory.

    In this example we’re using a sample app; you can use that, too, to try out Trace, or you can replace it with your own app.

    git clone git@github.com:bitrise-io/iosCCC.git
       
    cd iosCCC/  
  2. Open Trace on Bitrise: go to your app, click the Add-ons tab, find Trace, and click Go to Add-on.

  3. If it’s your first time setting up Trace for an app, you are automatically taken to the Getting started page. If it’s not your first time, you’re taken to the Trace home page: in the top-right, click Getting started.

  4. Choose Swift Package Manager from the install options.

    Swift Package Manager instructions
  5. Open your app in Xcode.

  6. Add the bitrise_configuration.plist file to the Xcode project by dragging and dropping it to the root of the project.

When done, proceed to initializing the SDK.

Initializing the SDK

After adding the bitrise_configuration.plist file to your Xcode project, you need to add Trace to the Swift Package Manager.

  1. Go to File > Swift Packages > Add Package Dependency.

  2. Enter the repository URL: https://github.com/bitrise-io/trace-cocoa-sdk.git.

    choose-package-repository.png

When done, proceed to adding Other Linker Flags to application target and creating a Trace object in code.

Configuring your Xcode project to run Trace

After adding the bitrise_configuration.plist file to your Xcode project, and adding Trace to the Swift Package Manager, you need a couple more things to make Trace work:

  • Adding Other Linker Flags to application target.

  • Creating a Trace object in code.

  1. In Xcode, select your project in the Project Navigator.

  2. Under the Targets heading in the sidebar, select the application target.

  3. In the tab bar at the top of that window, open the Build Settings panel.

  4. Search for Other Linker Flags or OTHER_LDFLAGS and enter the following:

    -ObjC -l z -l c++
  5. In the Xcode project, start the SDK by creating a Trace object:

    import SwiftUI
    import Trace
       
    @main
    struct App: SwiftUI.App {
      @StateObject var viewModel = AppViewModel()
      private let trace = Trace.shared
    }    
  6. Build and run the app in a simulator or on a device.

Installing Trace with a Bitrise Step

On Bitrise itself, installing Trace is simple: you only need to add the Add Trace SDK Step to your Workflow. The Step must come before the application’s binary itself is built. For example, if you build an iOS app, the Step must come before the Xcode Archive & Export for iOS Step.

To install Trace:

  1. Open the Workflow Editor of your app.

  2. Open the Workflow you use to build the app.

  3. Add the Add Trace SDK Step before the Step that builds your’s app binary.

  4. Check that the Project (or Workspace) path and the Scheme name input values are both correct.

    By default, both values are Environment Variables which are created and stored at the creation of the app.

  5. Run a build!

If all went well, Trace will track application data.

Once you have the SDK installed, all you need to do is deploy the apps for your users, and watch the data coming in.