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://",
  "deepLinkUrl": "myapp://product/12345?id=abc",
  "iosDeepLinkPath": "/product/12345?id=abc",
  "androidDeepLinkPath": "/product/12345?id=abc",
  "originalUrl": "https://example.com/product/12345",
  "shorturl": "product-link"
}

딥링크 이동은 deepLinkUrl을 사용하세요. scheme과 경로를 앱에서 직접 이어 붙이면 경로의 쿼리스트링(?id=abc)이 인코딩되어 값이 전달되지 않을 수 있습니다.

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

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

참고중복 클릭 처리

같은 사용자(IP)가 같은 대상을 중복 제거 시간 안에 다시 클릭하면 집계되지 않습니다. 이때도 응답은 200이며 filtered: true가 내려오고 clickId는 없습니다. 이동에 필요한 값(originalUrl, mobileTargetUrl, 캠페인은 redirectUrl)은 그대로 내려오므로 앱 동작은 바꾸지 않아도 됩니다 — 클릭 ID를 저장하는 경우에만 null 처리를 확인하세요.

중복 제거 사용 여부와 시간(1분~요금제 상한)은 콘솔의 단축 URL·캠페인 설정에서 지정합니다. 꺼져 있으면 모든 호출이 집계됩니다.

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

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

요청 본문

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

JSON

{
  "success": true,
  "clickId": 12345,
  "filtered": false,
  "campaign": { "id": 42, "name": "봄 프로모션", "alias": "spring-sale" },
  "redirectUrl": "https://example.com/spring"
}

링크 연결 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

로그인 또는 회원가입 시 사용자 기본정보를 수집하고, 수신동의를 관리합니다. 모바일 앱에서도 웹 SDK와 동일한 엔드포인트를 사용하며 X-App-ID와 X-Mobile-App-API-Key 헤더가 필요합니다.

메서드	경로	설명
POST	/api/v1/cross-platform/identify	사용자 기본정보 수집 — externalUserId 기준 upsert
POST	/api/v1/cross-platform/opt-in	수신동의 업데이트 — identify 선행 필요

iOS Swift SDK 호출 예시

// 로그인 성공 후
FPLink.identify(
    externalUserId: user.id,
    name: user.name,
    phone: user.phone,
    email: user.email,
    pushIdentify: FPLink.getPushIdentify(),  // 핑거푸시 식별자
    pushOptIn: true,
    smsOptIn: user.smsConsent
)

// 마이페이지 수신동의 변경 시
FPLink.optIn(
    externalUserId: user.id,
    smsOptIn: false,
    emailAdOptIn: true
)

Android Kotlin SDK 호출 예시

// 로그인 성공 후
FPLink.identify(
    externalUserId = user.id,
    name = user.name,
    phone = user.phone,
    email = user.email,
    pushIdentify = FPLink.getPushIdentify(),
    pushOptIn = true,
    smsOptIn = user.smsConsent
)

// 마이페이지 수신동의 변경 시
FPLink.optIn(
    externalUserId = user.id,
    smsOptIn = false,
    emailAdOptIn = true
)

요청 파라미터 (identify)

필드	타입	필수	설명
externalUserId	String	필수	고객사 서비스의 회원 ID
name	String		이름
phone	String		전화번호 (AES-256 암호화 저장)
email	String		이메일 (AES-256 암호화 저장)
pushIdentify	String		앱푸시 식별자 (핑거푸시 토큰)
smsOptIn ~ nightAdOptIn	Boolean		수신동의 7종 (null이면 기존 값 유지)

커스텀 도메인 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 →