iOS SDK
2026년 3월 10일에 업데이트됨
iOS SDK v1.0.0-rc02 (호환성 정보)
iOS 15.0+
iOS SDK 설치하기
핑거푸시 링크 iOS SDK는 아래 방법으로 설치할 수 있습니다.
1. 핑거푸시 링크 iOS SDK를 다운로드합니다.
2. fplink.xcframework를 프로젝트에 추가합니다. [Xcode] > [프로젝트 파일] > [General] > [Frameworks, Libraries, and Embedded Content]에서 ‘+’를 클릭합니다.
3. [Add Other...]에서 ‘Add Files...’를 클릭하고 fplink.xcframework를 선택합니다.
4. fplink.xcframework의 Embed를 Do Not Embed로 설정합니다.
5. [Targets 프로젝트] > [Build Settings] > 'User Script Sandboxing' 값을 Yes로 변경합니다.
6. RunScript 를 추가합니다. [Targets 프로젝트] > [Build Phases] > '+' 클릭 > 'New RunScript Phase' 클릭 후 아래의 스크립트를 추가합니다.
SDK 초기화하기
시스템 방식에 따라 SDK 초기화 방법이 다릅니다. SceneDelegate Lifecycle 또는 AppDelegate Lifecycle은 AppDelegate를 참고해 주세요. SwiftUI Lifecycle는 SwiftUI를 참고해 주세요.
YOUR_APP_ID와 YOUR_MOBILE_APP_API_KEY은 핑거푸시 링크 대시보드의 [모바일 앱] > [앱 관리] > [API 키] 에서 확인할 수 있습니다.
주의하세요
Fplink.initialize 함수를 AppDelegate 의 application(_:didFinishLaunchingWithOptions:) 시점에 호출해야 올바르게 동작합니다.
딥링크
이 문서에서 FINGERPUSH.LINK 딥링크는 이하 'FP 딥링크'로 표기합니다.
링크 생성 시 모바일 딥링크를 설정하면, 사용자가 해당 링크를 클릭했을 때 앱이 실행되며 지정한 화면으로 이동하도록 할 수 있습니다.
딥링크 설정하기
FP 딥링크를 사용하기 위해 먼저 핑거푸시 링크 대시보드에서 앱을 추가하고, 딥링크 설정을 진행합니다.
1. 앱 추가하기
핑거푸시 링크 대시보드에서 아래 경로로 이동하여 앱을 추가합니다.
[모바일 앱] > [앱 관리] > [새 앱 추가] > iOS 플랫폼 선택
필수 정보 입력
Team ID : 애플 개발자 대시보드의 멤버십 세부 사항에서 팀 ID 값을 가져와서 입력하거나, 애플 개발자 프로그램 리소스의 앱의 [Identifier]에서 App ID Prefix(팀 ID) 값을 가져와서 입력해주세요.
Bundle ID : 애플 개발자 프로그램 리소스의 앱의 [Identifier]에서 Bundle ID 값을 가져와서 입력해주세요.
앱 스킴(App Scheme) : 앱에서 사용하는 URL 스킴을 입력합니다.
앱 스토어 URL : 앱이 설치되지 않은 경우 이동할 App Store 주소를 입력합니다.
FP 딥링크로 앱이 실행될 수 있도록, 앱에서 딥링크 설정을 진행합니다.
2 딥링크 설정하기
스킴 딥링크 앱 설정
1. Xcode에서 [YOUR_PROJECT] > [Info] > [URL Types]로 이동합니다.
2. '+'를 클릭한 후에 URL Schemes에 핑거푸시 링크 대시보드에서 입력한 iOS URL 스킴을 입력합니다.
주의하세요
://를 제외한 iOS URL 스킴을 입력해야 합니다.
유니버셜 링크 앱 설정
1. Xcode에서 [YOUR_PROJECT]>[Signing & Capabilities]로 이동합니다.
2. '+ Capability'를 클릭하면 Associated Domains를 추가할 수 있습니다.
3. Associated Domains에 핑거푸시 링크 대시보드의 [도메인 & 인프라] > [커스텀 도메인] 에서 사용하고자 하는 모든 도메인을 applinks:[도메인 이름] 형태로 추가합니다.
딥링크 처리하기
딥링크로 앱이 실행될 때, handleDeeplink 를 호출해 딥링크를 SDK로 전달하고 FP 딥링크 여부를 확인해주세요. handleDeeplink 를 통해 SDK는 딥링크 오픈 이벤트를 수집하며, FP 딥링크인 경우 해당 딥링크를 처리합니다.
FP 딥링크인 경우, SDK는 설정된 링크 정보를 조회하여 url과 schemeUrl을 가져옵니다.
가져온 값은 setDeeplinkCallback 으로 설정한 콜백으로 전달됩니다.
콜백으로 전달된 url 또는 schemeUrl을 이용해 유저를 원하는 화면으로 이동시켜주세요.
딥링크 처리 흐름
handleDeeplink 의 반환값 isFingerpushDeeplink 값이 true이면 FP 딥링크이며, 처리 성공/실패 여부는 onSuccess/onFailure 콜백으로 전달됩니다.
반환값이 false이면 FP 딥링크가 아니며, 이 경우 setDeeplinkCallback 및 성공/실패 콜백은 호출되지 않습니다.
이를 활용하면 FP 딥링크와 그 외 딥링크를 분리하여 처리할 수 있습니다
콜백 설정
setDeeplinkCallback 은 앱 시작 시점에 설정해야 합니다.
SceneDelegate와 AppDelegate가 모두 있는 경우: AppDelegate에서 설정
AppDelegate만 있는 경우: AppDelegate에서 설정
SwiftUI를 사용하는 경우: App 클래스에서 설정
handleDeeplink 호출
handleDeeplink 는 딥링크로 앱이 실행될 때 호출해야 합니다.
SceneDelegate와 AppDelegate가 모두 있는 경우: SceneDelegate에서 호출
AppDelegate만 있는 경우: AppDelegate에서 호출
SwiftUI를 사용하는 경우: App 클래스(onOpenURL)에서 호출
URL Scheme으로 오픈되는 경우 application:open:options:
유니버셜 링크로 오픈되는 경우 application:continue:restorationHandler:
해당 콜백에서 handleDeeplink 함수를 호출하여 딥링크 오픈 이벤트를 수집하고 setDeeplinkCallback 함수를 통해서 유저를 이동시키세요.
앱이 꺼지거나 백그라운드에 있는 상태에서
URL Scheme 또는 유니버셜 링크로 오픈되는 경우 scene:willConnectTo:options:
앱이 백그라운드에 있는 상태에서
URL 스킴으로 오픈되는 경우 scene:openURLContexts:
유니버셜링크로 오픈되는 경우 scene:continue:
해당 콜백에서 handleDeeplink 함수를 호출하여 딥링크 오픈 이벤트를 수집하고 setDeeplinkCallback 함수를 통해서 유저를 이동시키세요.
URL Scheme으로 오픈되는 경우 application:openURL:options:
유니버셜 링크로 오픈되는 경우 application:continueUserActivity:restorationHandler:
해당 콜백에서 handleDeeplink 함수를 호출하여 딥링크 오픈 이벤트를 수집하고 setDeeplinkCallback 함수를 통해서 유저를 이동시키세요.
앱이 꺼지거나 백그라운드에 있는 상태에서
URL Scheme 또는 유니버셜 링크로 오픈되는 경우 scene:willConnectToSession:options:
앱이 백그라운드에 있는 상태에서
URL 스킴으로 오픈되는 경우 scene:openURLContexts:
유니버셜링크로 오픈되는 경우 scene:continueUserActivity:
해당 콜백에서 handleDeeplink 함수를 호출하여 딥링크 오픈 이벤트를 수집하고 setDeeplinkCallback 함수를 통해서 유저를 이동시키세요.
앱이 꺼지거나 백그라운드에 있는 상태에서
URL Scheme 또는 유니버셜 링크 로 오픈되는 경우 onOpenURL
해당 콜백에서 handleDeeplink 함수를 호출하여 딥링크 오픈 이벤트를 수집하고 setDeeplinkCallback 함수를 통해서 유저를 이동시킬 수 있습니다.
Notice
handleDeeplink 는 FP 딥링크인 경우 true를 반환하고, 변환된 링크 정보를 setDeeplinkCallback 함수로 전달합니다.
FP 딥링크가 아닌 경우 false를 반환하며, SDK 처리는 수행되지 않습니다.
setDeeplinkCallback 고객 화면 이동을 자동으로 수행하지 않습니다.
콜백으로 전달된 링크 정보를 기반으로 앱에서 직접 화면 이동을 구현해야 합니다.
디퍼드 딥링크 설정하기
앱이 설치되지 않은 상태에서 디퍼드 딥링크가 설정된 FP 딥링크를 클릭하면, 해당 딥링크 정보가 서버에 저장됩니다. 이후 앱이 설치되고 처음 실행될 때, SDK를 통해 저장된 딥링크 정보를 전달받을 수 있습니다.
handleDeferredDeeplink 를 호출하면, 저장된 딥링크 정보를 확인하고 콜백으로 전달합니다. 콜백으로 전달된 링크 정보를 이용해 유저를 원하는 화면으로 이동시켜주세요.
handleDeferredDeeplink 함수는 앱이 설치되고 처음으로 호출되었으면 true를 반환하고, SDK가 초기화되지 않았거나 handleDeferredDeeplink 함수를 처음으로 호출하는 것이 아닌 경우 false를 전달합니다.
Warning
디퍼드 딥링크로 앱을 설치하고, 실행없이 딥링크로 앱을 열면 FP 딥링크는 디퍼드 딥링크 유무에 관계없이 null을 onSuccess에 전달해서 딥링크만 처리되도록 합니다.
추가 설정하기
앱 내에서 FP 딥링크 활용하기
웹뷰 또는 푸시 메시지 URL 로드와 같이 링크를 여는 방식에 따라, FP 딥링크가 정상적으로 동작하지 않을 수 있습니다. (중간 페이지 이동, 앱스토어 연결, 클릭 추적 등)
이 경우 click 함수를 사용하여 앱 내에서 FP 딥링크를 정상적으로 처리할 수 있습니다 .
click 함수 사용 방법
click 함수는 전달된 URL이 FP 딥링크인지 확인하고, FP 딥링크인 경우 SDK를 통해 처리합니다.
click 함수는 두 가지 방식으로 결과를 제공합니다.
onSuccess콜백으로 결과를 받는 방식입력된 URL이 FP 딥링크인 경우 true 반환
처리 완료 시
onSuccess콜백으로 최종 URL 전달처리 실패 시
onFailure콜백 호출
setDeeplinkCallback을 통해 결과를 받는 방식입력된 URL이 FP 딥링크인 경우 true 반환
처리 완료 시
setDeeplinkCallback으로 설정한 콜백을 통해 url과 schemeUrl 전달처리 실패 시
onFailure콜백 호출
입력된 URL이 FP 딥링크가 아닌 경우 false를 반환하며, SDK에서 처리를 수행하지 않습니다.
웹뷰에서 딥링크 처리하기
웹뷰는 기본적으로 딥링크 실행을 지원하지 않기 때문에, 웹뷰 내에서 FP 딥링크를 클릭하는 경우 의도와 다르게 동작할 수 있습니다.
이 경우 click 함수를 호출하여 SDK가 딥링크 처리를 대신 수행하도록 설정해야 합니다.
WKWebView에서 webView(_:decidePolicyFor:decisionHandler:) 를 구현하면, 특정 URL이 로드되는 시점에 해당 URL을 확인하고 로딩 여부를 제어할 수 있습니다.
이 메서드에서 click 함수를 호출해 FP 딥링크 여부를 확인하고, FP 딥링크인 경우 웹뷰 로딩을 중단하고 앱 내 이동을 처리합니다.
WWKWebView에서 webView(_:decidePolicyFor:decisionHandler:) 를 구현하면, 특정 URL이 로드되는 시점에 해당 URL을 확인하고 로딩 여부를 제어할 수 있습니다.
이 메서드에서 click 함수를 호출해 FP 딥링크 여부를 확인하고, FP 딥링크인 경우 웹뷰 로딩을 중단하고 앱 내 이동을 처리합니다.