iOS エージェント適用

インストール前の要件

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

iOS 15.0以上
Xcode 15.0以上
Swift 5.9以上 または Objective-C

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

エージェントは次の3つの方法でインストールできます。

Swift Package Managerを利用した自動インストール方式(推奨)
XCFrameworkを利用した手動インストール方式
ローカルファイルを利用した閉域網インストール方式

方法1: Swift Package Manager (SPM)、推奨

Xcodeでプロジェクトを開き、File → Add Package Dependenciesを選択します。
パッケージURLを入力します。

https://github.com/whatap/WhatapIOSAgent-Release
バージョン2.7.3以上を選択し、Add Packageをクリックします。

方法2: 手動XCFrameworkインストール

XCFrameworkをダウンロードします。

curl -O https://repo.whatap-mobile-agent.io/uploads/2.7.3/WhatapAgent.xcframework.zip
unzip WhatapAgent.xcframework.zip

Xcodeプロジェクトに追加します。
- プロジェクトターゲットを選択 → Generalタブ
- Frameworks, Libraries, and Embedded Contentセクションへ移動
- **+**ボタン → Add Other → Add Files
- WhatapAgent.xcframeworkを選択
- Embed & Signが設定されていることを確認

方法3: ローカルファイルインストール(閉域網・社内網)

外部リポジトリへのアクセスが制限された環境では、WhaTapが提供するzipファイルをダウンロードし、解凍してプロジェクトに追加します。その後は方法2と同様に、XcodeでEmbed & Signとして追加します。

unzip whatap-ios-agent-2.7.3.zip
mv WhatapAgent.xcframework /path/to/YourApp/

エージェント初期化

WhaTap iOS SDKは、アプリの性能データを収集するためにアプリ起動時に初期化する必要があります。SDK初期化はアプリが開始される際に最も早く実行されるべきで、これによりアプリのライフサイクル全体で発生するイベントを追跡できます。

ノート

初期化タイミング

SwiftUI: @main structのinit() - アプリ構造体が生成される時点
UIKit: application:willFinishLaunchingWithOptions: - didFinishLaunchingより前に呼び出される

初期化のタイミングが遅れると、アプリ起動初期の重要な性能データ(pre-main時間、初期メモリ使用量など)を逃す可能性があります。

Swift

SwiftUIアプリでは@main structのinit()でSDKを初期化します。

import SwiftUI
import WhatapAgent

@main
struct MyApp: App {
    init() {
        // 起動時にSDKを初期化
        let agent = WhatapAgentBuilder()
            .setProjectKey("<YOUR_PROJECT_ACCESS_KEY>")
            .setPCode(<YOUR_PCODE>)
            .setServerUrl("<YOUR_SERVER_URL>")
            .build()
        
        agent.initialize()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

UIKitベースのアプリでは、AppDelegateのapplication:willFinishLaunchingWithOptions:でSDKを初期化することを推奨します。

import UIKit
import WhatapAgent

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, 
                    willFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        // 最も早いタイミングでSDKを初期化(推奨)
        let agent = WhatapAgentBuilder()
            .setProjectKey("<YOUR_PROJECT_ACCESS_KEY>")
            .setServerUrl("<YOUR_SERVER_URL>")
            .setPCode(<YOUR_PCODE>)
            .build()
        
        agent.initialize()
        
        return true
    }
}

Objective-C

willFinishLaunchingWithOptionsを使用(推奨)

AppDelegate.m
#import "AppDelegate.h"
@import WhatapAgent;

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application 
    willFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // didFinishLaunchingより前に実行されるSDK初期化
    WhatapAgentBuilder *builder = [[WhatapAgentBuilder alloc] init];
    [builder setProjectKey:@"<YOUR_PROJECT_ACCESS_KEY>"];
    [builder setServerUrl:@"<YOUR_SERVER_URL>"];
    [builder setPCode:<YOUR_PCODE>];
    
    WhatapIOSAgent *agent = [builder build];
    [agent initialize];
    
    return YES;
}
@end

Builderオプション

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

setFlushInterval(_:): 10.0秒
setQueueSize(_:): 1,000
setMaxDiskBytes(_:): 500 × 1024
setMaxDiskFiles(_:): 5

収集・HTTPオプション

注意

ネットワーク収集はopt-inです

iOS SDK 2.7.3から、自動ネットワーク収集のデフォルト値はfalseです。有効にするとURLProtocolを通してリクエストが計測されるため、証明書のpinning・カスタムのURLSessionDelegate・独自のCookieや認証ヘッダー・HTTP/2ネゴシエーションに依存するアプリは、まず影響を確認してください。セキュリティに敏感なリクエストは、別途カスタムのURLSessionに分離することを推奨します。

setCollectScreenLoading(_:): true
setCollectNetwork(_:): false
setKeepAlive(_:): true
setMaxConnectionsPerHost(_:): 4

カスタムendpoint

setLogServerUrl(_:): serverUrl + "/log"
setSpanServerUrl(_:): serverUrl + "/trace"

ScreenGroupおよび追跡オプション

setGroupWaitingInterval(_:): 3.0秒
setExcludeLifecycleEventsFromScreenGroup(_:): false
enableMethodTracing(_:): false
setSamplingRate(_:): 1.0

WhatapAgentBuilder()
    .setFlushInterval(120)
    .setMaxDiskBytes(2 * 1024 * 1024)
    .setMaxDiskFiles(5)
    .setQueueSize(1000)
    .setKeepAlive(true)
    .setMaxConnectionsPerHost(4)
    .setGroupWaitingInterval(3.0)
    .build()

