지식센터 / 레퍼런스

추천 위젯 SDK: API 호출부터 트래킹까지 - BizSpring BLOG

추천 위젯 SDK: API 호출부터 트래킹까지 - BizSpring BLOG

콘텐츠로 건너뛰기

내비게이션 메뉴

인사이트

테크

활용 방법/사례

활용 방법/사례

성공사례

성공 사례 일반

광고/마케팅 에이전시

이커머스

미디어/콘텐츠

금융/핀테크

의료/헬스케어

통신/인터넷

뉴스/트렌드

릴리즈 노트

인터넷트렌드 ↗

웹사이트 ↗

# 추천 위젯 SDK: API 호출부터 트래킹까지

2026년 04월 10일 2026년 05월 26일

테크

추천 시스템은 사용자 행동 데이터를 기반으로 상품을 추천하는 기능입니다. 하지만 실제 서비스에서는 추천 결과를 받아오는 것뿐만 아니라, 이를 화면에 노출하고 사용자 행동을 추적하는 과정까지 함께 구현해야 합니다.

이번 포스트에서는 추천 위젯을 서비스에 연동하기 위해 임베디드 SDK를 어떻게 설계하고 구현했는지를 중심으로 정리합니다.

1. 추천 위젯 SDK란

추천 시스템의 기본 구조는 다음과 같습니다.

Client (SDK) > Recommendation API > Model

모델은 추천 결과를 생성하고, SDK는 이를 서비스 화면에 노출하는 역할을 담당합니다.

SDK에서 처리하는 주요 역할은 다음과 같습니다.

추천 API 호출

위젯 렌더링

사용자 이벤트 트래킹 (노출, 클릭 등)

서비스에서 사용할 수 있는 호출 방식 제공

즉 추천 로직과는 별개로, 추천 결과를 서비스에서 사용할 수 있도록 처리하는 모듈입니다.

2. SDK 동작 흐름

SDK의 기본적인 동작 흐름은 다음과 같습니다.

SDK 초기화

추천 API 호출

추천 데이터 수신

위젯 렌더링

사용자 이벤트 트래킹

구조를 단순하게 보면 다음과 같습니다.

init → API 호출 → 데이터 → DOM 렌더링 → 이벤트 수집

각 단계는 서로 분리되어 있지만, 실제 구현에서는 하나의 흐름으로 연결되어 동작합니다.

3. SDK 호출 구조 및 비동기 로드 대응

SDK는 단일 진입점 기반의 구조로 설계했습니다.

function MA() {

var cmd = arguments[0];

var params = arguments[1] || {};

handleCommand(cmd, params);

}

사용 방식:

_MA('init', {...})

_MA('renderWidget', {...})

이와 같은 단일 진입점 구조는 외부에 노출되는 인터페이스를 최소화하여 기능 확장 시 하위 호환성을 유지하기에 유리합니다.

비동기 로드 문제 해결

임베디드 SDK는 비동기로 로드되는 경우가 많습니다. 이때 SDK 로드 이전에 호출된 명령이 유실될 수 있습니다.

var previous = window._MA;

var queued = previous && previous.q ? previous.q.slice() : [];

if (queued) {

for (var i = 0; i < queued.length; i++) {

MA.apply(null, queued[i]);

}

}

gtag나 fbq 등에서 검증된 이 패턴은 SDK 로드 이전의 명령을 큐(q)에 임시 저장했다가, 로드 완료 시점에 순차적으로 실행하여 안정적인 동작을 보장합니다.

4. 사용자 식별 전략

추천 정확도와 트래킹을 위해 사용자 식별이 필요합니다.

MID: sha256(member_id)

UUID: GA cookie 기반

MID (Member ID): 로그인 사용자 식별. 개인정보 보호를 위해 member_id를 직접 노출하지 않고 SHA-256 해싱 처리하여 사용합니다.

UUID: 비로그인 사용자 식별. _ga와 같은 GA 쿠키를 활용하여 세션 간 일관된 경험을 제공합니다.

이 구조는 개인정보 보호 대응 및 세션 간 추적 유지를 동시에 만족하기 위한 방식입니다.

5. 노출 제어 트리거

추천 위젯의 성공 여부는 노출 타이밍에 좌우됩니다. 추천 위젯에는 어드민 설정에 따라 다양한 노출 전략을 지원하는 트리거 핸들러를 포함합니다.

triggerHandlers = {

immediate,

delay,

scroll,

bottom,

exit

}

활용 예:

immediate: 페이지 로드 즉시 노출

scroll: 특정 스크롤 깊이 도달 시 렌더링

bottom: 페이지 최하단 도달 시 위젯 노출

exit: 마우스가 브라우저 상단을 벗어나는 시점을 기준으로 이탈 의도를 감지

노출 조건은 어드민 설정과 연동해 SDK에서 제어할 수 있도록 구현했습니다.

6. 이벤트 트래킹 구조

1) 전환 이벤트

dataLayer.push({...})

Google Analytics / GTM 연동

전환 성과 측정

2) 노출 이벤트 정확도

노출 이벤트는 단순히 DOM에 렌더링된 시점이 아니라, 사용자 화면에 실제로 노출된 시점을 기준으로 수집합니다.

new IntersectionObserver(..., { threshold: 0.5 })

사용자의 화면(Viewport)에 실제로 위젯이 나타난 순간을 포착하기 위해 IntersectionObserver를 활용합니다.

__recImpressedKeys

