API Documentation

개요

워크플로우 SDK 연동 가이드

ENDPOINTS

UUID 등록 ADID 매핑 UUID 조회 ADID 조회

ADMIN

로그인 통계 매핑 목록 이벤트 로그

Web SDK 연동 가이드

1. SDK 설치

2. 초기화

AdidTracker.init({
    apiBaseUrl: 'https://your-domain.com',  // API 서버 URL
    debug: true,                           // 디버그 모드 (선택)
    autoRegister: true                       // 자동 등록 (기본: true)
});
                        

3. 주요 메서드

메서드	설명	예시
`init(options)`	SDK 초기화	`AdidTracker.init({apiBaseUrl: 'https://...'})`
`getUUID()`	현재 UUID 반환 (없으면 생성)	`const uuid = AdidTracker.getUUID()`
`register()`	UUID를 서버에 수동 등록	`await AdidTracker.register()`
`openApp(options)`	딥링크로 앱 열기	`AdidTracker.openApp({scheme:'myapp', path:'open'})`
`buildUrl(baseUrl, params)`	UUID가 포함된 URL 생성	`AdidTracker.buildUrl('https://...', {ref:'ad1'})`

4. 이벤트 리스너

// 등록 완료 이벤트
window.addEventListener('adidtracker:registered', (e) => {
    console.log('UUID:', e.detail.uuid);
    console.log('Response:', e.detail.response);
});

// 에러 이벤트
window.addEventListener('adidtracker:error', (e) => {
    console.error('Error:', e.detail.error);
});
                        

5. 앱 연동 예시 (딥링크)

// 앱 열기 버튼 클릭 시
document.getElementById('openAppBtn').addEventListener('click', () => {
    AdidTracker.openApp({
        scheme: 'myapp',              // 앱 URL scheme
        path: 'open',                  // 앱 내 경로
        fallbackUrl: 'https://play.google.com/store/apps/details?id=...',
        params: { campaign: 'summer2026' }
    });
});
                        

샘플 페이지: /sdk/sample.html에서 실제 동작을 테스트해볼 수 있습니다.

크로스 디바이스 추적 워크플로우

개요: 웹 광고를 클릭한 사용자가 앱을 설치했는지 추적하는 시스템입니다. 웹에서 UUID를 발급하고, 앱에서 ADID와 매핑하여 크로스 디바이스 전환을 측정합니다.

전체 흐름

단계	위치	동작	API 호출	데이터
1	웹 (광고 랜딩)	SDK가 UUID를 생성하고 localStorage에 저장	`-`	UUID 생성됨
2	웹	SDK가 서버에 UUID 등록	`POST /api/v1/uuid`	UUID, referrer, fingerprint
3	웹	사용자가 앱 설치 버튼 클릭 → 딥링크 URL 생성	`-`	myapp://open?uuid=xxx
4	앱스토어	사용자가 앱 설치	`-`	-
5	앱	앱 실행 시 딥링크에서 UUID 추출, ADID 획득	`-`	UUID (딥링크), ADID (기기)
6	앱	UUID-ADID 매핑 요청	`POST /api/v1/match`	UUID + ADID + platform
7	분석	광고 성과 측정 (전환 추적)	`GET /api/v1/lookup/*`	매핑 데이터 조회

주요 용어

UUID	웹 브라우저에서 생성하는 고유 식별자 (Universally Unique Identifier)
ADID	모바일 광고 식별자의 통칭 (GAID + IDFA)
GAID	Google Advertising ID (Android)

