メインコンテンツまでスキップ
バージョン: 4.6.1

インストールおよび初期化

このガイドは、NetFUNNEL iOSエージェントをアプリケーションに統合するための必須設定手順を説明します。

事前要件​

システム要件​

構成要素バージョン備考
iOS12+アクティブなiOSデバイスの99%を含む
StoryboardObjective-C, SwiftUIKitベースの開発用
SwiftUI互換性ありSwiftUIベースの開発用

ステップ1: SDKダウンロード​

1.1 NetFUNNELコンソールからダウンロード​

iOS Agent SDK Download placement

  1. NetFUNNELコンソールにログイン
  2. 移動: エージェント → モバイルエージェント → iOS
  3. クリック: "Traffic Control Installation File"ボタン
  4. ZIPファイルダウンロード: netfunnel-ios-agent-{{version}}.zip

1.2 ファイル抽出​

  1. ZIPファイルを抽出して以下を取得します: 
    netfunnel-ios-agent-{{version}}/
    ├── netfunnel-ios-agent-debug/
    │   └── netfunnel_ios.xcframework    // (開発用)
    └── netfunnel-ios-agent-release/
        └── netfunnel_ios.xcframework    // (プロダクション用)
ビルドタイプ
  • 開発: debug xcframeworkを使用
  • プロダクション: release xcframeworkを使用

ステップ2: 依存関係の追加​

2.1 フレームワークの追加​

  1. プロジェクトルートにFrameworksフォルダを作成 (.xcodeprojファイルと同じレベル)

  2. 適切なxcframeworkをFrameworks/にコピー:

    プロジェクト構造:

    your-project/
    ├── YourProject/
    │   ├── AppDelegate.swift
    │   └── ...
    ├── Frameworks/
    │   └── netfunnel_ios.xcframework   // (debugまたはreleaseフォルダから)
    └── YourProject.xcodeproj

  3. Xcodeでフレームワークを登録:

    • Project Navigatorでプロジェクトを選択
    • General → Frameworks, Libraries, and Embedded Contentに移動
    • **+**をクリック → Add Files… → netfunnel_ios.xcframeworkを選択
    • Addをクリック
    • EmbedをEmbed & Signに設定

iOS Agent Framework Import Result

フレームワーク登録

フレームワークが疑問符(?)なしで表示されることを確認してください。疑問符が表示される場合は、右クリック → Source Control → Add netfunnel_ios.xcframework

2.2 App Transport Securityの構成 (必要な場合)​

NetFUNNELサーバーがHTTPSの代わりにHTTPを使用する場合にのみ必要です。

Info.plistが隠されているプロジェクト用

  1. Project Navigatorでアプリターゲットを選択
  2. Infoタブに移動
  3. 既存の行を右クリック → Add Row
  4. "App Transport Security Settings"を入力 → Dictionaryに設定
  5. App Transport Security Settingsを展開 → Add Row
  6. "Allow Arbitrary Loads"を入力 → "YES"に設定 (Boolean)
プロダクション安全性

プロダクションビルドの場合、App Store審査拒否を避けるために、特定のサーバードメインと共にNSExceptionDomainsを使用してください。

2.3 設定確認​

  1. プロジェクトクリーン: Product → Clean Build Folder (⌘+Shift+K)
  2. プロジェクトビルド: Product → Build (⌘+B)

ステップ3: エージェントの初期化​

3.1 NetfunnelHandlerクラスの作成​

NetFUNNELを初期化する前に、デリゲートメソッド用の専用ハンドラークラスを作成してください:

  1. NetfunnelHandlerファイルの作成:
  • Xcodeでプロジェクトを右クリック
  • New File → Swift Fileを選択
  • NetfunnelHandlerと名前を付ける
  • プロンプトが表示されたらプロジェクトターゲットに追加
ファイル登録必須

重要: NetfunnelHandler.swiftを作成した後、プロジェクトターゲットに登録する必要があります。Xcodeがターゲットに追加するかどうかを尋ねます - アプリターゲットのチェックボックスを選択する必要があります。

ファイルの場所

NetfunnelHandler.swiftをAppDelegate.swiftと一緒にメインアプリフォルダに配置してください。

  1. ハンドラー実装の追加:
