コンテンツにスキップ

iOS/tvOS/macOS アプリの導入


iOS、tvOS、macOS アプリのメトリクスデータを収集し、Apple プラットフォームのアプリ側パフォーマンスを可視化して分析します。

参照順序

前提条件

SDK 1.6.8+ では iOS 15、tvOS 15、macOS 12 以上が必要です。アップグレード要件については1.6.8 へのアップグレードを、製品名の変更と旧バージョンのデプロイ要件については1.6.6 へのアップグレードを参照してください。

注意

RUM Headless サービスを有効化済みの場合、前提条件は自動設定されているため、アプリを直接導入できます。

ローカル環境にデプロイする場合は、以下のデータ受信側の設定を完了する必要があります。パブリック DataWay を使用する場合は、DataKit を自身でデプロイする必要はありません。

macOS Alpha の説明

SDK 1.6.6 以降では、GuanceSDK メイン SDK が iOS、tvOS、macOS をカバーします。macOS は現在 Alpha バージョンであり、すべての iOS 機能がサポートされることを保証するものではありません。macOS を導入する前に、テスト環境で初期化、RUM、Log、Trace、データ同期などの主要なフローを検証してください。Widget Extension は macOS をサポートしていません。macOS Electron Session Replay の導入と機能範囲については、macOS Electron モニタリングを参照してください。

アプリの導入

  1. RUM > アプリを作成に移動し、iOS、tvOS、または macOS のアプリタイプを選択します。
  2. アプリ名を入力します。
  3. アプリ ID を入力します。
  4. 「導入方法を選択」で Agent 自動導入または手動導入を選択し、「導入設定」を完了します。

導入方法を選択

アプリ設定ページで「Agent 自動導入」または「手動導入」を選択し、「導入設定」を完了します。既存のアプリは設定ページに直接進み、導入を続行できます。

導入方法 ユースケース 操作入口
Agent 自動導入 コーディングアシスタントにプロジェクトを分析させ、SDK の導入を完了したい場合 コンソールで生成されたプロンプトをコピーし、アプリのコードリポジトリでコーディングアシスタントに渡して実行します
手動導入 SDK を自身でインストールし、パラメーターを設定したい場合 データ送信方法を確認し、本文とクイックスタートに従って設定を完了します

Agent 自動導入

  1. 現在のアプリの設定ページで「Agent 自動導入」を選択します。
  2. 「導入設定」にある完全なプロンプトをコピーし、現在のアプリの導入情報が使用されていることを確認します。
  3. アプリのコードリポジトリでコーディングアシスタントを開き、プロンプトを貼り付けます。Agent が導入ガイドに従ってプロジェクトを分析し、SDK 設定を完了します。
  4. アプリをビルドして実行し、ページアクセスなどの操作を発生させ、現在のアプリのエクスプローラーでデータが受信されていることを確認します。

ページで個人用 API Key または一時認証コードが準備できていない旨が表示された場合は、案内に従って補完してから、プロンプトを再コピーしてください。

手動導入

アプリ設定ページで「手動導入」を選択し、データ送信方法を確認します。

  • パブリック DataWay:RUM データを直接受信します。DataKit コレクターをインストールする必要はありません。
  • ローカル環境へのデプロイ:前提条件を満たしたうえで RUM データを受信します。

以下のインストールとクイックスタートに従って、SDK のインストール、初期化、検証を完了します。既存の SDK 設定がある場合は、重複した初期化を避けるため、まず内容を確認して再利用してください。

インストール

tvOS

ソースコード:https://github.com/GuanceCloud/datakit-ios

Demo:https://github.com/GuanceDemo/guance-app-demo

CocoaPods の今後のメンテナンスについて

CocoaPods の公式アナウンスによると、CocoaPods は 2026 年 12 月 2 日以降に trunk を読み取り専用状態へ切り替える予定であり、新しい Podspec を受け付けなくなります。公開済みの Pod バージョンと既存のビルドは直ちに無効にはなりませんが、今後 CocoaPods 経由で新しいバージョン、互換性修正、セキュリティアップデートを取得することが制限される可能性があります。そのため、新規に SDK を導入する場合や SDK をアップグレードする場合は、Swift Package Manager 方式での統合を優先することを推奨します。

Using Xcode UI

  1. Xcode で File -> Add Package Dependency... を選択します。

  2. 表示されたページの検索ボックスに https://github.com/GuanceCloud/datakit-ios.git を入力します。

  3. Xcode がパッケージを解析したら、依存バージョンのルールを選択します。Up to Next Major Version を推奨します。

    追加先のプロジェクトを選択したら、Add Package をクリックし、読み込みが完了するまで待ちます。

  4. パッケージの解析が完了したら、Package Products リストで各 Target に追加するプロダクトを選択し、Add Package をクリックします。

    GuanceSDK:メインプロジェクトの Target に追加します。iOS、tvOS、macOS をサポートします。macOS は Alpha バージョンです。

    GuanceWidgetExtension:iOS Widget Extension Target にのみ追加します。

Using Package.swift

