Web SDK API

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

TIP인증 불필요

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/identify	사용자 기본정보 수집 (Identify) — upsert
POST	/api/v1/cross-platform/opt-in	수신동의 업데이트 (Opt-in)

이벤트 & 전환 추적

메서드	경로	설명
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	퍼널 이벤트 추적

TIP웹 앱 퍼널 단계

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

전환 목표 추적 메서드

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

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

참고trackPurchase vs trackGoal 차이점

trackPurchase(금액, 통화, options?) — 통화 코드(KRW, USD 등)를 포함하여 매출 데이터를 정확하게 수집합니다. 내부적으로 goalType이 purchase_KRW 형태로 자동 생성됩니다. options.transactionId로 거래 고유 ID를 전달하면 중복 결제를 방지할 수 있습니다.
trackGoal(목표타입, 수치, 통화?, options?) — 회원가입, 예약, 구독 시작, 콘텐츠 조회 등 다양한 전환을 수치화할 때 사용합니다. options.transactionId로 중복 전환을 방지할 수 있습니다.

주의전환 목표 메서드 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'
tracker.trackPurchase(29900, 'KRW', { transactionId: 'ORD-001' });     // 중복 결제 방지 (권장)

// ✅ 구매 외 전환 목표 → 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)
tracker.trackConversion('custom_event', 1, null, { transactionId: 'EVT-001' }); // 중복 전환 방지

TIPURL 전환 목표 자동 연동

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

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

사용자 식별 & 수신동의 API

로그인/회원가입 시 사용자 기본정보를 수집하고, 수신동의를 관리하는 API입니다.

메서드	경로	설명
POST	/api/v1/cross-platform/identify	사용자 기본정보 수집 — externalUserId 기준 upsert
POST	/api/v1/cross-platform/opt-in	수신동의 업데이트 — identify 선행 필요
POST	/api/v1/cross-platform/withdraw	회원탈퇴 — 비활성화 + 개인정보 공백 처리

참고identify / opt-in / withdraw 차이점

identify — 이름, 전화번호, 이메일, 수신동의를 한 번에 upsert합니다. 처음 호출 시 레코드를 생성하고, 이후 호출 시 전달한 필드만 업데이트합니다.
opt-in — 수신동의 항목만 단독으로 업데이트합니다. identify를 먼저 호출하지 않은 사용자는 404 에러를 반환합니다.
withdraw — 탈퇴 시 호출합니다. 주소록에서 비활성화하고 개인정보를 즉시 공백 처리합니다.

identify 요청 파라미터

필드	타입	필수	설명
externalUserId	String	✓	고객사 서비스의 회원 ID
name	String		이름
phone	String		전화번호 (서버에서 AES-256 암호화 저장)
email	String		이메일 (서버에서 AES-256 암호화 저장)
pushIdentify	String		앱푸시 식별자 (핑거푸시 토큰)
smsOptIn	Boolean		SMS 수신동의
emailOptIn	Boolean		이메일 수신동의
pushOptIn	Boolean		앱푸시 수신동의
smsAdOptIn	Boolean		SMS 광고 수신동의
emailAdOptIn	Boolean		이메일 광고 수신동의
pushAdOptIn	Boolean		앱푸시 광고 수신동의
nightAdOptIn	Boolean		야간 광고 수신동의
customFields	Object		등급·생일 등 임의 속성 — 세그먼트 조건으로 사용 (가이드)

SDK 호출 예시

// 로그인 성공 후
const result = await fplink.identify({
    externalUserId: user.id,
    name: user.name,
    phone: user.phone,
    email: user.email,
    smsOptIn: user.smsConsent,
    emailOptIn: user.emailConsent,
    customFields: { grade: 'gold', birthday: '1990-07-26' }  // 날짜는 YYYY-MM-DD
});
console.log(result.action); // "created" | "updated" | "reactivated"

// 마이페이지에서 수신동의 변경 시
await fplink.optIn({
    externalUserId: user.id,
    smsOptIn: false,
    emailAdOptIn: true
});

회원탈퇴 (withdraw)

탈퇴 시 호출합니다. 연락처를 비활성화하고 이름·전화번호·이메일·앱푸시 식별자·커스텀 속성을 즉시 공백 처리하며 수신동의를 모두 해제합니다. 행동 기록도 함께 삭제됩니다.

필드	타입	필수	설명
externalUserId	String	✓	탈퇴할 회원 ID

// 회원탈퇴 처리 완료 후
const result = await fplink.withdraw({ externalUserId: user.id });
console.log(result.withdrawnCount); // 공백 처리된 연락처 수

