iOS/tvOS/macOS アプリの導入¶
iOS、tvOS、macOS アプリのメトリクスデータを収集し、Apple プラットフォームのアプリ側パフォーマンスを可視化して分析します。
参照順序¶
- 初回導入:まず導入方法を選択してください。手動導入の場合はクイックスタートを参照できます
- 全体の導入:引き続き本文をお読みください
- 1.6.6 より前のバージョンからのアップグレード:移行ガイドを参照してください
- 初期化パラメーター:SDK の初期化、RUM 設定、Log 設定、Trace 設定を参照してください
- カスタマイズ機能:カスタムタグの使用、カスタム収集ルール、データ収集のマスキングを参照してください
- 高度なユースケース:「高度なユースケース」グループの専用ページを参照してください
- トラブルシューティング:トラブルシューティングを参照してください
前提条件¶
SDK 1.6.8+ では iOS 15、tvOS 15、macOS 12 以上が必要です。アップグレード要件については1.6.8 へのアップグレードを、製品名の変更と旧バージョンのデプロイ要件については1.6.6 へのアップグレードを参照してください。
注意
RUM Headless サービスを有効化済みの場合、前提条件は自動設定されているため、アプリを直接導入できます。
ローカル環境にデプロイする場合は、以下のデータ受信側の設定を完了する必要があります。パブリック DataWay を使用する場合は、DataKit を自身でデプロイする必要はありません。
- DataKit をインストールします。
- RUM コレクターを設定します。
- DataKit をパブリックにアクセス可能にし、IP ジオロケーションデータベースをインストールします。
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 モニタリングを参照してください。
アプリの導入¶
- RUM > アプリを作成に移動し、iOS、tvOS、または macOS のアプリタイプを選択します。
- アプリ名を入力します。
- アプリ ID を入力します。
- 「導入方法を選択」で Agent 自動導入または手動導入を選択し、「導入設定」を完了します。
導入方法を選択¶
アプリ設定ページで「Agent 自動導入」または「手動導入」を選択し、「導入設定」を完了します。既存のアプリは設定ページに直接進み、導入を続行できます。
| 導入方法 | ユースケース | 操作入口 |
|---|---|---|
| Agent 自動導入 | コーディングアシスタントにプロジェクトを分析させ、SDK の導入を完了したい場合 | コンソールで生成されたプロンプトをコピーし、アプリのコードリポジトリでコーディングアシスタントに渡して実行します |
| 手動導入 | SDK を自身でインストールし、パラメーターを設定したい場合 | データ送信方法を確認し、本文とクイックスタートに従って設定を完了します |
Agent 自動導入¶
- 現在のアプリの設定ページで「Agent 自動導入」を選択します。
- 「導入設定」にある完全なプロンプトをコピーし、現在のアプリの導入情報が使用されていることを確認します。
- アプリのコードリポジトリでコーディングアシスタントを開き、プロンプトを貼り付けます。Agent が導入ガイドに従ってプロジェクトを分析し、SDK 設定を完了します。
- アプリをビルドして実行し、ページアクセスなどの操作を発生させ、現在のアプリのエクスプローラーでデータが受信されていることを確認します。
ページで個人用 API Key または一時認証コードが準備できていない旨が表示された場合は、案内に従って補完してから、プロンプトを再コピーしてください。
手動導入¶
アプリ設定ページで「手動導入」を選択し、データ送信方法を確認します。
- パブリック DataWay:RUM データを直接受信します。DataKit コレクターをインストールする必要はありません。
- ローカル環境へのデプロイ:前提条件を満たしたうえで RUM データを受信します。
以下のインストールとクイックスタートに従って、SDK のインストール、初期化、検証を完了します。既存の SDK 設定がある場合は、重複した初期化を避けるため、まず内容を確認して再利用してください。
インストール¶
ソースコード: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
-
Xcode で
File->Add Package Dependency...を選択します。 -
表示されたページの検索ボックスに
https://github.com/GuanceCloud/datakit-ios.gitを入力します。 -
Xcode がパッケージを解析したら、依存バージョンのルールを選択します。
Up to Next Major Versionを推奨します。追加先のプロジェクトを選択したら、
Add Packageをクリックし、読み込みが完了するまで待ちます。 -
パッケージの解析が完了したら、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 に変更されています。旧プロダクト名からの移行については移行ガイドを参照してください。
-
Cartfileファイルを設定します。 -
依存関係を更新します。
対象プラットフォーム(iOS、tvOS、macOS)に応じて、対応する
carthage updateコマンドを実行し、XCFrameworks を生成するために--use-xcframeworksパラメーターを追加します:-
iOS プラットフォームの場合:
-
tvOS プラットフォームの場合:
-
macOS プラットフォームの場合:
生成された xcframework は通常の Framework と同じように使用できます。ビルドで生成されたライブラリをプロジェクトに追加します。
GuanceSDK:メインプロジェクトの Target に追加します。iOS、tvOS、macOS をサポートします。macOS は Alpha バージョンです。GuanceWidgetExtension:iOS ウィジェットの Widget Extension Target にのみ追加します。 -
-
TARGETS->Build Setting->Other Linker Flagsに-ObjCを追加します。 -
Carthage で統合する場合、サポートされる SDK バージョンは次のとおりです:
GuanceSDK:>=1.6.6GuanceWidgetExtension:>=1.6.6
CocoaPods の適用について
CocoaPods の公式アナウンスによると、CocoaPods は 2026 年 12 月 2 日以降に trunk を読み取り専用状態へ切り替える予定であり、新しい Podspec を受け付けなくなります。新規プロジェクトまたは依存関係の管理方法を調整中のプロジェクトでは、上記の Swift Package Manager 方式で SDK を統合することを優先してください。
-
Podfileファイルを設定します。-
Dynamic Library を使用する
-
Static Library を使用する
-
Podfileファイル:use_modular_headers! # メインプロジェクト target 'yourProjectName' do pod 'GuanceSDK', :path => '[folder_path]' end # Widget Extension target 'yourWidgetExtensionName' do pod 'GuanceSDK/WidgetExtension', :path => '[folder_path]' endfolder_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 } ends.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 を引き続き使用できます:
Podfileのディレクトリでpod installを実行し、SDK をインストールします。
互換性について:SDK 1.6.6 以降のメイン Pod 名は GuanceSDK です。旧 FTMobileSDK の統合方法は 1.6.6 より前のバージョンに適用されます。1.6.6 以降にアップグレードする場合は、移行ガイドを参照して依存関係の名前を調整してください。
ヘッダーファイルを追加¶
詳細設定の入口¶
高度なユースケース¶
- カスタムタグの使用
- データ収集のカスタムルール
- データ収集のマスキング
- URLSession によるカスタム Network 収集
- 動的設定
- シンボルファイルのアップロード
- Widget Extension のデータ収集
- WebView のデータモニタリング
- macOS Electron モニタリング
- tvOS のデータ収集
- ビジター識別子 Visitor ID
よくある質問¶
クラッシュログ分析について¶
開発時の 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 から取得¶
-
Xcode -> Window -> Organizer -
Archivesタブを選択します。 -
公開したアーカイブパッケージを見つけ、対応するアーカイブパッケージを右クリックして
Show in Finderを選択します。 -
特定したアーカイブファイルを右クリックし、
パッケージの内容を表示を選択します。 -
dSYMsディレクトリを選択します。このディレクトリ内に、ダウンロードされた dSYM ファイルがあります。
iTunes Connect から取得¶
- App Store Connect にログインします。
- 「My Apps」に移動します。
- 「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 のグローバル変数を上書きします。