プロジェクト自体が Swift Package の場合は、SDK を依存関係として追加し、Package.swift に dependencies を追加してください。

// メインプロジェクト
dependencies: [
.package(url: "https://github.com/GuanceCloud/datakit-ios.git",
.upToNextMajor(from: "[latest_version]"))
]

Target に依存関係を追加します:

targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "GuanceSDK", package: "GuanceSDK"),
        ]),
    .target(
        name: "YourWidgetExtensionTarget",
        dependencies: [
            .product(name: "GuanceWidgetExtension", package: "GuanceSDK"),
        ]),
    ]

注意:Swift Package Manager は 1.4.0-beta.1 以降でサポートされています。SDK 1.6.6 以降では、SPM のプロダクト名が GuanceSDK、GuanceWidgetExtension、GuanceSessionReplay に変更されています。旧プロダクト名からの移行については移行ガイドを参照してください。

  1. Cartfile ファイルを設定します。

    github "GuanceCloud/datakit-ios" == [latest_version]
    
  2. 依存関係を更新します。

    対象プラットフォーム(iOS、tvOS、macOS)に応じて、対応する carthage update コマンドを実行し、XCFrameworks を生成するために --use-xcframeworks パラメーターを追加します:

    • iOS プラットフォームの場合:

      carthage update --platform iOS --use-xcframeworks
      
    • tvOS プラットフォームの場合:

      carthage update --platform tvOS --use-xcframeworks
      
    • macOS プラットフォームの場合:

      carthage update --platform macOS --use-xcframeworks
      

    生成された xcframework は通常の Framework と同じように使用できます。ビルドで生成されたライブラリをプロジェクトに追加します。

    GuanceSDK:メインプロジェクトの Target に追加します。iOS、tvOS、macOS をサポートします。macOS は Alpha バージョンです。

    GuanceWidgetExtension:iOS ウィジェットの Widget Extension Target にのみ追加します。

  3. TARGETS -> Build Setting -> Other Linker Flags に -ObjC を追加します。

  4. Carthage で統合する場合、サポートされる SDK バージョンは次のとおりです:

    GuanceSDK:>=1.6.6

    GuanceWidgetExtension:>=1.6.6

CocoaPods の適用について

CocoaPods の公式アナウンスによると、CocoaPods は 2026 年 12 月 2 日以降に trunk を読み取り専用状態へ切り替える予定であり、新しい Podspec を受け付けなくなります。新規プロジェクトまたは依存関係の管理方法を調整中のプロジェクトでは、上記の Swift Package Manager 方式で SDK を統合することを優先してください。

  1. Podfile ファイルを設定します。

    • Dynamic Library を使用する

      use_frameworks!
      def shared_pods
        pod 'GuanceSDK', '[latest_version]'
        # Widget Extension のデータを収集する場合
        pod 'GuanceSDK/WidgetExtension', '[latest_version]'
      end
      
      # メインプロジェクト
      target 'yourProjectName' do
        shared_pods
      end
      
      # Widget Extension
      target 'yourWidgetExtensionName' do
        shared_pods
      end
      
    • Static Library を使用する

      use_modular_headers!
      # メインプロジェクト
      target 'yourProjectName' do
        pod 'GuanceSDK', '[latest_version]'
      end
      # Widget Extension
      target 'yourWidgetExtensionName' do
        pod 'GuanceSDK/WidgetExtension', '[latest_version]'
      end
      
    • コードベースをローカルにダウンロードして使用する

      Podfile ファイル:

      use_modular_headers!
      # メインプロジェクト
      target 'yourProjectName' do
        pod 'GuanceSDK', :path => '[folder_path]'
      end
      # Widget Extension
      target 'yourWidgetExtensionName' do
        pod 'GuanceSDK/WidgetExtension', :path => '[folder_path]'
      end
      

      folder_path:GuanceSDK.podspec が存在するフォルダーのパス。

      GuanceSDK.podspec ファイル:

      GuanceSDK.podspec ファイルの s.version と s.source を変更します。

      Pod::Spec.new do |s|
        s.name         = "GuanceSDK"
        s.version      = "[latest_version]"
      s.source       = { :git => "https://github.com/GuanceCloud/datakit-ios.git", :tag => s.version }
      end
      

      s.version:指定したバージョンに変更します。Sources/Agent/Core/FTSDKVersion.h の SDK_VERSION と一致させることを推奨します。

      s.source:tag => s.version

Widget Extension の互換性のある記述:

SDK 1.6.6 以降では GuanceSDK/WidgetExtension の使用を推奨します。旧プロジェクトで従来 pod 'FTMobileSDK', :subspecs => ['Extension'] を使用していた場合も、GuanceSDK にアップグレードした後は互換 subspec を引き続き使用できます:

target 'yourWidgetExtensionName' do
  pod 'GuanceSDK', :subspecs => ['Extension']
end
  1. Podfile のディレクトリで pod install を実行し、SDK をインストールします。

