dt-obs-android

Android Dynatrace インストルメンテーション

対象範囲： 基本的なセットアップのみです。ゼロから最初のイベントを送信するまでを扱います。初期インストルメンテーション以外の内容（カスタムアクション、クラッシュのグループ化、データプライバシーポリシーなど）については、Dynatrace のドキュメントを直接参照してください。

フェーズ 1：事前確認

ほかの作業を始める前に、settings.gradle.kts または settings.gradle があるかどうかを確認し、現在のディレクトリが Android プロジェクトのルートであることを確かめます。どちらも存在しない場合は、作業を中止して、ここは Android プロジェクトのルートではないことをユーザーに伝え、正しいディレクトリに移動するよう依頼してください。

次に、以下の最低要件を確認します。満たしていない要件がある場合は、作業を中止し、先にアップグレードが必要な項目をユーザーに知らせてください。

要件	最低バージョン
Gradle	7.0.2
Android Gradle Plugin（AGP）	7.0
JVM	Java 11

./gradlew --version（Windows では gradlew.bat --version）を実行します。出力には Gradle と、Gradle が実際に使用している JVM（Daemon JVM の行）の両方が表示されます。プロジェクトを Android Studio または IntelliJ で開いている場合、実際に使用される JVM はシステムの Java と異なることがあります。java -version は使用しないでください。ビルドで実際に使用される JDK とは別の JDK の情報が表示される場合があります。AGP のバージョンはルートのビルドファイルで宣言されています。

フェーズ 2：既存のセットアップを検出

ビルドファイル内のどこかに dynatrace { } ブロック、または configure<com.dynatrace.tools.android.dsl.DynatraceExtension> { } ブロック（クラスがインポートされている場合は configure<DynatraceExtension> { } と記述）が見つかったら、その内容を確認し、以下があれば値を抽出します。

• applicationId（applicationId(...) または applicationId '...' に渡される値）
• beaconUrl（beaconUrl(...) または beaconUrl '...' に渡される値）

これらを事前入力値として保存し、フェーズ 3 に引き継ぎます。いずれかの値がない場合、またはプレースホルダー（例：YOUR_APPLICATION_ID）が設定されている場合は、見つからなかったものとして扱います。フェーズ 3 に進みます。

フェーズ 3：入力情報を収集

まず、次の項目だけを尋ねます。

1. applicationId — Dynatrace アプリケーション ID です。作成済みのモバイルアプリ内にある Dynatrace テナントで確認できることをユーザーに伝えます。フェーズ 2 で値を抽出できた場合は現在の値を示し、確認または変更を依頼します。
2. beaconUrl — Dynatrace ビーコン URL です。同じモバイルアプリの設定内にある Dynatrace テナントで確認できることをユーザーに伝えます。同様に、抽出した値があれば表示し、確認または変更を依頼します。

ユーザーが両方の値を確認または入力したら、次に質問します。ただし、ユーザーが最初のリクエストですでにセッションリプレイの希望を伝えている場合は、この質問を省略し、その希望に従います。

1. セッションリプレイ — セッションリプレイを有効にしますか？（はい／いいえ）

フェーズ 4：ファイルを特定

アプリモジュールを見つける

アプリケーションモジュールの名前は、必ずしも app とは限りません。settings.gradle.kts または settings.gradle を読み込み、含まれるすべてのモジュールを確認してから、各モジュールのビルドファイルで com.android.application プラグインを探します。このプラグインを適用している最初のモジュールのディレクトリを、以下のすべてのパスで APP_MODULE として使用します。

macOS／Linux：

grep -r -l --include="*.gradle" --include="*.gradle.kts" --exclude-dir=buildSrc "com.android.application" .

Windows（cmd）：

findstr /s /m "com.android.application" *.gradle *.gradle.kts

Windows（PowerShell）：

Get-ChildItem -Recurse -Include "*.gradle","*.gradle.kts" | Select-String "com.android.application" | Select-Object -ExpandProperty Path

一致した行に apply false が含まれる結果は除外します。これらはルートのビルドファイルにあるバージョンカタログの宣言であり、実際のプラグイン適用ではありません。また、buildSrc/ 配下の結果も除外します。

フィルタリング後に com.android.application を適用しているモジュールが見つからない場合は、作業を中止して失敗を報告してください。この時点では、ファイルはまだ変更されていません。

編集前に読み込むファイル

• ルートの build.gradle.kts ／ build.gradle（settings ファイルと同じ階層）
• アプリの APP_MODULE/build.gradle.kts ／ APP_MODULE/build.gradle
• エントリーポイントのソースファイル — 以下を参照

エントリーポイントファイルを見つける

推奨：Application クラス。 OS に応じたコマンドを使用して、ソースツリー内で Application を継承するクラスを検索します。

macOS / Linux：

grep -r -l --include="*.java" "extends Application" APP_MODULE/src
grep -r -l --include="*.kt" ": Application()" APP_MODULE/src