동일 세션 내에서 같은 추천 결과가 반복적으로 집계되는 것을 막기 위해 __recImpressedKeys와 같은 내부 저장소를 활용합니다.

7. 마무리

이번 포스팅에서는 SDK 호출 구조, 비동기 로드 대응, 노출 트리거 제어, 이벤트 트래킹 방식을 중심으로 정리했습니다.

추천 기능을 서비스에 적용하는 과정에서는 단순히 API를 호출하는 것 외에도 렌더링과 트래킹까지 함께 고려해야 합니다.

비슷한 구조를 고민하고 있다면 참고할 수 있는 사례로 활용될 수 있기를 바랍니다.

최신 마케팅/고객 데이터 활용 사례를 받아보실 수 있습니다.

비즈스프링 뉴스레터 구독하기 →

Related Posts via Categories

구글애즈가 정확검색·구문검색 키워드까지 AI 모드에 노출하기 시작했다 — 자동화 상품 없이 AI 답변 화면에 들어가는 첫 실험

AI가 React 앱을 직접 디버깅 – Agent 기반 디버깅

ChatGPT 광고가 픽셀·전환 API·맞춤 오디언스를 갖췄다 — 답변 화면이 측정 가능한 광고 매체가 되는 순간

AI 시대, 데이터도 설명이 필요합니다

MCP 클라이언트는 Authorization Server를 어떻게 찾는가: 공식 MCP TypeScript SDK와 VS Code 구현 비교

RAG 시대의 GEO: AI가 콘텐츠를 읽는 방식과 스키마의 진짜 역할

AI 에이전트로 웹 데이터 수집 가능 여부 자동 검증하기

GA4 Intraday 실시간 테이블, 대시보드 원천 데이터로 바로 사용할 수 있을까?

워크플로우 오케스트레이션 플랫폼 Temporal 알아보기

iOS 14.5부터 GA4까지, 환경 변화가 가져온 업무 폭증을 해결하는 실무 전략은…?

다음에 대해 검색하기...

최신 글 둘러보기

기존 SEO와 무엇이 같고 무엇이 다른가

콘텐츠가 답인 걸 모르는 사람은 없습니다 — 문제는 지속입니다

광고비를 늘리지 않고 매출을 늘린 회사들은 무엇을 했나

코호트로 비교하면 광고 예산 판단이 달라집니다

GEO를 위한 글쓰기를 위한 작은 노하우

(해외동향) 광고주가 광고플랫폼 리포트에서 자체 측정으로 옮겨가고 있다.

구글애즈가 정확검색·구문검색 키워드까지 AI 모드에 노출하기 시작했다 — 자동화 상품 없이 AI 답변 화면에 들어가는 첫 실험

AI가 React 앱을 직접 디버깅 – Agent 기반 디버깅

ChatGPT 광고가 픽셀·전환 API·맞춤 오디언스를 갖췄다 — 답변 화면이 측정 가능한 광고 매체가 되는 순간

마케팅 자동화, 무엇부터 자동화해야 할까?

출처: https://blog.bizspring.co.kr/%ed%85%8c%ed%81%ac/%ec%b6%94%ec%b2%9c-%ec%9c%84%ec%a0%af-sdk-api-%ed%98%b8%ec%b6%9c%eb%b6%80%ed%84%b0-%ed%8a%b8%eb%9e%98%ed%82%b9%ea%b9%8c%ec%a7%80/

자주 묻는 질문

추천 위젯 SDK는 정확히 어떤 역할을 하나요?

모델이 생성한 추천 결과를 받아 서비스 화면에 노출하고 사용자 행동을 추적하는 모듈입니다. 추천 API 호출, 위젯 렌더링, 이벤트 트래킹, 호출 방식 제공을 담당하며 추천 로직 자체와는 별개로 동작합니다.

SDK가 비동기로 로드될 때 명령이 유실되지 않나요?

SDK 로드 이전에 호출된 명령은 큐(q)에 임시 저장했다가 로드 완료 시점에 순차적으로 실행하는 패턴을 사용합니다. 이는 gtag나 fbq 등에서 검증된 방식으로 안정적인 동작을 보장합니다.

로그인 사용자와 비로그인 사용자는 어떻게 구분해서 추적하나요?

로그인 사용자는 member_id를 SHA-256으로 해싱한 MID로 식별하고, 비로그인 사용자는 GA 쿠키(_ga) 기반의 UUID로 식별합니다. 이를 통해 개인정보 보호와 세션 간 일관된 경험 제공을 동시에 만족시킵니다.

위젯 노출 타이밍은 어떻게 제어할 수 있나요?

immediate, delay, scroll, bottom, exit 등 트리거 핸들러를 통해 어드민 설정에 따라 다양한 노출 전략을 지원합니다. 예를 들어 스크롤 깊이 도달, 페이지 최하단 도달, 이탈 의도 감지 시점 등에 맞춰 위젯을 노출할 수 있습니다.

노출 이벤트는 어떻게 정확하게 집계하나요?

단순히 DOM에 렌더링된 시점이 아니라 IntersectionObserver를 활용해 사용자의 화면(Viewport)에 실제로 노출된 순간을 기준으로 수집합니다. 또한 __recImpressedKeys 같은 내부 저장소로 동일 세션 내 중복 집계를 방지합니다.

관련 문서

이 문서를 참조하는 문서 (역링크)

• 없음

다른 표현: Markdown · JSON · 최종 갱신 2026-09-06