互換性について:SDK 1.6.6 以降のメイン Pod 名は GuanceSDK です。旧 FTMobileSDK の統合方法は 1.6.6 より前のバージョンに適用されます。1.6.6 以降にアップグレードする場合は、移行ガイドを参照して依存関係の名前を調整してください。

ヘッダーファイルを追加

#import <GuanceSDK/GuanceSDK.h>
import GuanceSDK

詳細設定の入口

高度なユースケース

よくある質問

クラッシュログ分析について

開発時の Debug および Release モードでは、Crash 時にキャプチャされたスレッドバックトレースはシンボル化されています。 一方、リリースパッケージにはシンボルテーブルが含まれていないため、異常が発生したスレッドの重要なバックトレースにはイメージ名が表示され、有効なコードシンボルに変換されません。取得した crash log 内の関連情報はすべて 16 進数のメモリアドレスであり、クラッシュしたコードを特定できないため、16 進数のメモリアドレスを対応するクラスとメソッドに解決する必要があります。

コンパイルまたはパッケージング後に dSYM ファイルを見つける方法

  • Xcode では、dSYM ファイルは通常、コンパイル後の .app ファイルと一緒に生成され、同じディレクトリに配置されます。
  • プロジェクトをアーカイブした場合は、Xcode の Window メニューで Organizer を選択し、対応するアーカイブファイルを選択します。アーカイブファイルを右クリックして Show in Finder” を選択し、Finder で対応する .xcarchive ファイルを見つけます。.xcarchive ファイルを右クリックして Show Package Contents を選択し、dSYMs フォルダーに移動すると、対応する dSYM ファイルが見つかります。

XCode でコンパイル後に dSYM ファイルが生成されない場合は?

XCode の Release ビルドではデフォルトで dSYM ファイルが生成されますが、Debug ビルドではデフォルトで生成されません。対応する Xcode 設定は次のとおりです:

Build Settings -> Code Generation -> Generate Debug Symbols -> Yes

Build Settings -> Build Option -> Debug Information Format -> DWARF with dSYM File

bitCode を有効にした場合、シンボルテーブルをアップロードする方法

bitcode アプリを App Store にアップロードする際、提出ダイアログでシンボルファイル(dSYM ファイル)の生成を宣言する項目にチェックを入れます:

  • シンボルテーブルファイルを設定する前に、App Store から該当バージョンに対応する dSYM ファイルをローカルにダウンロードし、その後スクリプトで入力パラメーターに応じてシンボルテーブルファイルのアップロードを処理する必要があります。
  • スクリプトを Xcode プロジェクトの Target に統合する必要はありません。また、ローカルで生成された dSYM ファイルを使用してシンボルテーブルファイルを生成しないでください。ローカルビルドで生成された dSYM ファイルのシンボルテーブル情報はすべて隠蔽されているためです。ローカルビルドで生成された dSYM ファイルをアップロードすると、復元結果は「__hiden#XXX」のようなシンボルになります。

App Store に公開済みの App に対応する dSYM ファイルを取得する方法

App Store Connect へのアップロード時の Distribution options dSym ファイル
Don’t include bitcode
Upload symbols
Xcode から取得
Include bitcode
Upload symbols
iTunes Connect から取得
Xcode から取得。.bcsymbolmap を使用して難読化解除処理を行う必要があります。
Include bitcode
Don’t upload symbols
Xcode から取得。.bcsymbolmap を使用して難読化解除処理を行う必要があります。
Don’t include bitcode
Don’t upload symbols
Xcode から取得
Xcode から取得
  1. Xcode -> Window -> Organizer

  2. Archives タブを選択します。

  3. 公開したアーカイブパッケージを見つけ、対応するアーカイブパッケージを右クリックして Show in Finder を選択します。

  4. 特定したアーカイブファイルを右クリックし、パッケージの内容を表示 を選択します。

  5. dSYMs ディレクトリを選択します。このディレクトリ内に、ダウンロードされた dSYM ファイルがあります。

iTunes Connect から取得
  1. App Store Connect にログインします。
  2. 「My Apps」に移動します。
  3. 「App Store」または「TestFlight」で任意のバージョンを選択し、「Build Metadata(ビルドメタデータ)」をクリックします。このページで「Download dSYM(dSYM をダウンロード)」ボタンをクリックして dSYM ファイルをダウンロードします。
.bcsymbolmap の難読化解除処理

Xcode から dSYM ファイルを見つけると、BCSymbolMaps ディレクトリを確認できます。

ターミナルを開き、次のコマンドを使用して難読化解除処理を行います。

xcrun dsymutil -symbol-map <BCSymbolMaps_path> <.dSYM_path>

フィールドの衝突を避けるためにグローバル変数を追加

カスタムフィールドと SDK データの衝突を避けるため、タグ名には プロジェクトの略称 のプレフィックスを付けることを推奨します(例:custom_tag_name)。プロジェクトで使用されている key の値はソースコードを参照して確認できます。SDK のグローバル変数に RUM、Log と同じ変数が存在する場合、RUM、Log が SDK のグローバル変数を上書きします。

フィードバック

このページは役に立ちましたか?