Skip to main content

Installation

Installation​

Integrating the Embrace Apple SDK can be accomplished using either the Swift Package Manager or CocoaPods. The information below outlines the steps for both methods. Additionally, you can pull down the open-source repository and integrate it manually if your app requires a custom setup.

Swift Package Manager​

For your project, you'll want to add a package dependency in Xcode. Select File > Add Package Dependencies... and enter the repository URL https://github.com/embrace-io/embrace-apple-sdk.git into the search bar.

Be sure to set the Dependency Rule to a recent release. When "Choose Package Products for embrace-apple-sdk" appears, Xcode will add all libraries to your application by default. For the most straightforward installation, select EmbraceIO to add to your application target. For all other package products, select None.

Explanation of Package Products

Here's a quick summary of the products this package contains:

  • EmbraceIO - This is the recommended product to install for quick integration. It is the single public entry point and provides a convenience layer over EmbraceCore to simplify the setup interface.
  • EmbraceCore - This is the main implementation of the Embrace SDK. If you'd like to customize your integration, this product allows you to.
  • EmbraceSemantics - This module contains the public, Embrace-owned signal types (such as EmbraceSpan and EmbraceLog) as well as constants and attributes used to extend OTel Semantic Conventions.
  • EmbraceMacros - Swift macros that provide convenience instrumentation helpers.

Trusting the Embrace macros​

Xcode requires you to trust a package's macro plugin before it builds code that uses it, and asks again whenever the package version changes. If the build fails with Macro "EmbraceMacroPlugin" from package "embrace-apple-sdk" must be enabled before it can be used, open the error in the Issue navigator and click Trust & Enable. For command-line builds, such as on CI, pass -skipMacroValidation to xcodebuild.

Only targets that add the EmbraceMacros product need this. EmbraceIO alone doesn't use the macro plugin.

CocoaPods​

Installing through CocoaPods is straightforward. Add the main pod to your Podfile:

pod 'EmbraceIO', '~> 7.0.0'

By default, this command installs all the necessary components to use the SDK, including crash reporting and Crashlytics support.

info

If you wish to continue using Crashlytics as your primary crash reporter while also having those crashes reported to the Embrace Dashboard and using all associated features, you no longer need a separate pod. Crashlytics support is bundled with EmbraceIO — enable it at setup time with crashReporter: .crashlytics. See Basic Setup.

Next Steps​

After installing the Embrace SDK, you need to set up and configure it in your application code.