📱 Mobile SDK API

모바일 앱에서 딥링크 매칭, 클릭 추적, 퍼널 이벤트를 처리하는 API입니다.

ℹ️ 인증 방식

모든 Mobile SDK API 요청에는 다음 헤더가 필요합니다:

X-App-ID: 앱 등록 시 발급된 App ID
X-Mobile-App-API-Key: 앱 등록 시 발급된 API Key

딥링크 매칭 API

앱이 실행될 때 딥링크 정보를 조회하여 적절한 화면으로 이동시킵니다.

GET /api/v1/sdk/mobile/deeplink/match

토큰 기반으로 딥링크 정보를 매칭합니다. 앱이 딥링크 URL로 실행될 때 사용합니다.

쿼리 파라미터

파라미터	타입	필수	설명
token	String	✅	딥링크 토큰

cURL

curl -X GET "https://fplink.net/api/v1/sdk/mobile/deeplink/match?token=abc123" \
  -H "X-App-ID: your-app-id" \
  -H "X-Mobile-App-API-Key: your-api-key"

JSON — 성공 응답

{
  "scheme": "myapp://product/12345",
  "originalUrl": "https://example.com/product/12345",
  "url": {
    "id": 12345,
    "alias": "product-link"
  }
}

GET /api/v1/sdk/mobile/deeplink/resolve-fingerprint

핑거프린트 기반으로 딥링크를 매칭합니다. 앱 설치 후 최초 실행 시 디퍼드 딥링크(Deferred Deep Link)에 사용됩니다.

쿼리 파라미터

파라미터	타입	필수	설명
userAgent	String	✅	기기 User-Agent
ipAddress	String	✅	클라이언트 IP 주소
resolution	String		화면 해상도 (예: 1920x1080)
osVersion	String		OS 버전

GET /api/v1/sdk/mobile/deeplink/resolve-shorturl/**

단축 URL 코드로 원본 URL과 딥링크 정보를 조회합니다.

cURL

# 일반 URL
GET /api/v1/sdk/mobile/deeplink/resolve-shorturl/abc123

# 앱 경로 포함
GET /api/v1/sdk/mobile/deeplink/resolve-shorturl/myapp/abc123

GET /api/v1/sdk/mobile/deeplink/resolve-campaign/**

캠페인 별칭으로 원본 URL과 캠페인 정보를 조회합니다.

JSON

{
  "originalUrl": "https://example.com/summer-sale",
  "campaign": {
    "id": 567,
    "name": "여름 프로모션",
    "alias": "summer2026"
  },
  "customerId": "cid-12345"
}

POST /api/v1/sdk/mobile/deeplink/funnel/track

딥링크 퍼널 이벤트를 추적합니다. 사용자의 전환 과정을 단계별로 기록합니다.

요청 본문

필드	타입	필수	설명
sessionId	String	✅	세션 ID
stage	String	✅	퍼널 단계 (아래 표 참조)
timestamp	String		이벤트 발생 시각
goalType	String		목표 유형
goalValue	String		목표 값
platform	String		플랫폼 (IOS, ANDROID)
deviceType	String		기기 유형
urlId	Long		관련 URL ID
campaignId	Long		관련 캠페인 ID
externalUserId	String		외부 사용자 식별자

퍼널 단계 (stage)

단계	설명
CLICKED	링크 클릭
STORE_VISITED	앱스토어 방문
APP_INSTALLED	앱 설치 완료
APP_OPENED	앱 실행
DEEP_LINK_RESOLVED	딥링크 매칭 완료
GOAL_COMPLETED	목표 달성 (구매, 가입 등)

클릭 추적 API

모바일 앱 내에서 발생하는 클릭 이벤트를 기록합니다.

POST /api/v1/sdk/mobile/clicks/url

단축 URL 클릭 이벤트를 기록합니다.

요청 본문

필드	타입	필수	설명
shortCode	String	✅	단축 URL 코드
deviceInfo	Object		기기 정보 (platform, os, browser 등)

JSON

{
  "clickId": 98765,
  "originalUrl": "https://example.com/product/12345",
  "mobileTargetUrl": "https://m.example.com/product/12345"
}

POST /api/v1/sdk/mobile/clicks/campaign

캠페인 클릭 이벤트를 기록합니다.

요청 본문

필드	타입	필수	설명
campaignAlias	String	✅	캠페인 별칭
trackerAlias	String		추적 별칭
customId	String		커스텀 ID
deviceInfo	Object		기기 정보

링크 연결 API

FingerPush SDK와의 링크 연결(Association)을 처리합니다.

POST /api/v1/sdk/mobile/links/{shortCode}/associations

단축 URL에 FingerPush 식별 정보를 연결합니다.

요청 본문

필드	타입	필수	설명
tokenidx	String	✅	FingerPush 토큰 인덱스
identify	String	✅	사용자 식별자

쿼리 파라미터

파라미터	타입	설명
type	String	링크 유형 (url 또는 campaign)

POST /api/v1/sdk/mobile/links/{appPath}/{shortCode}/associations

앱 경로가 포함된 단축 URL에 FingerPush 식별 정보를 연결합니다.

커스텀 도메인 API

Mobile SDK에서 커스텀 도메인 정보를 조회합니다.

메서드	경로	설명
GET	/api/v1/sdk/mobile/custom-domains	도메인 목록 (페이징)
GET	/api/v1/sdk/mobile/custom-domains/{id}	특정 도메인 조회
POST	/api/v1/sdk/mobile/custom-domains/{id}/verify	도메인 검증
GET	/api/v1/sdk/mobile/custom-domains/verified	검증된 도메인 목록 (앱 조직 기반)

← Service API

Web SDK API →