fplink_flutter 1.0.0-alpha01

FpLink SDK for Flutter

Fplink Flutter SDK

Fplink SDK는 플러터 앱에서 딥링크(Deep Link), 지연된 딥링크(Deferred Deep Link), 그리고 웹 링크 트래킹 기능을 강력하고 안정적으로 제공하는 공식 플러그인입니다.

✅ 요구 사항 (Requirements)

• Dart SDK: >= 3.0.0
• Flutter SDK: >= 3.10.0
• Android: minSdk 23 (Android 6.0) 이상
• iOS: iOS 13.0 이상

---

📦 설치 (Installation)

flutter pub add fplink_flutter

---

⚙️ 필수 설정 (Native Configuration)

Fplink SDK가 딥링크를 안전하게 가로채어 분석하기 위해, 플러터 엔진의 기본 딥링크 자동 라우팅 기능을 반드시 비활성화해야 합니다.

Android 설정 (AndroidManifest.xml)

android/app/src/main/AndroidManifest.xml 파일을 열고 <application> 태그 내부에 아래 값을 추가하세요.

<application ...>
    <!-- Fplink SDK 처리를 위해 Flutter 기본 딥링크 자동 라우팅 비활성화 -->
    <meta-data android:name="flutter_deeplinking_enabled" android:value="false" />
</application>

iOS 설정 (Info.plist)

ios/Runner/Info.plist 파일을 열고 <dict> 태그 내부에 아래 키를 추가해 주세요.

<dict>
    <!-- Fplink SDK 처리를 위해 Flutter 기본 딥링크 자동 라우팅 비활성화 -->
    <key>FlutterDeepLinkingEnabled</key>
    <false/>
</dict>

---

🚀 초기화 (Native Initialization)

앱 실행 시 딥링크 유실을 원천 차단하기 위해, SDK 초기화는 반드시 네이티브(Android/iOS) 코드 최상단에서 진행해야 합니다.

Android (Application 클래스)

android/app/src/main/kotlin/.../MainApplication.kt 에서 초기화합니다.

import kr.co.tracking.fplink.TrackingSdk
import kr.co.tracking.fplink.data.FplinkOptionsBuilder

class MainApplication : FlutterApplication() {
    override fun onCreate() {
        super.onCreate()

        FplinkFlutter.initialize(
            application = this,
            appId = "YOUR_APP_ID",
            apiKey = "YOUR_API_KEY"
        )
    }
}

iOS (AppDelegate.swift)

ios/Runner/AppDelegate.swift 에서 초기화합니다.

import fplink_flutter

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
  
    FplinkFlutterPlugin.initialize(appId: "YOUR_APP_ID", apiKey: "YOUR_API_KEY")

    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

---

💻 사용 방법 (Dart Usage)

초기화가 완료되면, 플러터(Dart) 환경에서는 직관적인 API를 통해 기능을 사용할 수 있습니다.

1. 딥링크 리스너 등록 (중앙 핸들러)

앱의 첫 화면(initState)에 리스너를 등록하여 모든 딥링크 이벤트를 한 곳에서 수신합니다.

import 'dart:async';
import 'package:fplink_flutter/fplink_flutter.dart';

StreamSubscription? _deeplinkSub;

@override
void initState() {
  super.initState();
  
  // 일반 딥링크, 지연된 딥링크, 클릭 트래킹 결과가 모두 이쪽으로 수신됩니다.
  _deeplinkSub = Fplink.setOnDeeplinkReceived((data) {
    print("🔗 딥링크 수신 URL: ${data.link}");
    print("🔗 딥링크 스킴: ${data.scheme}");
    // TODO: Navigator 등을 통한 화면 이동 로직 작성
  });
}

@override
void dispose() {
  _deeplinkSub?.cancel(); // 메모리 누수 방지
  super.dispose();
}

2. 웹뷰 클릭 트래킹 (WebView Interception)

webview_flutter 등에서 링크 이동을 가로채어 SDK에 분석을 맡깁니다.

NavigationDelegate(
  onNavigationRequest: (request) async {
    // SDK가 트래킹 도메인인지 확인 후 처리 (비동기)
    final isHandled = await Fplink.click(request.url);
    
    if (isHandled) {
      return NavigationDecision.prevent; // 우리 링크이므로 웹뷰 로딩 중단
    }
    return NavigationDecision.navigate; // 일반 링크 허용
  },
)