IDFA	Identifier for Advertisers (iOS)
딥링크	앱을 직접 열 수 있는 URL (예: myapp://open)
어트리뷰션	앱 설치가 어떤 광고에서 발생했는지 추적

API Endpoints

POST /api/v1/uuid 브라우저 UUID 등록

API 설명

웹 브라우저에서 생성한 UUID를 서버에 등록합니다. 이 UUID는 나중에 앱의 ADID와 매핑되어 크로스 디바이스 추적에 사용됩니다.

사용 시나리오:

사용자가 웹사이트(광고 랜딩페이지)에 접속
SDK가 브라우저에서 UUID를 생성하고 localStorage에 저장
이 API를 호출하여 서버에 UUID를 등록
사용자가 앱을 설치하면 앱에서 같은 UUID로 ADID 매핑 요청

Request Body

Parameter	Type	Description
uuid *required	string (UUID v4)	브라우저에서 생성한 UUID (36자, 예: 550e8400-e29b-41d4-a716-446655440000)
referrer	string (max 500)	유입 경로 URL. 광고 캠페인 추적에 활용
fingerprint	object	브라우저 핑거프린트 데이터 (선택)

Fingerprint 필드 상세

Field	Type	Description
screen	string	화면 해상도 (예: "1920x1080")
timezone	string	타임존 (예: "Asia/Seoul")
language	string	브라우저 언어 (예: "ko-KR")
platform	string	플랫폼 (예: "Win32")
cookieEnabled	boolean	쿠키 활성화 여부
doNotTrack	string	DNT 설정값

Example Request

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "referrer": "https://ad.example.com/campaign1",
  "fingerprint": {
    "screen": "1920x1080",
    "timezone": "Asia/Seoul",
    "language": "ko-KR"
  }
}
                                

Response (201 Created) - 신규 등록

{
  "success": true,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "created": true
}
                                

Response (200 OK) - 이미 존재

{
  "success": true,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "created": false
}
                                

Error Response (422)

{
  "success": false,
  "error": "uuid 필드는 필수입니다."
}
                                

Try It

주의: UUID는 한 번 등록되면 변경할 수 없습니다. 중복 호출 시 기존 데이터가 반환됩니다.

POST /api/v1/match UUID-ADID 매핑

API 설명

웹에서 등록된 UUID와 모바일 앱의 광고 ID(ADID)를 연결합니다. 이를 통해 웹 방문자가 앱을 설치했는지 추적할 수 있습니다.

ADID란?

GAID (Google Advertising ID): Android 기기의 광고 식별자
IDFA (Identifier for Advertisers): iOS 기기의 광고 식별자

호출 시점:

사용자가 앱을 설치하고 최초 실행
앱에서 딥링크 또는 Deferred Deep Link로 UUID를 전달받음
앱에서 ADID를 획득하여 이 API로 매핑 요청

Request Body

Parameter	Type	Description
uuid *required	string (UUID v4)	웹에서 등록된 UUID. 딥링크 파라미터로 전달받음
adid *required	string (36자)	모바일 광고 ID (GAID 또는 IDFA)
platform *required	enum	`android` 또는 `ios`

Example Request

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "adid": "cdda802e-fb9c-47ad-9866-0794d394c912",
  "platform": "android"
}
                                

Response (200 OK) - 매핑 성공

{
  "success": true,
  "matched": true,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "adid": "cdda802e-fb9c-47ad-9866-0794d394c912",
  "platform": "android",
  "matched_at": "2026-01-12T12:00:00+09:00"
}
                                

Error Response (404) - UUID 없음

{
  "success": false,
  "error": "UUID not found"
}
                                

Error Response (400) - 이미 매핑됨

{
  "success": false,
  "error": "Already matched with different ADID"
}
                                

Tip: 동일한 UUID-ADID 조합으로 재호출 시 기존 매핑 정보가 반환됩니다 (멱등성 보장).

GET /api/v1/lookup/uuid/{uuid} UUID로 ADID 조회

API 설명

UUID를 기준으로 매핑된 ADID 정보를 조회합니다. 웹에서 발급된 UUID가 앱과 연결되었는지 확인할 때 사용합니다.

활용 사례:

광고 성과 측정: 웹 광고를 본 사용자가 앱을 설치했는지 확인
리타겟팅: 웹 방문자 중 앱 미설치 사용자 식별
어트리뷰션: 특정 캠페인의 앱 설치 전환율 측정

Path Parameters

Parameter	Type	Description
uuid *required	string (UUID v4)	조회할 UUID (36자)

Example Request

