dt-setup-ios

Dynatrace iOS SDK のセットアップ

このスキルは、ユーザーの iOS プロジェクトに Dynatrace iOS SDK（OneAgent）をセットアップし、最初のイベントが発生するまでを支援します。Dynatrace のドキュメントに記載された公式のセットアップ手順に従います。

このスキルを使用するタイミング

• ユーザーが iOS アプリに Dynatrace のモニタリングを追加したい場合
• ユーザーが Dynatrace iOS SDK の統合、インストール、またはセットアップを依頼した場合
• ユーザーが Dynatrace を使って iOS アプリを計測したい場合
• ユーザーが Experience Vitals ウィザードからコピーしたセットアッププロンプトを貼り付けた場合

事前入力された値

Experience Vitals ウィザードから呼び出された場合、ユーザーのメッセージには dynatrace-ios-setup-config とラベル付けされたフェンス付きブロックに、事前入力された設定値が含まれます。例：

```dynatrace-ios-setup-config
DTXApplicationID: ABC-123
DTXBeaconURL: https://example.dynatrace.com/mbeacon
Product: DynatraceSessionReplay
DTXUserOptIn: true
```

これらの値が含まれている場合：

• ステップ 2（アプリケーション識別キーの収集）をスキップします — 提供された DTXApplicationID と DTXBeaconURL を使用します。
• ステップ 3 の製品に関する質問をスキップします — 提供された Product の値 （Dynatrace または DynatraceSessionReplay）を使用します。
• DTXUserOptIn を使用して、ステップ 5 でプライバシーのオプトインコードを追加するかどうかを判断します。 true の場合はオプトインコードを追加します。false の場合はステップ 5 をスキップします。

それ以外の手順（前提条件、SPM 依存関係、plist の作成、インポート、ビルド、検証）は通常どおり進めます。

手順

1. 前提条件を確認する

次に進む前に、各前提条件を必ず確認してください。確認に失敗した場合はユーザーに伝え、作業を中止してください。

a）Xcode MCP サーバーが利用可能であること これは必須条件です。このスキルでは、Xcode MCP サーバーを使用して Xcode プロジェクトを操作します（SPM 依存関係の追加、ビルドなど）。Xcode MCP ツール（例：mcp_xcode_XcodeListWindows）が利用可能であることを確認してください。利用できない場合は、作業を進める前に Xcode MCP サーバーをインストールして有効にするようユーザーに伝えてください。

b）iOS のデプロイメントターゲットが 12.0 以上であること .pbxproj ファイルは Xcode MCP サーバーからアクセスできません（プロジェクトのメタデータであり、ナビゲーターのファイルではありません）。代わりにターミナルで grep を使用します。

grep 'IPHONEOS_DEPLOYMENT_TARGET' <path/to/project.pbxproj>

すべてのデプロイメントターゲット値が 12.0 以上であることを確認します。12.0 未満の値がある場合は、更新するようユーザーに伝えてください。

c）Xcode のバージョンが 16.0 以上であること ターミナルで xcodebuild -version を実行して確認します。16.0 未満の場合は、Xcode を更新するようユーザーに伝えてください。

d）Ruby と xcodeproj gem があること ステップ 3 の scripts/add_spm_dependency.rb で必要です。次のコマンドで確認します。

ruby -e 'require "xcodeproj"; puts Xcodeproj::VERSION'

失敗した場合は gem install xcodeproj を実行して、再度確認します。

2. アプリケーション識別キーを収集する

ユーザーのメッセージに dynatrace-ios-setup-config ブロックが含まれている場合（事前入力された値を参照）、そこから DTXApplicationID と DTXBeaconURL を取得して、ステップ 3 に進みます。

含まれていない場合は、必要な 2 つの値をユーザーに尋ねます。

• DTXApplicationID — アプリケーションの一意の識別子
• DTXBeaconURL — ビーコンエンドポイントの URL（例：https://{environment}.dynatrace.com/mbeacon）

ユーザーのメッセージにこれらの値がすでに含まれている場合は、質問をスキップします。

ユーザーがこれらの値を持っていない場合、または取得方法がわからない場合は、公式のセットアップドキュメントを案内してください：https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/ios/id-01-initial-setup

3. プロジェクトに OneAgent を追加する（SPM 依存関係）

Swift Package Manager を使用して、Dynatrace Swift Mobile SDK を追加します。

ユーザーのメッセージに Product の値を含む dynatrace-ios-setup-config ブロックがある場合は、その値をそのまま使用します。ない場合は、どの製品を使用するかユーザーに確認します。

