🌍 Web SDK API

웹 브라우저에서 핑거프린트 업데이트, 스토어 방문 추적, 플랫폼 전환 세션을 처리하는 API입니다.

💡 인증 불필요

Web SDK API는 브라우저에서 직접 호출하므로 인증이 필요하지 않습니다. 별도의 API Key나 헤더 없이 사용할 수 있습니다.

딥링크 핑거프린트 API

웹에서 앱으로의 딥링크 전환 시 핑거프린트 정보를 수집하고 매칭에 사용합니다.

POST /api/v1/sdk/web/deeplink/update-fingerprint

웹 브라우저의 핑거프린트 정보를 업데이트합니다. QR 코드 스캔이나 단축 URL 클릭 후 중간 페이지에서 자동으로 호출됩니다.

요청 본문

필드	타입	필수	설명
token	String	✅	딥링크 토큰
resolution	String		화면 해상도 (예: 1920x1080)
appId	Long		앱 ID
userAgent	String		브라우저 User-Agent

JavaScript

fetch('https://fplink.net/api/v1/sdk/web/deeplink/update-fingerprint', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token: 'dl_token_abc123',
    resolution: window.screen.width + 'x' + window.screen.height,
    userAgent: navigator.userAgent
  })
});

JSON

{
  "status": "success",
  "message": "Fingerprint updated"
}

POST /api/v1/sdk/web/campaign-deep-link/update-fingerprint

캠페인 딥링크의 핑거프린트를 업데이트합니다. 캠페인 QR 코드 스캔 후 호출됩니다.

요청 본문

딥링크 핑거프린트 API와 동일한 필드를 사용합니다.

스토어 방문 추적 API

POST /api/v1/sdk/web/deeplink/track-store-visit

앱스토어 방문 이벤트를 추적합니다. 중간 페이지에서 앱스토어로 이동할 때 navigator.sendBeacon()으로 호출됩니다.

요청 본문

필드	타입	필수	설명
token	String	✅	딥링크 토큰
isCampaign	Boolean		캠페인 여부 (기본: false)

JavaScript — sendBeacon

// 앱스토어 이동 직전에 호출
navigator.sendBeacon(
  'https://fplink.net/api/v1/sdk/web/deeplink/track-store-visit',
  JSON.stringify({
    token: 'dl_token_abc123',
    isCampaign: false
  })
);
window.location.href = storeUrl;

디버그 API

POST /api/v1/sdk/web/deeplink/debug-scheme

Android Intent URL 디버그 정보를 수집합니다. 개발/디버깅 목적으로 사용됩니다.

요청 본문

필드	타입	설명
appUrl	String	앱 URL
schemeEnd	String	URL Scheme 끝부분
pathPart	String	경로 부분
androidPackage	String	Android 패키지명
appScheme	String	앱 URL Scheme
intentUrl	String	Android Intent URL 전체

SDK 버전 API

GET /api/v1/sdk/web/version

Web SDK의 최신 버전 정보를 조회합니다.

JSON

{
  "version": "1.0.0",
  "sdkUrl": "/sdk/v1/fplink-tracker.js",
  "changelogUrl": "/sdk/v1/CHANGELOG.md",
  "name": "FPLink Cross-Platform Session Tracker SDK"
}

사용자 여정 세션 API

웹과 앱 간의 사용자 여정을 추적하는 사용자 여정 세션 API입니다. 이 API는 /api/v1/cross-platform/session 경로를 사용하며, X-App-ID 헤더가 필요합니다.

ℹ️ 인증 요구사항

사용자 여정 API는 X-App-ID와 X-Mobile-App-API-Key 헤더가 필요합니다. 사용자 여정 분석 애드온 구독도 필요합니다.

세션 관리

메서드	경로	설명
POST	/api/v1/cross-platform/session/create	새 세션 생성
GET	/api/v1/cross-platform/session/{sessionId}	세션 정보 조회
POST	/api/v1/cross-platform/session/{sessionId}/link-user	세션에 사용자 연결
POST	/api/v1/cross-platform/session/register-fplink	FPLink 등록

이벤트 & 전환 추적

메서드	경로	설명
POST	/api/v1/cross-platform/session/event	세션 이벤트 기록 (페이지뷰, 클릭, 구매 등)
GET	/api/v1/cross-platform/session/{sessionId}/events	세션 이벤트 조회
POST	/api/v1/cross-platform/session/transition	플랫폼 전환 기록 (web→app 등)
GET	/api/v1/cross-platform/session/{sessionId}/transitions	전환 이력 조회
POST	/api/v1/cross-platform/session/funnel/track	퍼널 이벤트 추적

💡 웹 앱 퍼널 단계