GET /api/v1/lookup/uuid/550e8400-e29b-41d4-a716-446655440000

Response (200 OK) - 매핑됨

{
  "success": true,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "adid": "cdda802e-fb9c-47ad-9866-0794d394c912",
  "platform": "android",
  "matched": true,
  "first_seen_at": "2026-01-12T11:00:00+09:00",
  "matched_at": "2026-01-12T12:00:00+09:00"
}
                                

Response (200 OK) - 미매핑

{
  "success": true,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "adid": null,
  "platform": null,
  "matched": false,
  "first_seen_at": "2026-01-12T11:00:00+09:00"
}
                                

Error Response (404)

{
  "success": false,
  "error": "UUID not found"
}
                                

GET /api/v1/lookup/adid/{adid} ADID로 UUID 조회

API 설명

ADID를 기준으로 연결된 모든 UUID를 조회합니다. 하나의 ADID(기기)가 여러 웹 세션(UUID)과 연결될 수 있습니다.

활용 사례:

사용자 여정 분석: 앱 사용자가 어떤 웹 경로로 유입되었는지 추적
멀티 터치 어트리뷰션: 앱 설치 전 방문한 모든 웹 세션 확인
크로스 디바이스 분석: 동일 기기에서 여러 브라우저 사용 패턴 분석

Path Parameters

Parameter	Type	Description
adid *required	string (36자)	조회할 ADID (GAID 또는 IDFA)

Example Request

GET /api/v1/lookup/adid/cdda802e-fb9c-47ad-9866-0794d394c912

Response (200 OK)

{
  "success": true,
  "adid": "cdda802e-fb9c-47ad-9866-0794d394c912",
  "count": 2,
  "mappings": [
    {
      "uuid": "550e8400-e29b-41d4-...",
      "referrer": "https://ad.example.com/campaign1",
      "first_seen_at": "2026-01-10T10:00:00+09:00",
      "matched_at": "2026-01-12T12:00:00+09:00"
    },
    {
      "uuid": "661f9511-fc9c-52e5-...",
      "referrer": "https://ad.example.com/campaign2",
      "first_seen_at": "2026-01-11T14:00:00+09:00",
      "matched_at": "2026-01-12T12:05:00+09:00"
    }
  ]
}
                                

Error Response (404)

{
  "success": false,
  "error": "ADID not found"
}
                                

Admin API

POST /api/v1/auth/login 관리자 로그인

Request Body

Parameter	Type	Description
username *required	string	관리자 아이디
password *required	string	비밀번호

Response (200 OK)

{
  "success": true,
  "token": "YWRtaW46MTc2ODE...",
  "user": { "username": "admin" }
}
                                

GET /api/v1/admin/stats 통계 조회

Response (200 OK)

{
  "total": 1000,
  "matched": 500,
  "unmatched": 500,
  "match_rate": 50.0,
  "today": { "total": 50, "matched": 25 },
  "platforms": { "android": 300, "ios": 200 }
}
                        

GET /api/v1/admin/mappings 매핑 목록 조회

Query Parameters

Parameter	Type	Description
search	string	UUID/ADID 검색
status	string	matched \| unmatched
platform	string	android \| ios
page	integer	페이지 번호
per_page	integer	페이지당 개수 (max: 100)

GET /api/v1/admin/events 이벤트 로그 조회

Query Parameters

Parameter	Type	Description
type	string	uuid_created \| adid_matched \| lookup
mapping_id	integer	특정 매핑의 이벤트만
page	integer	페이지 번호

Rate Limits

Endpoint	Limit
UUID 등록	100 requests/min per IP
ADID 매핑	200 requests/min per IP
조회 API	300 requests/min per IP

ADID API Documentation

개요

ENDPOINTS

ADMIN

Web SDK 연동 가이드

1. SDK 설치

2. 초기화

3. 주요 메서드

4. 이벤트 리스너

5. 앱 연동 예시 (딥링크)

크로스 디바이스 추적 워크플로우

전체 흐름

주요 용어

API Endpoints

API 설명

API 설명

API 설명

API 설명

Admin API