Skip to content

macOS App Integration


Guance Application Monitoring collects metrics from macOS apps and visualizes the performance of each macOS app client.

Reading Path

Prerequisites

Note

If the RUM Headless service is enabled, the prerequisites are configured automatically, and you can integrate the app directly.

For local environment deployments, complete the following data receiver configuration. For public DataWay, you do not need to deploy DataKit yourself.

App Integration

  1. Go to RUM > Create > macOS;
  2. Enter the app name;
  3. Enter the app ID;
  4. In Select Access Method, choose Agent Auto-Integration or Manual Integration, then complete Integration Configuration.

Choose an Access Method

On the app configuration page, select Agent Auto-Integration or Manual Integration, then complete Integration Configuration. For an existing app, go directly to the configuration page to continue integration.

Access Method Use Cases Entry Point
Agent Auto-Integration Let a coding assistant analyze the project and complete SDK integration Copy the prompt generated in the console and run it with the coding assistant in the app code repository
Manual Integration Install the SDK and configure parameters yourself Confirm the data reporting method, then complete configuration by following this document and Quick Start

Agent Auto-Integration

  1. On the configuration page for the current app, select Agent Auto-Integration.
  2. Copy the complete prompt from Integration Configuration, and make sure it uses the integration information for the current app.
  3. Open the coding assistant in the app code repository, paste the prompt, and let the Agent analyze the project and complete the SDK configuration according to the integration guide.
  4. Build and run the app, trigger operations such as page views, and verify in the Explorer for the current app that data is received.

If the page indicates that your personal API Key or temporary authorization code is not ready, complete the required information as prompted, and then copy the prompt again.

Manual Integration

On the app configuration page, select Manual Integration, and confirm the data reporting method:

  • Public DataWay: receives RUM data directly; no DataKit collector installation is required.
  • Local environment deployment: receives RUM data after the prerequisites are met.

Follow the Installation and Quick Start sections below to install, initialize, and verify the SDK. If an SDK configuration already exists, review and reuse it first to avoid duplicate initialization.

Installation

Source Code: https://github.com/GuanceCloud/datakit-macos

Demo: https://github.com/GuanceCloud/datakit-macos/Example

  1. Configure the Podfile.
   target 'yourProjectName' do

   # Pods for your project
   pod 'FTMacOSSDK', '~>[latest_version]'

   end
  1. In the directory containing the Podfile, run pod install to install the SDK.
  1. Select PROJECT -> Package Dependency, then click + under Packages.

  2. In the search box on the page that appears, enter https://github.com/GuanceCloud/datakit-macos, which is the repository location.

  3. After Xcode successfully fetches the package, it displays the SDK configuration page.

Dependency Rule: We recommend selecting Up to Next Major Version.

Add To Project: Select the supported project.

After filling in the configuration, click Add Package and wait for loading to complete.

  1. In the Choose Package Products for datakit-macos dialog, select the Target to which you want to add the SDK, and click Add Package. The SDK is now added successfully.

If your project is managed by SPM, add FTMacOSSDK as a dependency by adding dependencies to Package.swift.

```swift dependencies: [

.package(url: "https://github.com/GuanceCloud/datakit-macos.git", .upToNextMajor(from: "[latest_version]")) ] ```

Add Header File

#import "FTMacOSSDK.h"
import FTMacOSSDK

Detailed Configuration Entry Points

Advanced Scenarios

FAQ

Crash Log Analysis

For crash log analysis and dSYM details, see Troubleshooting.

Include of non-modular header inside framework module error occurs

Because the SDK's .h files import .h files from dependent libraries, set the following:

Set Target -> Build Settings -> CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES to YES.

Feedback

Is this page helpful?