Flutter 튜토리얼 19편: 딥 링킹 설정

요약#

핵심 요지#

문제 정의: URL을 클릭했을 때 앱의 특정 화면으로 바로 이동하는 기능이 필요하다.
핵심 주장: Flutter의 딥 링킹¹으로 URL과 앱 화면을 연결할 수 있다.
주요 근거: Android App Links²와 iOS Universal Links³ 설정으로 플랫폼별 딥 링킹을 구현한다.
실무 기준: go_router 패키지와 함께 사용하면 라우팅 관리가 편리하다.
한계: 웹 도메인 소유와 서버 설정이 필요하다.

문서가 설명하는 범위#

딥 링킹 기본 개념
Android App Links 설정
iOS Universal Links 설정
go_router로 딥 링크 처리
테스트와 검증 방법

읽는 시간: 18분 | 난이도: 중급

참고 자료#

Deep linking - 딥 링킹 개요
Set up app links - Android 설정
Set up universal links - iOS 설정
go_router package - 라우팅 패키지

문제 상황#

사용자가 광고, 이메일, 메시지의 링크를 클릭하면 앱의 특정 화면으로 바로 이동해야 합니다. 예를 들어 상품 링크를 클릭하면 앱이 열리고 해당 상품 페이지가 표시되어야 합니다.

딥 링킹 사용 사례#

1
마케팅 캠페인 → 특정 프로모션 페이지
2
이메일 알림 → 주문 상세 페이지
3
SNS 공유 → 콘텐츠 상세 페이지
4
검색 결과 → 앱 내 해당 페이지

문제는 다음과 같습니다.

플랫폼별로 다른 설정이 필요하다 (Android/iOS).
웹 도메인과 앱을 연결해야 한다.
앱이 실행 중일 때와 종료 상태일 때 모두 처리해야 한다.
URL 경로를 앱 화면으로 매핑해야 한다.

해결 방법#

Flutter는 Android App Links와 iOS Universal Links를 지원하며, go_router로 쉽게 구현할 수 있습니다.

챕터 1: 딥 링킹 기본 개념#

Why#

NOTE
딥 링킹은 단순히 앱을 여는 것이 아니라, 앱 내부의 특정 위치로 바로 이동합니다.
”딥(deep)“은 앱의 깊은 곳까지 직접 접근한다는 의미입니다.
1
일반 링크: https://example.com/product/123 → 웹 브라우저
2
딥 링크: https://example.com/product/123 → 앱 → 상품 123 화면

What#

NOTE
딥 링킹에는 두 가지 주요 유형이 있습니다.

유형 설명 예시
URL 스킴 앱 전용 커스텀 스킴 myapp://product/123
App Links/Universal Links 도메인 기반 검증된 링크 https://example.com/product/123
App Links/Universal Links가 더 안전하고 권장됩니다.

유형	설명	예시
URL 스킴	앱 전용 커스텀 스킴	`myapp://product/123`
App Links/Universal Links	도메인 기반 검증된 링크	`https://example.com/product/123`

How#

TIP
Flutter 딥 링킹 흐름
graph TD A[URL 클릭] --> B{앱 설치?} B -->|예| C[앱 열기] B -->|아니오| D[웹페이지 표시] C --> E{앱 상태?} E -->|종료| F[앱 시작 + 라우팅] E -->|실행 중| G[라우팅만] F --> H[특정 화면 표시] G --> H
플랫폼별 동작

플랫폼 앱 종료 상태 앱 실행 중
iOS initialRoute + 딜레이 후 라우팅 pushRoute 호출
Android 전체 경로가 initialRoute pushRoute 호출

플랫폼	앱 종료 상태	앱 실행 중
iOS	initialRoute + 딜레이 후 라우팅	pushRoute 호출
Android	전체 경로가 initialRoute	pushRoute 호출

Watch out#