웹 앱은 앱 설치 관련 중간 단계가 생략되고, 콘텐츠 조회·액션 수행이 추가되어 5단계 퍼널로 추적됩니다:
① 링크 클릭(CLICKED) → ② 페이지 도달(DEEP_LINK_RESOLVED) → ③ 콘텐츠 조회(CONTENT_VIEWED) → ④ 액션 수행(ACTION_TAKEN) → ⑤ 목표 달성(GOAL_COMPLETED)
콘솔의 퍼널 분석에서 웹 앱 선택 시 자동으로 5단계 퍼널이 표시됩니다.

전환 목표 추적 메서드

SDK는 전환 목표를 추적하기 위한 여러 편의 메서드를 제공합니다. 구매/매출 추적에는 trackPurchase를, 그 외 전환 목표에는 trackGoal을 사용합니다.

메서드	용도	사용 예시
trackPurchase(amount, currency)	구매/매출 추적 (통화 코드 포함)	trackPurchase(29900, 'KRW')
trackGoal(goalType, goalValue)	범용 목표 수치화 (구매 외 전환)	trackGoal('signup', 1)
trackSignup()	회원가입 완료 (편의 메서드)	trackSignup()
trackConversion(eventName, value)	커스텀 전환 목표 (편의 메서드)	trackConversion('file_download', 1)

ℹ️ trackPurchase vs trackGoal 차이점

trackPurchase(금액, 통화) — 통화 코드(KRW, USD 등)를 포함하여 매출 데이터를 정확하게 수집합니다. 내부적으로 goalType이 purchase_KRW 형태로 자동 생성됩니다.
trackGoal(목표타입, 수치) — 통화(currency) 파라미터가 없습니다. 회원가입, 예약, 구독 시작, 콘텐츠 조회 등 구매 외 전환을 수치화할 때 사용합니다.

⚠️ 전환 목표 메서드 vs trackEvent — 데이터 저장 위치가 다릅니다

trackPurchase / trackGoal / trackSignup / trackConversion — 퍼널 전환 목표로 기록됩니다. 콘솔의 사용자 여정 분석에서 확인할 수 있습니다. (내부: session_metadata에 저장)
trackEvent(eventType, eventData) — 이벤트로 기록됩니다. 콘솔의 이벤트 로그에서 확인할 수 있습니다. (내부: session_events에 저장)

💡 구매 데이터를 양쪽 모두에서 조회하려면 두 메서드를 함께 호출하세요:

tracker.trackPurchase(29900, 'KRW');       // → 사용자 여정 분석 (퍼널)
tracker.trackEvent('purchase', {           // → 이벤트 로그
  amount: 29900, currency: 'KRW', product: '프리미엄 플랜'
});

JavaScript — 전환 목표 추적

// ✅ 구매/매출 → trackPurchase (통화 코드 포함)
tracker.trackPurchase(29900, 'KRW');    // goalType = 'purchase_KRW'
tracker.trackPurchase(19.99, 'USD');    // goalType = 'purchase_USD'

// ✅ 구매 외 전환 목표 → trackGoal (통화 없음)
tracker.trackGoal('signup', 1);           // 회원가입
tracker.trackGoal('subscription', 9900);  // 구독 시작
tracker.trackGoal('reservation', 1);      // 예약 완료
tracker.trackGoal('lead_generation', 1);  // 리드 생성
tracker.trackGoal('content_view', 1);     // 콘텐츠 조회
tracker.trackGoal('survey_complete', 1);  // 설문 완료

// ✅ 편의 메서드
tracker.trackSignup();                    // = trackGoal('signup', 1)
tracker.trackConversion('file_download', 1); // = trackGoal('file_download', 1)

💡 URL 전환 목표 자동 연동

콘솔에서 URL 생성 시 전환 목표를 설정하면, SDK가 딥링크 resolve 응답에서 goalType을 자동으로 수신하여 저장합니다. 이후 trackGoal(null, 금액)으로 호출해도 URL에 설정된 goalType이 자동 적용됩니다. 단, SDK에서 명시적으로 goalType을 전달하면 URL 설정보다 우선됩니다.

📌 goalType 목록: 콘솔의 목표 유형 관리 페이지에서 동적으로 관리됩니다. 기본 프리셋(purchase, signup 등) 외에 커스텀 goalType을 자유롭게 추가할 수 있습니다.

통계 조회

메서드	경로	설명
GET	/api/v1/cross-platform/stats/dashboard	대시보드 통계
GET	/api/v1/cross-platform/stats/summary	전체 요약
GET	/api/v1/cross-platform/stats/daily	일별 통계
GET	/api/v1/cross-platform/stats/sessions/summary	세션 요약 통계
GET	/api/v1/cross-platform/stats/sessions/by-platform	플랫폼별 세션 통계
GET	/api/v1/cross-platform/stats/sessions/by-utm-source	UTM 소스별 세션
GET	/api/v1/cross-platform/stats/sessions/list	세션 목록
GET	/api/v1/cross-platform/stats/transitions/summary	전환 요약 통계
GET	/api/v1/cross-platform/stats/transitions/trend	전환 트렌드

← Mobile SDK API

에러 코드 →