Windows（cmd）：

findstr /s /m "extends Application" APP_MODULE\src\*.java
findstr /s /m ": Application()" APP_MODULE\src\*.kt

Windows（PowerShell）：

Get-ChildItem -Recurse -Path APP_MODULE/src -Include "*.java" | Select-String "extends Application" | Select-Object -ExpandProperty Path
Get-ChildItem -Recurse -Path APP_MODULE/src -Include "*.kt" | Select-String ": Application()" | Select-Object -ExpandProperty Path

見つかった場合は、そのファイルを使用します。super.onCreate() の後に、onCreate() 内でプライバシーのオプトイン呼び出しを追加します。

フォールバック：ランチャーアクティビティ。 Application クラスがない場合は、AndroidManifest.xml でランチャーアクティビティを見つけます。これは、次の内容を含む <activity> です。

<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />

そのアクティビティの android:name 属性を確認し、ソースファイルを特定して、setContentView(...) の後に onCreate() 内でプライバシーのオプトイン呼び出しを追加します。

ファイルが見つかったら、拡張子から言語を判定します：.kt = Kotlin、.java = Java。

ファイル名が MainActivity だと決めつけないでください。

フェーズ 5：計装する

以下の各手順では、書き込む前に対象の要素がすでに存在するか確認してください。要素が存在し、正しい場合はスキップします。存在するものの誤っている、または不完全な場合は、影響する値のみを更新します。存在しない場合は、すべて追加します。

ファイルを編集する前に、その元の内容を記録してください。何らかの理由（ビルドエラー、ファイルの欠落、解決できない競合、予期しないファイル構造など）で手順に失敗した場合は：

1. 直ちに停止します — それ以上の変更を試みないでください。
2. 失敗を報告します — どの手順が失敗したのか、またその理由を明確に伝えます。
3. すべての編集をロールバックします — このフェーズで変更したすべてのファイルを元の内容に戻します。ファイルを新規作成した場合は削除します。
4. ロールバックを確認します — 復元したファイルと、プロジェクトが元の状態に戻ったことをユーザーに伝えます。

計装が途中の状態でプロジェクトを残さないでください。

ルートビルドファイル

まず、ルートビルドファイルが build.gradle.kts（Kotlin DSL）か build.gradle（Groovy DSL）かを確認し、該当する構文を使用します。

com.dynatrace.instrumentation は、アプリモジュールではなく、ルートビルドファイルに適用する必要があります。

Kotlin DSL（build.gradle.kts）

クラスパス依存関係 — buildscript { dependencies { } } ブロックに com.dynatrace.tools.android:gradle-plugin がすでに記述されているか確認します。記述されていて、バージョン指定が 8.+ の場合はスキップします。記述されていて別のバージョンの場合は、バージョンを 8.+ に更新します。記述されていない場合は、既存の buildscript { dependencies { } } ブロックがあればそこにクラスパスを追加します。なければ、plugins {} ブロックの前に buildscript ブロック全体を追加します。

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("com.dynatrace.tools.android:gradle-plugin:8.+")
    }
}

プラグインの適用 — apply(plugin = "com.dynatrace.instrumentation") がすでに存在するか確認します。存在する場合はスキップします。存在しない場合は、plugins {} ブロックの後に追加します。

DynatraceExtension ブロック — configure<com.dynatrace.tools.android.dsl.DynatraceExtension> ブロックがすでに存在するか確認します。

• 存在する場合は、各フィールドを確認し、対象の値と異なるものだけを更新します：applicationId、beaconUrl、userOptIn(true)、agentBehavior.startupLoadBalancing(true)、agentBehavior.startupWithGrailEnabled(true)、および sessionReplay.enabled(true)（セッションリプレイが要求されている場合）。不足しているフィールドがあれば追加します。
• 存在しない場合は、プラグイン適用行の後にブロック全体を追加します。いずれの場合も、applicationId と beaconUrl をフェーズ 3 で確認した値に置き換えます。以下のプレースホルダーを残さないでください。

configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            autoStart {
                applicationId("YOUR_APPLICATION_ID")
                beaconUrl("https://your-tenant.live.dynatrace.com/mbeacon")
            }
            userOptIn(true)
            agentBehavior.startupLoadBalancing(true)
            agentBehavior.startupWithGrailEnabled(true)
            // only if session replay was requested:
            sessionReplay.enabled(true)
        }
    }
}

Groovy DSL（build.gradle）

クラスパスの依存関係 — buildscript { dependencies { } } ブロックに com.dynatrace.tools.android:gradle-plugin がすでに記述されているか確認します。記述されていて、バージョン指定が 8.+ の場合はスキップします。記述されていて、別のバージョンの場合は、バージョンを 8.+ に更新します。記述されていない場合は、既存の buildscript { dependencies { } } ブロック内にクラスパスを追加します。そのブロックがない場合は、apply 行の前に buildscript ブロック全体を作成します。

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'com.dynatrace.tools.android:gradle-plugin:8.+'
    }
}