• Dynatrace — モバイルアプリの自動計測用 OneAgent
• DynatraceSessionReplay — OneAgent + Session Replay モジュール（クラッシュ時にリプレイ）

SPM パッケージ URL： https://github.com/Dynatrace/swift-mobile-sdk.git

同梱の Ruby スクリプト scripts/add_spm_dependency.rb を実行します。このスクリプトは xcodeproj gem を使用してパッケージ参照、製品の依存関係、フレームワークのビルドファイルエントリーを正しく追加します。.pbxproj の文字列操作は行いません。

ruby ./scripts/add_spm_dependency.rb \
  <ProjectPath> \
  https://github.com/Dynatrace/swift-mobile-sdk.git \
  8.0.0 \
  <Product> \
  [TargetName]

• ProjectPath — 例：./MyApp.xcodeproj
• <Product> — Dynatrace または DynatraceSessionReplay（手順 3 で選択したもの）
• TargetName — 省略可能。デフォルトでは、プロジェクト内で最初のアプリケーションターゲットが使用されます

このスクリプトは冪等です。2 回実行しても何も変更されません。成功すると OK: project saved と出力します。

何らかの理由でスクリプトが失敗した場合（特殊なプロジェクト構成、Ruby が利用できないなど）は、Xcode で手動で追加するようユーザーを案内します。

1. Xcode でプロジェクトを開きます
2. File > Add Package Dependencies...
3. URL を入力します：https://github.com/Dynatrace/swift-mobile-sdk.git
4. 8.0.0 から Up to Next Major Version を選択します
5. 選択したライブラリをアプリのターゲットに追加します
6. Add Package をクリックします

スクリプトの実行が成功した後（またはユーザーが手動で追加したことを確認した後）、手順 4 に進みます。

4. Dynatrace.plist 設定を作成する

mcp_xcode_XcodeWrite を使用して、アプリのメインソースディレクトリに新しい Dynatrace.plist ファイルを作成します。これにより、ファイルが Xcode プロジェクトに自動的に登録されます。

内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>DTXApplicationID</key>
    <string>{USER_PROVIDED_APP_ID}</string>
    <key>DTXBeaconURL</key>
    <string>{USER_PROVIDED_BEACON_URL}</string>
    <key>DTXUserOptIn</key>
    {USER_OPT_IN_VALUE}
    <key>DTXStartupLoadBalancing</key>
    <true/>
    <key>DTXStartupWithGrailEnabled</key>
    <true/>
</dict>
</plist>

{USER_PROVIDED_APP_ID} と {USER_PROVIDED_BEACON_URL} を、手順 2 で取得した実際の値に置き換えます。 {USER_OPT_IN_VALUE} は、設定ブロックの DTXUserOptIn の値に応じて <true/> または <false/> に置き換えます。設定ブロックがない場合は、デフォルトで <true/> を使用します。

• DTXUserOptIn — true の場合、データ収集をオフにした状態でエージェントを起動し、プライバシー API（手順 5 で設定）による明示的なオプトインを必要とします。false の場合、オプトインを必要とせずにデータ収集を直ちに開始し、手順 5 はスキップします。
• DTXStartupLoadBalancing — 起動時にクラスターノード間の負荷分散を有効にします。
• DTXStartupWithGrailEnabled — クラスター設定を受信する前のアプリ初回起動時に、最新の Dynatrace で RUM を有効にします。クラスター設定がキャッシュされると、このフラグは恒久的に上書きされます。

5. ユーザーのオプトインに関するプライバシー設定を追加する

mcp_xcode_XcodeRead を使用してアプリのエントリーポイントファイルを読み込み、次に mcp_xcode_XcodeUpdate を使用して TODO コメント付きのプライバシー設定コードを追加します。これにより、適切な場所（プライバシー設定画面など）に移動する必要があることをユーザーに知らせます。

SwiftUI アプリ（@main App 構造体のファイル）の場合： App 構造体の init() メソッド内に次のコードを追加します（存在しない場合は作成します）。

init() {
    // TODO: Move this privacy configuration to your app's privacy settings screen.
    // These settings are provided here for a quick start with capturing monitoring data.
    // In production, this should be driven by user consent (e.g., a privacy settings screen).
    let privacyConfig = Dynatrace.userPrivacyOptions()
    privacyConfig.dataCollectionLevel = .userBehavior
    privacyConfig.crashReportingOptedIn = true
    Dynatrace.applyUserPrivacyOptions(privacyConfig) { (successful) in
        // callback after privacy changed
    }
}

