iOS SDK

2026년 3월 10일에 업데이트됨

circle-check
circle-info

Notice

현재 CocoaPods을 통한 설치는 지원하지 않습니다. 추후 Swift Package Manager 지원이 제공될 예정입니다

iOS SDK 설치하기

핑거푸시 링크 iOS SDK는 아래 방법으로 설치할 수 있습니다.

1. 핑거푸시 링크 iOS SDK를 다운로드합니다.

file-archive
309KB

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 키] 에서 확인할 수 있습니다.

triangle-exclamation

딥링크

이 문서에서 FINGERPUSH.LINK 딥링크는 이하 'FP 딥링크'로 표기합니다.

링크 생성 시 모바일 딥링크를 설정하면, 사용자가 해당 링크를 클릭했을 때 앱이 실행되며 지정한 화면으로 이동하도록 할 수 있습니다.

딥링크 설정하기

FP 딥링크를 사용하기 위해 먼저 핑거푸시 링크 대시보드에서 앱을 추가하고, 딥링크 설정을 진행합니다.

chevron-right1. 앱 추가하기hashtag

핑거푸시 링크 대시보드arrow-up-right에서 아래 경로로 이동하여 앱을 추가합니다.

[모바일 앱] > [앱 관리] > [새 앱 추가] > iOS 플랫폼 선택

필수 정보 입력

Team ID : 애플 개발자 대시보드arrow-up-right의 멤버십 세부 사항에서 팀 ID 값을 가져와서 입력하거나, 애플 개발자 프로그램 리소스arrow-up-right의 앱의 [Identifier]에서 App ID Prefix(팀 ID) 값을 가져와서 입력해주세요.

Bundle ID : 애플 개발자 프로그램 리소스arrow-up-right의 앱의 [Identifier]에서 Bundle ID 값을 가져와서 입력해주세요.

앱 스킴(App Scheme) : 앱에서 사용하는 URL 스킴을 입력합니다.

앱 스토어 URL : 앱이 설치되지 않은 경우 이동할 App Store 주소를 입력합니다.

FP 딥링크로 앱이 실행될 수 있도록, 앱에서 딥링크 설정을 진행합니다.

chevron-right2 딥링크 설정하기hashtag

스킴 딥링크 앱 설정

1. Xcode에서 [YOUR_PROJECT] > [Info] > [URL Types]로 이동합니다.

2. '+'를 클릭한 후에 URL Schemes에 핑거푸시 링크 대시보드에서 입력한 iOS URL 스킴을 입력합니다.

triangle-exclamation

유니버셜 링크 앱 설정

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 는 딥링크로 앱이 실행될 때 호출해야 합니다.

  • SceneDelegate와 AppDelegate가 모두 있는 경우: SceneDelegate에서 호출

  • AppDelegate만 있는 경우: AppDelegate에서 호출

  • SwiftUI를 사용하는 경우: App 클래스(onOpenURL)에서 호출

URL Scheme으로 오픈되는 경우 application:open:options:

유니버셜 링크로 오픈되는 경우 application:continue:restorationHandler:

해당 콜백에서 handleDeeplink 함수를 호출하여 딥링크 오픈 이벤트를 수집하고 setDeeplinkCallback 함수를 통해서 유저를 이동시키세요.

circle-info

Notice

handleDeeplink 는 FP 딥링크인 경우 true를 반환하고, 변환된 링크 정보를 setDeeplinkCallback 함수로 전달합니다.

FP 딥링크가 아닌 경우 false를 반환하며, SDK 처리는 수행되지 않습니다.

setDeeplinkCallback 고객 화면 이동을 자동으로 수행하지 않습니다.

콜백으로 전달된 링크 정보를 기반으로 앱에서 직접 화면 이동을 구현해야 합니다.


디퍼드 딥링크 설정하기

앱이 설치되지 않은 상태에서 디퍼드 딥링크가 설정된 FP 딥링크를 클릭하면, 해당 딥링크 정보가 서버에 저장됩니다. 이후 앱이 설치되고 처음 실행될 때, SDK를 통해 저장된 딥링크 정보를 전달받을 수 있습니다.

handleDeferredDeeplink 를 호출하면, 저장된 딥링크 정보를 확인하고 콜백으로 전달합니다. 콜백으로 전달된 링크 정보를 이용해 유저를 원하는 화면으로 이동시켜주세요.

handleDeferredDeeplink 함수는 앱이 설치되고 처음으로 호출되었으면 true를 반환하고, SDK가 초기화되지 않았거나 handleDeferredDeeplink 함수를 처음으로 호출하는 것이 아닌 경우 false를 전달합니다.

triangle-exclamation

추가 설정하기

앱 내에서 FP 딥링크 활용하기

웹뷰 또는 푸시 메시지 URL 로드와 같이 링크를 여는 방식에 따라, FP 딥링크가 정상적으로 동작하지 않을 수 있습니다. (중간 페이지 이동, 앱스토어 연결, 클릭 추적 등)

이 경우 click 함수를 사용하여 앱 내에서 FP 딥링크를 정상적으로 처리할 수 있습니다 .

click 함수 사용 방법

click 함수는 전달된 URL이 FP 딥링크인지 확인하고, FP 딥링크인 경우 SDK를 통해 처리합니다.

click 함수는 두 가지 방식으로 결과를 제공합니다.

  1. onSuccess 콜백으로 결과를 받는 방식

    • 입력된 URL이 FP 딥링크인 경우 true 반환

    • 처리 완료 시 onSuccess 콜백으로 최종 URL 전달

    • 처리 실패 시 onFailure 콜백 호출

  2. setDeeplinkCallback 을 통해 결과를 받는 방식

    • 입력된 URL이 FP 딥링크인 경우 true 반환

    • 처리 완료 시 setDeeplinkCallback 으로 설정한 콜백을 통해 url과 schemeUrl 전달

    • 처리 실패 시 onFailure 콜백 호출

입력된 URL이 FP 딥링크가 아닌 경우 false를 반환하며, SDK에서 처리를 수행하지 않습니다.


웹뷰에서 딥링크 처리하기

웹뷰는 기본적으로 딥링크 실행을 지원하지 않기 때문에, 웹뷰 내에서 FP 딥링크를 클릭하는 경우 의도와 다르게 동작할 수 있습니다.

이 경우 click 함수를 호출하여 SDK가 딥링크 처리를 대신 수행하도록 설정해야 합니다.

WKWebView에서 webView(_:decidePolicyFor:decisionHandler:) 를 구현하면, 특정 URL이 로드되는 시점에 해당 URL을 확인하고 로딩 여부를 제어할 수 있습니다.

이 메서드에서 click 함수를 호출해 FP 딥링크 여부를 확인하고, FP 딥링크인 경우 웹뷰 로딩을 중단하고 앱 내 이동을 처리합니다.