//  NetfunnelHandler.swift
import Foundation
import Netfunnel_iOS

class NetfunnelHandler: NSObject, NetfunnelDelegate {
    static let shared = NetfunnelHandler()
    
    var onSuccess: ((String, String, Int, String) -> Void)?
    var onError: ((String, String, Int, String) -> Void)?
    var onNetworkError: ((String, String, Int, String) -> Void)?
    var onContinue: ((String, String, Int, String, Int, Int, String, Int) -> Void)?
    var onBlock: ((String, String, Int, String) -> Void)?
    var onClose: ((String, String, Int, String) -> Void)?
    var onComplete: ((String, String, Int, String) -> Void)?
    
    private override init() {
        super.init()
    }
    
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onSuccess?(projectKey, segmentKey, statusCode, message)
    }
    
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onError?(projectKey, segmentKey, statusCode, message)
    }
    
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onNetworkError?(projectKey, segmentKey, statusCode, message)
    }
    
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String,
                    aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        onContinue?(projectKey, segmentKey, statusCode, message, aheadWait, behindWait, waitTime, progressRate)
    }
    
    func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onBlock?(projectKey, segmentKey, statusCode, message)
    }
    
    func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onClose?(projectKey, segmentKey, statusCode, message)
    }
    
    func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        onComplete?(projectKey, segmentKey, statusCode, message)
    }
}

3.2 NetFUNNELコンソールから初期化コードを取得​

  1. NetFUNNELコンソールにログイン
  2. 移動: エージェント → モバイルエージェント → iOS
  3. 実際のサーバーURLが含まれた初期化コードをコピー

iOS Agent Initialization Code from NetFUNNEL Console

3.3 AppDelegateで初期化​

重要: 最初に初期化する必要がある

メソッドの開始部分でapplication(_:didFinishLaunchingWithOptions:)に初期化してください。このステップを省略すると = バイパスモード (保護なし)。

3.3.1 プロジェクトタイプの確認​

  • UIKitプロジェクト: ✅ すでにAppDelegateがある - 3.3.3にスキップ
  • SwiftUIプロジェクト: ⚠️ AppDelegateを作成する必要がある - 3.3.2に従ってください

3.3.2 AppDelegateの作成 (SwiftUIのみ)​

AppDelegateファイルの作成

  • Xcodeでプロジェクトを右クリック
  • New File → Swift Fileを選択
  • AppDelegateと名前を付ける

SwiftUIに接続

メインAppファイル(例: YourAppNameApp.swift)を開いて以下を追加してください:

// YourAppNameApp.swift
import SwiftUI

@main
struct YourAppNameApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

3.3.3 初期化コードの追加​

NetFUNNELコンソールから初期化コードをコピーしてAppDelegateファイルに追加してください:

  1. コンソールからコピー: NetFUNNELコンソールからコピーした初期化コードを使用 (3.2)
  2. AppDelegateに追加: application(_:didFinishLaunchingWithOptions:)メソッドに貼り付け

AppDelegate.swiftを開いてapplication(_:didFinishLaunchingWithOptions:)メソッドに初期化コードを追加してください:

// AppDelegate.swift
import UIKit
import Netfunnel_iOS

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        // ここにNetFUNNELコンソール初期化コードを貼り付けてください
        Netfunnel.initialize(
            clientId: "{{CLIENT_ID}}",
            delegate: self // デリゲートを指定されたデリゲートオブジェクトまたは'self'に設定します
        )
        
        return true
    }
}

3.3.4 初期化パラメータの修正​

変更する必要がある重要な事項:

  1. delegateパラメータの変更:

    • コンソールコード: delegate: self (Swift) または delegate:self (Objective-C)
    • 次に変更: delegate: NetfunnelHandler.shared (Swift) または delegate:[NetfunnelHandler sharedInstance] (Objective-C)

  2. テスト用にデバッグロギングを有効化:

    • 変更: printLog: false → printLog: true
    • 目的: デバッグのためにXcode ConsoleでNetFUNNELログを確認

修正されたAppDelegateコード:

// AppDelegate.swift - 修正版
import UIKit
import Netfunnel_iOS

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        Netfunnel.initialize(
            clientId: "{{CLIENT_ID}}",
            delegate: NetfunnelHandler.shared  // 'self'から変更
        )
        
        return true
    }
}
プロダクション設定

