本文へスキップ

Android エージェント適用

インストール前の要件​

Androidエージェントをインストールする前に、次の要件を確認してください。

  • Android Min SDK 21以上
  • 対応環境: Android 5.0(API Level 21)+, Java 17+, Android Gradle Plugin 7.0 ～ 9.x, Gradle 7.0 ～ 8.x (AGP 9.xを使用する場合はGradle 8.xが必要です)
ノート

WhatapAgent Android SDK 2.3.0は、Androidアプリケーションの性能モニタリングのためのSDKです。Gradle Plugin 2.2.2を併用すると、追加のコードなしで自動収集が可能になります。

エージェントインストール​

AndroidにWhaTapモバイルエージェントをインストールするには、次の手順で進めます。

  • WhaTapモバイルエージェントのインストール手順: Gradle設定 → SDK初期化 → Builderオプション → Manifest設定 → ProGuard設定 → 対応収集項目 → 手動連携 → ScreenGroup設定

1. Gradle設定​

エージェントをインストールするには、プロジェクトのGradleファイルを修正する必要があります。プロジェクトがKotlin DSLを使用しているかGroovyを使用しているかによって設定方法が異なります。

Kotlin DSL​

Projectレベル build.gradle.kts
plugins {
    id("io.whatap.android") version "2.2.2" apply false
}
Appモジュール build.gradle.kts
plugins {
    id("com.android.application")
    id("io.whatap.android")
}

dependencies {
    implementation("io.whatap.android:whatap-android-agent:2.3.0")
}

Groovy​

Projectレベル build.gradle
plugins {
    id 'io.whatap.android' version '2.2.2' apply false
}
Appモジュール build.gradle
plugins {
    id 'com.android.application'
    id 'io.whatap.android'
}

dependencies {
    implementation 'io.whatap.android:whatap-android-agent:2.3.0'
}

2. ローカルAARファイル方式(閉域網・社内網)​

配布されたAARファイルはapp/libs/に、PluginのJARファイルは必要に応じてlibs/または社内Mavenリポジトリに配置します。Plugin JARを使用しない場合は、手動連携ガイドのAPIを呼び出して必要な箇所を計測してください。

Kotlin DSL (build.gradle.kts)​

アプリモジュール build.gradle.kts
dependencies {
    implementation(files("libs/whatap-android-agent-2.3.0.aar"))
}
任意: ローカルPlugin JAR​
ローカルPlugin JAR(プロジェクトレベル build.gradle.kts)
buildscript {
    dependencies {
        classpath(files("libs/whatap-android-plugin-2.2.2.jar"))
    }
}

Groovy​

アプリモジュール build.gradle
dependencies {
    implementation files('libs/whatap-android-agent-2.3.0.aar')
}

3. SDK初期化​

Androidアプリケーションの性能データを収集するために、SDKを初期化する必要があります。Applicationクラスで初期化することを推奨します。

Kotlin​

import android.app.Application
import io.whatap.android.agent.WhatapAgent

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        WhatapAgent.Builder.newBuilder()
            .setProjectKey("<YOUR_PROJECT_ACCESS_KEY>")
            .setServerUrl("<YOUR_SERVER_URL>")
            .setPCode(<YOUR_PCODE>)
            .build(this)
    }
}

Java​

import android.app.Application;
import io.whatap.android.agent.WhatapAgent;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        WhatapAgent.Builder.newBuilder()
            .setProjectKey("<YOUR_PROJECT_ACCESS_KEY>")
            .setServerUrl("<YOUR_SERVER_URL>")
            .setPCode(<YOUR_PCODE>)
            .build(this);
    }
}

4. Builderオプション​

すべてのBuilderオプションは任意であり、指定しない場合はデフォルト値が適用されます。

送信・バッファオプション​

  • setFlushIntervalMs(long): 10,000 ms
  • setMaxDiskBytes(int): 500 × 1024
  • setMaxDiskFiles(int): 5
  • setQueueSize(int): 1,000

収集トグル​

  • setCollectScreenLoading(boolean): true
  • setCollectNetwork(boolean): true
  • setCollectHeartbeat(boolean): true

HTTP接続オプション​

  • setKeepAliveEnabled(boolean): true
  • setMaxConnections(int): 5
  • setDisconnectAfterSend(boolean): false

ScreenGroupおよびユーザーオプション​

  • setScreenGroupDelaySeconds(int): 0秒
  • setExcludeLifecycleEventsFromScreenGroup(boolean): true
  • setUserId(String), setSessionId(String), setSampling(double)
WhatapAgent.Builder.newBuilder()
    .setFlushIntervalMs(60_000L)
    .setMaxDiskBytes(2 * 1024 * 1024)
    .setMaxDiskFiles(5)
    .setQueueSize(1000)
    .setKeepAliveEnabled(true)
    .setMaxConnections(5)
    .setDisconnectAfterSend(false)
    .build(this)
注意

利用が少ない時間帯のトラフィックを減らす: バックグラウンド状態でもheartbeatやリソースサンプラーが送信されることがあります。必要に応じてheartbeat収集をオフにするか、flush間隔を延ばしてサーバーへのリクエスト数を減らすことができます。

WhatapAgent.Builder.newBuilder()
    .setCollectHeartbeat(false)
    .setFlushIntervalMs(60_000L)
    .build(this)

5. Manifest設定​

AndroidManifest.xmlファイルに必要な権限とApplicationクラスを設定する必要があります。

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <application
        android:name=".MyApplication"
        ...>
    </application>
</manifest>

6. ProGuard設定​

# Activity/Fragment
-keep class * extends android.app.Activity
-keep class * extends androidx.fragment.app.Fragment
-keepclassmembers class * extends android.app.Activity {
    public void *(android.view.View);
}