自動収集項目

アプリ起動性能(Cold/Warm start、pre-main)
UIViewControllerのライフサイクルに基づく画面遷移および画面ごとのロード時間
クラッシュ・例外・シグナル、CPU・メモリ・バッテリー・熱状態

画面追跡

Swift
final class CheckoutViewController: UIViewController {
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        WhatapIOSAgent.trackViewController(self)
    }
}

struct CheckoutView: View {
    var body: some View {
        ContentView()
            .onAppear {
                WhatapIOSAgent.trackViewController(UIHostingController(rootView: self))
            }
    }
}

Objective-C
- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [WhatapIOSAgent trackViewController:self];
}

手動連携

手動Task API

決済や画像ロードのように、1つの画面内の非同期処理を個別のspanとして記録できます。

WhatapIOSAgent.startTask("checkout", taskId: "task-001")
WhatapIOSAgent.endTask("task-001")

Method Tracing

Method Tracingはopt-in機能です。SDK初期化時のBuilderにenableMethodTracing(true)を追加した後、必要なメソッドの性能を記録してください。

methodStart / methodEnd

func validateBiometric(
    agent: WhatapIOSAgent,
    validate: () throws -> Void
) rethrows {
    agent.methodStart(className: "AuthService", methodName: "validateBiometric")
    defer {
        agent.methodEnd(className: "AuthService", methodName: "validateBiometric")
    }

    try validate()
}

StackSpan

func charge(
    agent: WhatapIOSAgent,
    operation: () async throws -> Void
) async rethrows {
    let stackSpan = agent.start(className: "PaymentService", methodName: "charge")

    do {
        try await operation()
        stackSpan.end()
    } catch {
        stackSpan.endWithError(error)
        throw error
    }
}

グローバルコンテキスト

ExtrasStoreの値は、すべてのログとspanに自動的に付与されます。

Swift
import WhatapAgent

ExtrasStore.shared.setExtra(key: "user_id", value: userId)
ExtrasStore.shared.removeExtra(key: "user_id")
ExtrasStore.shared.clearExtras()

Objective-C
[[ExtrasStore shared] setExtraValue:userId forKey:@"user_id"];

Tips

ExtrasStoreに保存したキーは、Androidとの互換性のため、送信時に自動的に.cサフィックスが付与されます。例: user_id → user_id.c

ChainView
ChainView.shared.startChain(chainName: "LoginFlow")

ChainView.shared.endChain()

ネットワーク & クラッシュ

ネットワークセキュリティ設定

HTTPS収集endpointにはApp Transport Securityの例外設定は不要です。レガシーなHTTP endpointをどうしても使用する必要がある場合は、必要な単一ドメインにのみ個別の例外を適用し、サブドメインや任意のロードは許可しないでください。

クラッシュレポーティング

クラッシュは自動的に収集され、次回のアプリ実行時に送信されます。組み込みのレポーターがデフォルトで、PLCrashReporterを使用する場合は別途ライブラリが必要です。

WhatapAgentBuilder()
    .useNativeCrashReporter()
    .build()

WhatapAgentBuilder()
    .usePLCrashReporter()
    .build()

インストール確認とデバッグ

アプリ実行後、Xcode Consoleで初期化ログを確認してください。データが収集されない場合は、プロジェクトキー・PCode・サーバーURL、initialize()の呼び出し、サンプリング比率とディスクバッファを確認してください。

#if DEBUG
WhatapLogger.isDebug = true
#endif

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

トラブルシューティング

SDK初期化失敗

SDK初期化が失敗する場合は、次の事項を確認してください。

プロジェクトキーとPCodeの確認: 正しい値が設定されているか確認します。
ネットワーク接続状態の確認: デバイスがインターネットに接続されているか確認します。
サーバーURLが正しいか確認: 提供された収集サーバーアドレスが正しいか確認します。

データが収集されない

モニタリングデータがダッシュボードに表示されない場合は、次の事項を確認してください。

サンプリング比率の確認: setSamplingRate(1.0)で100%収集されるよう設定されているか確認します。
Info.plistのネットワーク権限確認: App Transport Securityの設定が正しいか確認します。

クラッシュレポートが送信されない

クラッシュデータが収集されない場合は、次の事項を確認してください。

アプリを再起動する必要があります: クラッシュ発生後、アプリが再度実行される際に前回のクラッシュ情報が送信されます。
シミュレーターでは一部のクラッシュがキャプチャされない場合があります: 実機でのテストを推奨します。

サポート

問題が発生した場合は、次のチャネルでお問い合わせください。

メール: support@whatap.io
技術ドキュメント: https://docs.whatap.io

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

プロジェクトキー
iOSバージョン
Xcodeバージョン
SDKバージョン
エラーメッセージまたはログ
問題の再現方法

インストール前の要件​

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

方法1: Swift Package Manager (SPM)、推奨​

方法2: 手動XCFrameworkインストール​

方法3: ローカルファイルインストール(閉域網・社内網)​

エージェント初期化​

Swift​

Objective-C​

Builderオプション​

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

収集・HTTPオプション​

カスタムendpoint​

ScreenGroupおよび追跡オプション​

自動収集項目​

画面追跡​

手動連携​

手動Task API​

Method Tracing​

グローバルコンテキスト​

ネットワーク & クラッシュ​

ネットワークセキュリティ設定​

クラッシュレポーティング​

インストール確認とデバッグ​

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

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

SDK初期化失敗​

データが収集されない​

クラッシュレポートが送信されない​

サポート​