より良いパフォーマンスとセキュリティのために、プロダクションビルドでprintLog: falseに設定することを覚えておいてください。

実際のクライアントIDを使用

プレースホルダー{{CLIENT_ID}}をNetFUNNELコンソールの実際のクライアントIDに置き換えてください。

高度: 例外処理​

プロダクションアプリの場合、try-catchエラー処理を追加してprintLog: falseに設定してください:

import UIKit
import Netfunnel_iOS

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        do {
            try Netfunnel.initialize(
                clientId: "{{CLIENT_ID}}",
                delegate: NetfunnelHandler.shared
            )
        } catch {
            print("NetFUNNEL initialization failed: \(error)")
            // エラー処理: エラー画面を表示またはアプリを終了
        }
        
        return true
    }
}

必須パラメータ​

パラメータタイプ必須説明
clientIdStringはいNetFUNNELコンソールから提供されるクライアントID
delegateNetfunnelDelegateはいプロトコルを実装するデリゲートオブジェクト
バイパスモード

clientIdの欠落 = バイパスモード (待合室保護なし)

より多くの構成オプション

networkTimeout、retryCount、printLogなどの追加初期化パラメータについては、初期化オプションリファレンスを参照してください。

ステップ4: ビルドおよびインストール確認​

SDK設定および初期化を完了したので、プロジェクトをビルドしてNetFUNNELが正しく動作することを確認します。

4.1 プロジェクトビルド​

同期およびビルド​

  1. プロジェクトクリーン

    • Product → Clean Build Folderに移動
    • クリーン完了を待つ

  2. プロジェクトビルド

    • ⌘+Bを押すかProduct → Buildに移動
    • Issue Navigatorでエラーを監視

ビルド成功確認​

  1. ビルド出力確認

    • Issue Navigatorにコンパイルエラーがないことを確認
    • 成功したフレームワークリンクメッセージを確認
    • NetFUNNELフレームワークが正しく含まれていることを確認

  2. 依存関係確認

    • Project Navigatorでプロジェクトを展開
    • netfunnel_ios.xcframeworkがリストされていることを確認
    • フレームワークが疑問符なしで表示されることを確認

4.2 NetFUNNEL初期化テスト​

デバッグロギングの有効化​

NetFUNNELが正しく初期化されることを確認するには、AppDelegateで一時的にデバッグロギングを有効にしてください:

デバッグロギングの無効化

より良いパフォーマンスとセキュリティのために、プロダクションビルドでprintLog = falseに設定することを覚えておいてください。

//  AppDelegate.swift
Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: NetfunnelHandler.shared
)

コンソール出力の監視​

  1. コンソールを開く

    • View → Debug Area → Activate Console (⌘+Shift+Y)に移動
    • または下部パネルのConsoleタブをクリック

  2. NetFUNNELログのフィルタリング

    • コンソールフィルタフィールドにNetFUNNELを入力してNetFUNNELログでフィルタリング
    • これにより、NetFUNNEL関連のログメッセージのみが表示されます

  3. アプリの実行

    • デバイスまたはシミュレーターでアプリを実行
    • Consoleで初期化成功メッセージを確認:
    [NF4] Initialization successful. NetFUNNEL Version: {{version}}

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

インストールまたは初期化中に問題が発生した場合、以下の一般的な問題に対する詳細な解決方法を含む包括的なトラブルシューティング & FAQガイドを参照してください:

  • インストール問題: フレームワークローディング、プロジェクト構成、ビルド設定
  • 初期化問題: エージェントが初期化されない、デリゲート登録、バイパスモード
  • 関数呼び出しエラー: 初期化エラー、コールバック問題、コンテキスト問題
  • ネットワークおよび接続問題: タイムアウトエラー、接続問題、サーバー通信
  • ビルドおよび環境問題: Xcode構成、iOSバージョン互換性

一般的な問題に対する即座のヘルプ:

  1. コンソール確認: NetFUNNELでフィルタリングして詳細ログを確認
  2. 構成確認: すべての設定がNetFUNNELコンソールと一致することを再確認
  3. シンプルな設定でテスト: まず基本構成で開始
  4. クライアントID確認: クライアントIDがNetFUNNELコンソールのものと一致することを確認