プラグインの適用 — apply plugin: 'com.dynatrace.instrumentation' がすでに記述されているか確認します。記述されている場合はスキップします。記述されていない場合は、既存の apply 行の後、またはファイルの末尾に追加します。

dynatrace ブロック — dynatrace { } ブロックがすでに存在するか確認します。

• 存在する場合は、各フィールドを確認し、目標値と異なるものだけを更新します。対象は applicationId、beaconUrl、userOptIn true、agentBehavior.startupLoadBalancing true、agentBehavior.startupWithGrailEnabled true、および（セッションリプレイがリクエストされた場合）sessionReplay.enabled true です。不足しているフィールドがあれば追加します。
• 存在しない場合は、プラグインの適用行の後にブロック全体を追加します。どちらの場合も、applicationId と beaconUrl をフェーズ 3 で確認した値に置き換えます。以下のプレースホルダーをそのまま残さないでください。

dynatrace {
    configurations {
        sampleConfig {
            autoStart {
                applicationId 'YOUR_APPLICATION_ID'
                beaconUrl 'https://your-tenant.live.dynatrace.com/mbeacon'
            }
            userOptIn true
            agentBehavior.startupLoadBalancing true
            agentBehavior.startupWithGrailEnabled true
            // only if session replay was requested:
            sessionReplay.enabled true
        }
    }
}

エントリーポイントファイル（Application クラスまたはランチャーアクティビティ）

すでに存在しないインポートのみを追加します。プライバシーのオプトイン呼び出しについては、onCreate 内に Dynatrace.applyUserPrivacyOptions(...) がすでに存在するか確認します。存在する場合は、各オプション（DataCollectionLevel.USER_BEHAVIOR、withCrashReportingOptedIn(true)、セッションリプレイが有効な場合は withScreenRecordOptedIn(true)）を確認し、異なるものがあれば更新します。存在しない場合は、エントリーポイントの種類に応じた位置に挿入します。

• Application サブクラス — super.onCreate() の後
• ランチャーアクティビティ — setContentView(...) の後

Kotlin

インポート — すでに存在しないもののみを追加します。

import com.dynatrace.android.agent.Dynatrace
import com.dynatrace.android.agent.conf.DataCollectionLevel
import com.dynatrace.android.agent.conf.UserPrivacyOptions

プライバシーのオプトイン呼び出し — super.onCreate()（Application サブクラスの場合）または setContentView(...)（ランチャーアクティビティの場合）の後に挿入します。.withScreenRecordOptedIn(true) は、フェーズ 3 でセッションリプレイが有効になっている場合にのみ含めます。

Dynatrace.applyUserPrivacyOptions(
    UserPrivacyOptions.builder()
        .withDataCollectionLevel(DataCollectionLevel.USER_BEHAVIOR)
        .withCrashReportingOptedIn(true)
        // .withScreenRecordOptedIn(true) — add only if session replay is enabled
        .build()
)

Java

インポート — すでに存在しないもののみを追加します。

import com.dynatrace.android.agent.Dynatrace;
import com.dynatrace.android.agent.conf.DataCollectionLevel;
import com.dynatrace.android.agent.conf.UserPrivacyOptions;

プライバシーのオプトイン呼び出し — super.onCreate()（Application サブクラスの場合）または setContentView(...)（ランチャーアクティビティの場合）の後に挿入します。.withScreenRecordOptedIn(true) は、フェーズ 3 でセッションリプレイが有効になっている場合にのみ含めます。

Dynatrace.applyUserPrivacyOptions(UserPrivacyOptions.builder()
    .withDataCollectionLevel(DataCollectionLevel.USER_BEHAVIOR)
    .withCrashReportingOptedIn(true)
    // .withScreenRecordOptedIn(true) — add only if session replay is enabled
    .build()
);

フェーズ 6：ビルドと検証

まず、カスタムのビルドタイプやプロダクトフレーバーがあるプロジェクトに対応するため、利用可能な assemble タスクを確認します。

macOS / Linux：

./gradlew tasks --group=build | grep -i "^assemble"

Windows（cmd）：

gradlew.bat tasks --group=build | findstr /i "assemble"

Windows（PowerShell）：

.\gradlew.bat tasks --group=build | Select-String -Pattern "^assemble" -CaseSensitive:$false

assemble タスクが 1 つだけ表示される場合は、そのタスクを使用します。複数のタスクが表示される場合は、ユーザーに提示して、実行するタスクを尋ねます。

次に、タスクを実行します。

• macOS / Linux：./gradlew CHOSEN_TASK
• Windows（cmd）：gradlew.bat CHOSEN_TASK
• Windows（PowerShell）：.\gradlew.bat CHOSEN_TASK

ビルドが成功すれば、Dynatrace プラグインが正しく組み込まれていることを確認できます。