UIKit アプリ（AppDelegate）の場合： 同じコードを application(_:didFinishLaunchingWithOptions:) 内に追加します。

6. Dynatrace のインポートを追加する

mcp_xcode_XcodeUpdate を使用して、アプリのエントリーポイントファイルに import Dynatrace を追加します。

SwiftUI アプリの場合： @main App 構造体を含むファイルに追加します。

UIKit アプリの場合： AppDelegate.swift に追加します。

7. ビルドして実行する

Xcode MCP サーバーを使用してプロジェクトをビルドします。

• mcp_xcode_BuildProject を使用してプロジェクトをビルドします
• ビルドが成功した場合は、成功したことをユーザーに伝えます
• ビルドが失敗した場合は、ビルドエラーを表示し、解決できるようユーザーを支援します

8. インストールを検証する

同梱の検証スクリプト scripts/verify-setup.sh を実行します。このスクリプトはビルド出力、plist の値、シミュレーターの起動、エージェントの起動を順番に set -e で検証し、問題がある場合は個別の終了コードで失敗します。

実行方法：

./scripts/verify-setup.sh <ProjectPath> <SchemeName> \
  <ExpectedAppID> <ExpectedBeaconURL> [ExpectedOptIn]

引数（Xcode プロジェクトとステップ 2／4 で使用した値から確認してください）：

• ProjectPath — 例：./MyApp.xcodeproj
• SchemeName — xcodebuild -list -project <ProjectPath> を実行して利用可能なスキームを確認し、適切なアプリのスキームを選択します（テスト用や無関係なスキームは選択しないでください）
• ExpectedAppID — Dynatrace.plist に設定した DTXApplicationID の値
• ExpectedBeaconURL — Dynatrace.plist に設定した DTXBeaconURL の値
• ExpectedOptIn — 任意です。true または false を指定すると、ステップ 4 で使用した DTXUserOptIn の値を検証します。省略すると検証をスキップします。

終了コード：

コード	意味	対処
0	すべてのチェックに合格し、plist の値が正しく、エージェントの起動ログも確認できました	成功を報告します
2	ビルド出力にフレームワークがない、plist がない、または plist の値が想定と一致しません	SPM のリンク／plist のターゲットメンバーシップ／値の誤り — 具体的な内容は stderr に表示されます
3	シミュレーターの起動／インストール／アプリの起動に失敗しました	stderr を確認します。アプリのバンドルが古い場合はステップ 7 を再実行してください
4	起動後に Dynatrace Core のログが見つかりません	エントリーポイントに import Dynatrace があることを確認し、手動での起動と Dynatrace 環境の確認を提案してください
5	log show 自体が失敗しました	シミュレーターの状態に問題があります。シミュレーターを再起動してから再試行してください

スクリプトは === Phase N: ... === 形式のヘッダーを出力するため、標準出力から部分的な失敗をデバッグできます。

検証後の案内

ユーザーが操作してイベントを生成できるよう、アプリを開いたままシミュレーターを起動状態にしておきます。生成されたイベントはユーザーの Dynatrace 環境に表示されます。シミュレーターをシャットダウンしないでください。

検証に成功したら、ユーザーに次の内容を伝えます。

• シミュレーター上でアプリが起動しています。Dynatrace 環境にデータが届いていることを確認するには、次の操作を行ってください。
  1. アプリを操作します。ボタンをタップしたり、画面間を移動したりして、ユーザーアクションとイベントを生成します。
  2. アプリをバックグラウンドに移動し（シミュレーターのホームボタンを押します）、再びフォアグラウンドに戻します。これにより、Dynatrace クラスターへのセッションのフラッシュが直ちに実行されます。
  3. 数分以内に、生成されたイベントが Dynatrace 環境に表示されます。
• データを表示するには、Experience Vitals > Overview > Mobile > フロントエンドを選択します。
• Grail で DQL を使ってデータを直接クエリすることもできます。
• 高度な設定オプションについては、次を参照してください：https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/ios/id-03-configuration

重要な注意事項

• このスキルが対象とするのは SPM 統合のみ です。CocoaPods とフレームワークの手動統合はサポートされていません。
• ユーザーから明示的な依頼がない限り、DTX の設定キーを追加しないでください。既定値は、初回の利用に適したエクスペリエンスを実現できるよう最適化されています。
• このセットアップの公開ドキュメントはこちらです：https://docs.dynatrace.com/docs/observe/digital-experience/new-rum-experience/mobile-frontends/ios/id-01-initial-setup