연락처 SDK 연동 가이드

웹/앱 SDK의 identify()로 회원 정보·수신동의·커스텀 속성·행동 데이터를 주소록(연락처)에 수집합니다.

연락처 데이터 구성

하나의 연락처는 세 층으로 이루어지며, 각각 다른 API 호출로 채워집니다.

인증 & 베이스 URL

연락처 API는 /api/v1/cross-platform/** 경로를 사용하며, 모든 요청에 두 개의 헤더가 반드시 필요합니다.

베이스 URL은 https://api.fingerpush.link/api/v1/cross-platform 입니다.

사용자 수집 엔드포인트

SDK는 아래 세 엔드포인트로 회원 정보와 수신동의를 주소록에 upsert합니다.

POST /api/v1/cross-platform/identify

로그인·회원가입·프로필 변경 시 호출합니다. externalUserId 기준으로 없으면 새로 만들고(INSERT), 있으면 전달한 필드만 갱신합니다(보내지 않은 필드는 기존 값 유지).

요청 본문

요청 예시

curl -X POST https://api.fingerpush.link/api/v1/cross-platform/identify \
  -H "X-App-ID: 12345" \
  -H "X-Mobile-App-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "u1001",
    "name": "홍길동",
    "phone": "01012345678",
    "email": "gildong@example.com",
    "smsOptIn": true,
    "emailAdOptIn": true,
    "customFields": { "grade": "gold", "birthday": "1990-07-26", "point": 15000 }
  }'

응답

{
  "success": true,
  "action": "created",     // "created" | "updated" | "reactivated"
  "externalUserId": "u1001"
}

POST /api/v1/cross-platform/opt-in

마이페이지 등에서 수신동의만 단독으로 변경할 때 호출합니다. identify()를 먼저 호출하지 않은 사용자는 404를 반환합니다.

요청 본문

externalUserId(필수) + identify와 동일한 수신동의 필드들 (smsOptIn, emailOptIn, pushOptIn, smsAdOptIn, emailAdOptIn, pushAdOptIn, nightAdOptIn, alimtalkAdOptIn, whatsappOptIn). 전달한 항목만 갱신됩니다.

curl -X POST https://api.fingerpush.link/api/v1/cross-platform/opt-in \
  -H "X-App-ID: 12345" \
  -H "X-Mobile-App-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "externalUserId": "u1001", "smsOptIn": false, "emailAdOptIn": true }'

POST /api/v1/cross-platform/withdraw

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

요청 본문

{
  "success": true,
  "externalUserId": "u1001",
  "withdrawnCount": 1        // 공백 처리된 연락처 수
}

행동 데이터(activity) 수집

로그인·구매·커스텀 이벤트 같은 행동은 세션 API로 기록됩니다. 서버는 세션에 연결된 externalUserId로 연락처를 찾아, 이벤트를 해당 연락처의 activity(최초 시각·마지막 시각·발생 횟수·누적 금액)로 집계합니다. 이 값들이 세그먼트의 activity.* 조건 소스가 됩니다.

/session/event 요청 필드

세그먼트 연계

이 API로 수집한 데이터는 콘솔의 세그먼트 조건으로 즉시 활용됩니다. 커스텀 속성은 custom.키로, 행동 데이터는 activity.metric.first|last|count|sum 형태로 참조됩니다. 조건에 맞는 대상자는 매일 자동으로 다시 계산되어 캠페인·자동화 발송 대상으로 쓰입니다. 조건 문법과 활용 예시는 세그먼트 사용자 속성 가이드를 참고하세요.

오류 응답

// 401 — 헤더 누락
{ "error": "X-App-ID 헤더는 필수입니다." }

// 404 — opt-in 선행 identify 없음
{ "success": false, "message": "등록되지 않은 사용자입니다. identify()를 먼저 호출하세요." }