WARNING
URL 스킴(myapp://)은 다른 앱이 가로챌 수 있어 보안에 취약합니다.
App Links/Universal Links는 도메인 소유권 검증을 통해 이 문제를 해결합니다.
1
// ❌ 보안 취약: 다른 앱도 같은 스킴 등록 가능
2
myapp://product/123
3

4
// ✅ 보안 강화: 도메인 소유권 검증 필요
5
https://example.com/product/123

결론: App Links(Android)와 Universal Links(iOS)를 사용하면 보안과 사용자 경험이 향상됩니다.

챕터 2: go_router로 라우팅 설정#

Why#

NOTE
딥 링킹을 처리하려면 URL 경로를 앱 화면으로 매핑해야 합니다.
go_router 패키지는 선언적 라우팅과 딥 링킹을 쉽게 통합합니다.
1
URL 경로 → go_router → 해당 화면 위젯

What#

NOTE
go_router는 Flutter 팀이 추천하는 라우팅 패키지입니다.
URL 기반 네비게이션, 딥 링킹, 리다이렉션 등을 지원합니다.

How#

TIP

go_router 설치

1
dependencies:
2
  go_router: ^14.0.0

기본 라우터 설정

1
import 'package:flutter/material.dart';
2
import 'package:go_router/go_router.dart';
3

4
void main() => runApp(const MyApp());
5

6
class MyApp extends StatelessWidget {
7
  const MyApp({super.key});
8

9
  @override
10
  Widget build(BuildContext context) {
11
    return MaterialApp.router(
12
      title: '딥링크 데모',
13
      routerConfig: _router,
14
    );
15
  }
16
}
17

18
final _router = GoRouter(
19
  routes: [
20
    GoRoute(
21
      path: '/',
22
      builder: (context, state) => const HomeScreen(),
23
      routes: [
24
        GoRoute(
25
          path: 'product/:id',
26
          builder: (context, state) {
27
            final productId = state.pathParameters['id']!;
28
            return ProductScreen(productId: productId);
29
          },
30
        ),
31
        GoRoute(
32
          path: 'category/:name',
33
          builder: (context, state) {
34
            final categoryName = state.pathParameters['name']!;
35
            return CategoryScreen(categoryName: categoryName);
36
          },
37
        ),
38
        GoRoute(
39
          path: 'settings',
40
          builder: (context, state) => const SettingsScreen(),
41
        ),
42
      ],
43
    ),
44
  ],
45
);
46

47
class HomeScreen extends StatelessWidget {
48
  const HomeScreen({super.key});
49

50
  @override
51
  Widget build(BuildContext context) {
52
    return Scaffold(
53
      appBar: AppBar(title: const Text('홈')),
54
      body: ListView(
55
        children: [
56
          ListTile(
57
            title: const Text('상품 1'),
58
            onTap: () => context.go('/product/1'),
59
          ),
60
          ListTile(
61
            title: const Text('전자제품 카테고리'),
62
            onTap: () => context.go('/category/electronics'),
63
          ),
64
          ListTile(
65
            title: const Text('설정'),
66
            onTap: () => context.go('/settings'),
67
          ),
68
        ],
69
      ),
70
    );
71
  }
72
}
73

74
class ProductScreen extends StatelessWidget {
75
  const ProductScreen({super.key, required this.productId});
76

77
  final String productId;
78

79
  @override
80
  Widget build(BuildContext context) {
81
    return Scaffold(
82
      appBar: AppBar(title: Text('상품 $productId')),
83
      body: Center(
84
        child: Text('상품 ID: $productId'),
85
      ),
86
    );
87
  }
88
}

라우트 경로 패턴

패턴	예시 URL	설명
`/path`	`/settings`	정적 경로
`/path/:param`	`/product/123`	경로 파라미터
`/path?key=value`	`/search?q=flutter`	쿼리 파라미터

Watch out#

WARNING
중첩 라우트에서 전체 경로를 사용해야 합니다.
context.go()는 절대 경로, context.push()는 스택에 추가합니다.
1
// 중첩 라우트 구조
2
GoRoute(
3
  path: '/',
4
  routes: [
5
    GoRoute(path: 'product/:id', ...), // 전체 경로: /product/123
6
  ],
7
)
8

9
// ❌ 상대 경로 사용 불가
10
context.go('product/123'); // 에러
11

12
// ✅ 절대 경로 사용
13
context.go('/product/123'); // OK

결론: go_router로 URL 경로를 화면에 매핑하고, 경로 파라미터로 데이터를 전달합니다.

챕터 3: Android App Links 설정#

Why#

NOTE
Android App Links를 설정하면 HTTPS URL이 자동으로 앱을 엽니다.
사용자에게 “앱으로 열기” 선택 대화상자가 표시되지 않습니다.
1
https://example.com/product/123 → 앱이 바로 열림 (대화상자 없음)

What#

NOTE
App Links 설정에는 두 가지가 필요합니다.

AndroidManifest.xml에 intent filter 추가

웹 서버에 assetlinks.json 파일 호스팅

How#

TIP

1. AndroidManifest.xml 수정

android/app/src/main/AndroidManifest.xml 파일의 <activity> 태그 안에 추가:

1
<manifest ...>
2
    <application ...>
3
        <activity ...>
4
            <!-- 기존 intent-filter -->
5

6
            <!-- App Links intent filter 추가 -->
7
            <intent-filter android:autoVerify="true">
8
                <action android:name="android.intent.action.VIEW" />
9
                <category android:name="android.intent.category.DEFAULT" />
10
                <category android:name="android.intent.category.BROWSABLE" />
11
                <data android:scheme="https" android:host="example.com" />
12
            </intent-filter>
13
        </activity>
14
    </application>
15
</manifest>

2. assetlinks.json 생성

웹 서버의 /.well-known/assetlinks.json 경로에 파일 생성:

1
[{
2
  "relation": ["delegate_permission/common.handle_all_urls"],
3
  "target": {
4
    "namespace": "android_app",
5
    "package_name": "com.example.myapp",
6
    "sha256_cert_fingerprints": [
7
      "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"
8
    ]
9
  }
10
}]

SHA256 지문 얻기

1
# 디버그 키스토어 (개발용)
2
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
3

4
# 릴리스 키스토어 (배포용)
5
keytool -list -v -keystore your-release-key.keystore -alias your-alias

파일 검증

브라우저에서 https://example.com/.well-known/assetlinks.json 접근 가능해야 합니다.

Watch out#

WARNING
android:autoVerify="true"가 없으면 일반 딥 링크로 작동합니다.
앱 선택 대화상자가 표시될 수 있습니다.
1

2
<intent-filter>
3
    <action android:name="android.intent.action.VIEW" />
4
    ...
5
</intent-filter>
6

7

8
<intent-filter android:autoVerify="true">
9
    <action android:name="android.intent.action.VIEW" />
10
    ...
11
</intent-filter>
또한 sha256_cert_fingerprints가 실제 앱 서명과 일치해야 합니다.

결론: AndroidManifest.xml에 intent filter를 추가하고, 웹 서버에 assetlinks.json을 호스팅합니다.

챕터 4: iOS Universal Links 설정#

Why#

NOTE
iOS Universal Links를 설정하면 HTTPS URL이 Safari 대신 앱을 엽니다.
웹사이트와 앱 간의 원활한 전환이 가능합니다.
1
https://example.com/product/123 → 앱이 바로 열림

What#

NOTE
Universal Links 설정에는 세 가지가 필요합니다.

Xcode에서 Associated Domains 설정

Info.plist 수정 (Flutter 3.27 이전)

웹 서버에 apple-app-site-association 파일 호스팅

How#

TIP
1. Xcode에서 Associated Domains 설정

Xcode에서 ios/Runner.xcworkspace 열기

Runner 타겟 선택 → Signing & Capabilities 탭

”+ Capability” 클릭 → Associated Domains 추가

applinks:example.com 추가

2. Info.plist 설정 (Flutter 3.27 이전 버전)
ios/Runner/Info.plist에 추가:
1
<key>FlutterDeepLinkingEnabled</key>
2
<true/>
3. apple-app-site-association 파일 생성
웹 서버의 /.well-known/apple-app-site-association 경로에 파일 생성:
1
{
2
  "applinks": {
3
    "apps": [],
4
    "details": [
5
      {
6
        "appID": "TEAMID.com.example.myapp",
7
        "paths": [
8
          "/product/*",
9
          "/category/*",
10
          "/settings"
11
        ]
12
      }
13
    ]
14
  }
15
}
Team ID 찾기
Apple Developer 포털 → Account → Membership → Team ID
앱 ID 형식: TEAMID.bundleIdentifier 예: ABC123XYZ.com.example.myapp
파일 검증

확장자 없이 저장 (.json 아님)

Content-Type: application/json

HTTPS로만 접근 가능해야 함

Watch out#

WARNING
paths 배열이 너무 광범위하면 원하지 않는 URL도 앱으로 열릴 수 있습니다.
1
// ❌ 모든 경로가 앱으로 열림
2
{
3
  "paths": ["*"]
4
}
5

6
// ✅ 필요한 경로만 지정
7
{
8
  "paths": [
9
    "/product/*",
10
    "/category/*",
11
    "/NOT /admin/*"  // 제외할 경로
12
  ]
13
}
/NOT 패턴으로 특정 경로를 제외할 수 있습니다.

결론: Xcode에서 Associated Domains를 설정하고, 웹 서버에 apple-app-site-association을 호스팅합니다.

챕터 5: 딥 링크 테스트#

Why#

NOTE
설정이 올바른지 실제 기기에서 테스트해야 합니다.
시뮬레이터/에뮬레이터와 실제 기기에서 동작이 다를 수 있습니다.
1
설정 완료 → 빌드 → 테스트 → 검증

What#

NOTE
테스트 방법은 플랫폼별로 다릅니다.
ADB 명령어(Android)나 Safari(iOS)를 사용하여 테스트합니다.

How#

TIP
Android 테스트
Terminal window
1
# 앱 먼저 설치
2
flutter run
3

4
# ADB로 딥 링크 테스트
5
adb shell am start \
6
  -a android.intent.action.VIEW \
7
  -c android.intent.category.BROWSABLE \
8
  -d "https://example.com/product/123" \
9
  com.example.myapp
iOS 테스트

실제 기기에 앱 설치

Safari에서 URL 입력: https://example.com/product/123

또는 메모 앱에서 링크 탭

웹 테스트
Terminal window
1
flutter run -d chrome
2
# 브라우저 주소창에 직접 입력
3
http://localhost:port/#/product/123
Flutter DevTools로 검증
Terminal window
1
flutter pub global activate devtools
2
flutter pub global run devtools
DevTools → Deep Links 탭에서 설정 검증

Watch out#

WARNING
앱 링크 검증은 앱이 설치된 후에만 작동합니다.
테스트 전에 반드시 앱을 먼저 설치하세요.
Terminal window
1
# ❌ 앱 미설치 상태에서 테스트 → 웹으로 이동
2
adb shell am start -d "https://example.com/product/123"
3

4
# ✅ 앱 설치 후 테스트
5
flutter run  # 먼저 앱 설치
6
adb shell am start -d "https://example.com/product/123"  # 앱으로 열림
또한 디버그 빌드와 릴리스 빌드의 서명 키가 다르므로 각각 테스트해야 합니다.

결론: 앱 설치 후 플랫폼별 방법으로 딥 링크를 테스트하고, DevTools로 설정을 검증합니다.

챕터 6: 앱 상태별 딥 링크 처리#

Why#

NOTE
앱이 종료된 상태와 실행 중인 상태에서 딥 링크 처리가 다릅니다.
두 가지 경우를 모두 처리해야 완전한 딥 링킹이 구현됩니다.
1
앱 종료 상태: 앱 시작 → 라우팅
2
앱 실행 중: 현재 화면에서 라우팅

What#

NOTE
go_router는 두 가지 상태를 자동으로 처리합니다.
추가적인 로직이 필요하면 redirect나 리스너를 사용합니다.

How#

TIP

go_router의 자동 처리

1
final _router = GoRouter(
2
  routes: [...],
3
  // 초기 경로 설정 (앱 시작 시)
4
  initialLocation: '/',
5
  // 에러 페이지
6
  errorBuilder: (context, state) => ErrorScreen(error: state.error),
7
);

리다이렉션 추가

1
final _router = GoRouter(
2
  routes: [...],
3
  redirect: (context, state) {
4
    final isLoggedIn = authService.isLoggedIn;
5
    final isLoggingIn = state.matchedLocation == '/login';
6

7
    // 로그인 필요한 페이지 보호
8
    if (!isLoggedIn && !isLoggingIn) {
9
      return '/login?redirect=${state.matchedLocation}';
10
    }
11

12
    // 로그인 후 원래 페이지로
13
    if (isLoggedIn && isLoggingIn) {
14
      final redirect = state.uri.queryParameters['redirect'];
15
      return redirect ?? '/';
16
    }
17

18
    return null; // 리다이렉션 없음
19
  },
20
);

딥 링크 리스너

1
class MyApp extends StatefulWidget {
2
  const MyApp({super.key});
3

4
  @override
5
  State<MyApp> createState() => _MyAppState();
6
}
7

8
class _MyAppState extends State<MyApp> {
9
  @override
10
  void initState() {
11
    super.initState();
12
    // 앱 실행 중 딥 링크 처리
13
    _router.routerDelegate.addListener(_onRouteChanged);
14
  }
15

16
  void _onRouteChanged() {
17
    final location = _router.routerDelegate.currentConfiguration.fullPath;
18
    print('현재 경로: $location');
19
    // 분석 이벤트 전송 등
20
  }
21

22
  @override
23
  void dispose() {
24
    _router.routerDelegate.removeListener(_onRouteChanged);
25
    super.dispose();
26
  }
27

28
  @override
29
  Widget build(BuildContext context) {
30
    return MaterialApp.router(routerConfig: _router);
31
  }
32
}

딥 링크로 전달된 데이터 처리

1
GoRoute(
2
  path: '/product/:id',
3
  builder: (context, state) {
4
    final productId = state.pathParameters['id']!;
5
    final referrer = state.uri.queryParameters['ref'];
6

7
    // 분석: 어디서 왔는지 추적
8
    if (referrer != null) {
9
      analytics.logDeepLinkOpen(productId: productId, referrer: referrer);
10
    }
11

12
    return ProductScreen(productId: productId);
13
  },
14
)

Watch out#

WARNING

딥 링크로 접근한 화면에서 뒤로가기 동작을 고려해야 합니다.
스택이 비어있으면 앱이 종료될 수 있습니다.

1
// 딥 링크로 직접 접근 시 홈 화면이 스택에 없음
2
// 뒤로가기 → 앱 종료
3

4
// 해결: ShellRoute로 기본 구조 유지
5
GoRouter(
6
  routes: [
7
    ShellRoute(
8
      builder: (context, state, child) => ScaffoldWithNav(child: child),
9
      routes: [
10
        GoRoute(path: '/', ...),
11
        GoRoute(path: '/product/:id', ...),
12
      ],
13
    ),
14
  ],
15
)
16

17
// 또는 PopScope로 뒤로가기 제어
18
PopScope(
19
  canPop: false,
20
  onPopInvoked: (didPop) {
21
    if (!didPop) {
22
      context.go('/'); // 홈으로 이동
23
    }
24
  },
25
  child: ProductScreen(...),
26
)

결론: go_router가 앱 상태별 딥 링크를 자동 처리하고, redirect로 인증 흐름을 제어합니다.

한계#

딥 링킹에는 몇 가지 한계가 있습니다.

도메인 소유 필요: App Links/Universal Links는 웹 도메인 소유와 서버 설정이 필요합니다.
캐싱 지연: iOS는 apple-app-site-association 파일을 캐싱하여 업데이트 반영이 느릴 수 있습니다.
테스트 어려움: 시뮬레이터에서 완전한 테스트가 어렵고 실제 기기가 필요합니다.
플랫폼 제약: 각 플랫폼의 정책과 설정 요구사항이 다릅니다.

Deep Linking(딥 링킹): URL을 통해 앱의 특정 화면으로 직접 이동하는 기능이다. ↩
App Links(앱 링크): Android에서 HTTPS URL을 앱과 연결하는 기능이다. 도메인 소유권 검증이 필요하다. ↩
Universal Links(유니버설 링크): iOS에서 HTTPS URL을 앱과 연결하는 기능이다. Associated Domains 설정이 필요하다. ↩

Flutter 튜토리얼 19편: 딥 링킹 설정

요약#

핵심 요지#

문서가 설명하는 범위#

참고 자료#

문제 상황#

딥 링킹 사용 사례#

해결 방법#

챕터 1: 딥 링킹 기본 개념#

Why#

What#

How#

Watch out#

챕터 2: go_router로 라우팅 설정#

Why#

What#

How#

Watch out#

챕터 3: Android App Links 설정#

Why#

What#

How#

Watch out#

챕터 4: iOS Universal Links 설정#

Why#

What#

How#

Watch out#

챕터 5: 딥 링크 테스트#

Why#

What#

How#

Watch out#

챕터 6: 앱 상태별 딥 링크 처리#

Why#

What#

How#

Watch out#

한계#

Footnotes#

공유

목차