# WebView JavaScript Interface
-keepclassmembers class * {
    @android.webkit.JavascriptInterface <methods>;
}

7. 対応収集項目​

  • Activity/Fragmentのライフサイクルおよび ScreenGroup
  • 対応ネットワーククライアントのリクエスト・レスポンス情報
  • リソース使用量、クラッシュおよびANR
  • WebViewのページロードおよび性能情報

8. 手動連携​

注意

setCollectNetwork(false)を指定すると、ネットワーク拡張モジュールが初期化されず、wrap()およびonRequest()の呼び出しが動作しません。手動ネットワーク連携ではデフォルト値のtrueを維持してください。

OkHttp3 / Retrofit​

import io.whatap.android.agent.instrumentation.okhttp.OkHttp3Instrumentation

val client = OkHttpClient.Builder()
    .connectTimeout(10, TimeUnit.SECONDS)
    .build()

val instrumentedClient = OkHttp3Instrumentation.wrap(client)

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(instrumentedClient)
    .build()

Volley​

import io.whatap.android.agent.instrumentation.volley.VolleyInstrumentation

val queue = Volley.newRequestQueue(this)
val request = StringRequest(Request.Method.GET, url, listener, errorListener)
queue.add(request)
VolleyInstrumentation.onRequest(request)

HttpURLConnection​

import io.whatap.android.agent.instrumentation.httpurlconnection.HttpUrlConnectionInstrumentation

val raw = URL(urlString).openConnection() as HttpURLConnection
val connection = HttpUrlConnectionInstrumentation.wrap(raw)
connection.requestMethod = "GET"

Apache HttpClient​

Apache HttpClientは自動収集の対象ではありません。Android 9(API 28)以上でDefaultHttpClientとHttpGetを使用するには、org.apache.http.legacyの使用宣言または代替の依存関係が必要です。この前提条件を適用できない場合は、対応しているネットワーククライアントを使用してください。

import io.whatap.android.agent.instrumentation.httpclient.ApacheHttpClientInstrumentation

val client = DefaultHttpClient()
val instrumentedClient = ApacheHttpClientInstrumentation.wrap(client)

val request = HttpGet(url)
val response = instrumentedClient.execute(request)

StackSpan​

import io.whatap.android.agent.instrumentation.stacktrace.CallStackTracer

val span = CallStackTracer.start("LoginService", "doLogin")
try {
    doLogin()
    span.end()
} catch (error: Exception) {
    span.endWithError(error)
    throw error
}

9. ScreenGroup設定​

危険

主な変更点: 既存のstartGroup() / addTask() / endGroup() APIがstartChain() / endChain()に置き換えられました。複数のActivityやFragmentにまたがるフローはstartChain()で開始し、終了画面で同じtaskIdを使ってendChain()を呼び出します。taskIdを省略すると自動生成され、getCurrentChainTaskId()で取得できます。

Kotlin​

import android.content.Intent
import io.whatap.android.agent.instrumentation.screengroup.ChainView

private const val EXTRA_CHAIN_TASK_ID = "whatap_chain_task_id"

class LoginActivity : AppCompatActivity() {
    private fun continueToConfirmation() {
        ChainView.getInstance().startChain("LoginFlow", null)
        val taskId = ChainView.getInstance().getCurrentChainTaskId() ?: return

        startActivity(Intent(this, ConfirmationActivity::class.java)
            .putExtra(EXTRA_CHAIN_TASK_ID, taskId))
    }
}

class ConfirmationActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        intent.getStringExtra(EXTRA_CHAIN_TASK_ID)?.let { taskId ->
            ChainView.getInstance().endChain(taskId)
        }
    }
}

チェーンの状態と自動終了の待機時間: isChainActive()で進行中のチェーンがあるかどうかを確認できます。画面間に短い空白があるフローは、終了待機時間を延ばして1つのグループとして維持してください。

val isChainActive = ChainView.getInstance().isChainActive()

WhatapAgent.Builder.newBuilder()
    .setScreenGroupDelaySeconds(3)
    .build(this)

トラブルシューティングとサポート​

トラブルシューティング​

Desugaring関連エラー​

Dependency 'io.whatap.android:whatap-android-agent:2.3.0' requires core library desugaring to be enabled for :app. エラーが発生した場合は、以下の設定を追加してください。

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
        isCoreLibraryDesugaringEnabled = true
    }
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.0")
}

Plugin not foundエラー​

Pluginが見つからないエラーが発生した場合、以下の設定を追加してください。

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

Javaバージョン関連エラー​

Javaバージョンに関連するエラーが発生した場合、以下の設定を確認してください。

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

Namespace警告​

Namespace 'io.whatap.android.agent' is used in multiple modules 警告は無視して構いません。これはライブラリが複数のモジュールで使用されていることを知らせる警告であり、アプリの実行には影響しません。

ビルドエラーが発生した場合​

  • GradleバージョンとAndroid Gradle Pluginバージョンが要件を満たしているか確認してください。
  • ネットワーク接続状態を確認し、プロキシ設定が必要な場合は設定してください。
  • プロジェクトのClean & Rebuildを試してください。

データが収集されない場合​

  • プロジェクトアクセスキーが正しく設定されているか確認してください。
  • AndroidManifest.xmlにインターネット権限が追加されているか確認してください。
  • Applicationクラスで SDK が正しく初期化されているか確認してください。
  • プロキシやファイアウォール設定によりデータ転送がブロックされていないか確認してください。

サポート​

技術サポートを依頼する際は、以下の情報を提供すると、より迅速な解決が可能です。

  • プロジェクトアクセスキー
  • Android SDKバージョン
  • GradleバージョンおよびAndroid Gradle Pluginバージョン
  • エラーログ全文
  • build.gradleファイル内容
  • 問題の再現方法
最終修正：