// 같은 ID로 다시 가입하면 재가입으로 처리되어 되살아납니다
await fplink.identify({ externalUserId: user.id, name: '홍길동' });
// → action: "reactivated"

주의되돌릴 수 없습니다

공백 처리된 개인정보는 복구되지 않습니다. 재가입 시에는 identify()로 정보를 다시 보내야 합니다.

발송 이력과 누적 통계는 보존되며, 관리자가 콘솔에서 차단한 연락처는 재가입해도 되살아나지 않습니다. 대상이 없으면 404를 반환합니다(이미 탈퇴했거나 등록된 적 없는 사용자).

앱 안의 웹뷰에서 회원가입·마이페이지를 띄우는 하이브리드 앱이라면, 웹에서 바꾼 앱푸시 수신동의를 네이티브에도 알려야 합니다. FPLink 서버의 수신동의는 identify() / optIn()이 이미 저장하지만, 핑거푸시 단말 설정(beAgree / beAdAgree)은 앱에 심긴 핑거푸시 SDK가 들고 있기 때문에 웹에서만 바꾸면 앱 설정과 어긋납니다.

전달 데이터

필드	타입	설명
identify	String	핑거푸시 식별자 (identify의 pushIdentify와 같은 값)
pushOptIn	Boolean	앱푸시 수신동의
pushAdOptIn	Boolean	앱푸시 광고 수신동의

웹 호출 코드

// 서버 저장(optIn/identify)이 성공한 뒤에 호출합니다.
function sdkSyncPushConsent(params) {
    const data = {
        identify:    params.identify || '',
        pushOptIn:   Boolean(params.pushOptIn),
        pushAdOptIn: Boolean(params.pushAdOptIn)
    };

    // iOS — WKWebView
    if (window.webkit?.messageHandlers?.syncPushConsent) {
        window.webkit.messageHandlers.syncPushConsent.postMessage(data);   // 객체 그대로
        return true;
    }

    // Android — addJavascriptInterface (문자열만 전달 가능)
    if (window.syncPushConsent?.postMessage) {
        window.syncPushConsent.postMessage(JSON.stringify(data));
        return true;
    }

    return false;   // 브릿지 없음(PC·모바일 웹) — 서버 저장은 이미 끝났으므로 그냥 넘어갑니다
}

// 수신동의 저장 성공 후
await fplink.optIn({ externalUserId: user.id, pushOptIn: true, pushAdOptIn: false });
sdkSyncPushConsent({ identify: user.pushIdentify, pushOptIn: true, pushAdOptIn: false });

네이티브 등록

플랫폼	등록 방식
iOS	`userContentController.add(handler, name: "syncPushConsent")` — 전달값은 Dictionary
Android	`webView.addJavascriptInterface(obj, "syncPushConsent")` — `@JavascriptInterface fun postMessage(json: String)`

주의웹 함수 이름을 syncPushConsent로 만들지 마세요

Android는 브릿지 객체를 window.syncPushConsent로 주입합니다. 웹에서 같은 이름의 전역 함수를 선언하면 브릿지 객체를 덮어써서 안드로이드 전달이 되지 않습니다. 위 예시처럼 sdkSyncPushConsent 같은 다른 이름을 쓰세요.

참고호출 시점

회원가입 완료 후 — 가입 시 선택한 앱푸시·앱푸시 광고 동의
수신동의 저장 후 — pushOptIn·pushAdOptIn이 바뀐 경우에만
푸시 식별자 변경 후 — 새 식별자 기준으로 현재 동의 상태를 다시 전달
회원탈퇴 후 — 수신동의가 모두 해제되므로 false / false 전달

브릿지 호출은 서버 저장이 성공한 뒤에 하세요. 브릿지가 없는 환경(PC·모바일 웹)에서는 아무 것도 보내지 않고 넘어가면 됩니다.

통계 조회

메서드	경로	설명
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

인앱메시지 연동 가이드 →

Web SDK API

딥링크 핑거프린트 API

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

요청 본문

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

요청 본문

스토어 방문 추적 API

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

요청 본문

디버그 API

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

요청 본문

SDK 버전 API

GET /api/v1/sdk/web/version

사용자 여정 세션 API

세션 관리

이벤트 & 전환 추적

전환 목표 추적 메서드

사용자 식별 & 수신동의 API

identify 요청 파라미터

SDK 호출 예시

회원탈퇴 (withdraw)

웹뷰 앱푸시 수신동의 브릿지 (syncPushConsent)

전달 데이터

웹 호출 코드

네이티브 등록

통계 조회