Web SDK

블럭스 Web SDK 를 설치하고 사용하는 방법을 알아봅니다.

SDK 설치

스크립트 태그
모듈 임포트

HTML 페이지에 스크립트 태그로 블럭스 Web SDK 파일을 추가합니다.

* Next.js를 사용하시는 경우, _document.tsx 혹은 layout.tsx의 <Head> 사이에 삽입하세요.

* React를 사용하시는 경우, public/index.html의 <head> 사이에 삽입하세요.

<script src="https://scripts.blux.ai/blux_web_sdk/2.2.28/sdk_script.js"></script>

아래 명령어로 블럭스 Web SDK를 설치합니다.

* Node.js 버전 ≥ 10.24.1 환경만 지원해요.

npm install @blux.ai/web-sdk

yarn add @blux.ai/web-sdk

pnpm install @blux.ai/web-sdk

BluxClient 초기화

BluxClient 인스턴스를 생성해서 SDK를 초기화하세요. 생성한 인스턴스로 블럭스 Web SDK의 모든 메서드를 호출할 수 있습니다. 내 서비스의 애플리케이션 아이디와 API 키 정보는 연동 키 확인하기 에서 자세히 확인하세요.

* 인스턴스를 생성하면 자동으로 SDK가 초기화 돼요.

인스턴스를 생성한 이후, 별도의 비동기 처리 없이 바로 메서드를 호출해도 돼요.

스크립트 태그
모듈 임포트

<script>
	const bluxClient = new BluxClient({
		bluxApplicationId: "BLUX_APPLICATION_ID",
		bluxAPIKey: "BLUX_API_KEY",
	});
</script>

import { BluxClient } from @blux.ai/web-sdk

const bluxClient = new BluxClient({
	bluxApplicationId: "BLUX_APPLICATION_ID",
	bluxAPIKey: "BLUX_API_KEY",
});

파라미터

bluxApplicationId필수string

고객님의 서비스를 식별하는 고유 아이디입니다.

bluxAPIKey필수string

블럭스에서 발급하는 API 키입니다.

customDeviceIdstring

고객사가 자체적으로 관리하는 디바이스 식별자입니다. 외부 시스템의 디바이스와 블럭스 디바이스를 매핑할 때 사용하세요.

* customDeviceId 옵션은 Web SDK 2.2.11 이상에서 지원됩니다.

유저

유저 로그인을 요청합니다. signIn()을 호출하지 않으면 블럭스 SDK는 유저를 식별할 수 없어요. 아래의 경우에 반드시 호출하세요.

① 회원 유저가 자동 로그인 한 시점

② 비회원 유저가 로그인하여 회원 유저로 식별되는 시점

bluxClient.signIn({ userId: "USER_ID" });

파라미터

userId필수string

유저를 식별하는 고유 아이디입니다.

응답

Promise<void>

signOut()

유저 로그아웃을 요청합니다. 회원 유저가 로그아웃하는 시점에 호출하세요.

bluxClient.signOut();

응답

Promise<void>

setUserProperties()

유저의 전화번호, 이메일 주소, 광고 수신 동의 여부 등을 설정합니다.

bluxClient.setUserProperties({ 
	userProperties: {
		phone_number: "01012345678",
		email_address: "test@blux.ai",
		marketing_notification_consent: true,
	}
});

파라미터

userProperties필수Record

유저의 기본 정보입니다.

phone_numberstring
유저의 전화번호입니다. 블럭스의 문자/카카오톡 발송에 사용되고 있어요. - 없이 숫자로만 구성된 문자열입니다.
email_addressstring
유저의 이메일 주소입니다. 블럭스의 이메일 발송에 사용되고 있어요.
agenumber
유저의 나이입니다.
genderstring
유저의 성별입니다. male, female 중 하나를 입력하세요.
marketing_notification_consentboolean
광고 수신 전역 동의 설정입니다. 전역 동의 또는 채널별 동의 둘 중 하나라도 false면 해당 채널의 광고 수신은 거부됩니다. 둘 다 미설정이어도 해당 채널은 거부됩니다.
marketing_notification_sms_consentboolean
광고 문자 수신 동의 여부입니다.
marketing_notification_email_consentboolean
광고 이메일 수신 동의 여부입니다.
marketing_notification_push_consentboolean
광고 푸시 알림 수신 동의 여부입니다.
marketing_notification_kakao_consentboolean
광고 카카오톡 수신 동의 여부입니다.

응답

Promise<void>

setCustomUserProperties()

setUserProperties()로 설정하는 기본 정보 이외의 추가 정보를 설정합니다.

bluxClient.setCustomUserProperties({
	customUserProperties: {
		"membership_level": "GOLD",
		"available_points": 12000,
		"is_active": true,
		"last_login_date": "2025-06-17T11:15:00.123+09:00",
	}
});

파라미터

customUserProperties필수Record<string, string | boolean | number | null>

유저의 추가 정보입니다. 예를 들어, 회원 등급, 잔여 포인트, 활성 여부, 최근 로그인 일시 등을 설정할 수 있습니다. 블럭스의 유저 세그멘테이션에 사용되고 있어요.

응답

Promise<void>

이벤트

Event 객체

유저의 행동 데이터를 담고 있는 객체입니다. 행동의 종류, 정보, 발생 시간 등을 자세히 알 수 있습니다.

기본 이벤트

기본 이벤트는 블럭스가 미리 정의해 둔 이벤트 객체입니다. 자주 쓰이는 장바구니 담기, 좋아요 누르기, 상세페이지 진입하기 등의 이벤트를 포함합니다.

AddProductDetailViewEvent

유저가 상품의 상세 정보를 탐색한 순간이에요. 예를 들어, 유저가 상품의 상세페이지에 진입한 순간을 의미해요.

const addProductDetailViewEvent = new AddProductDetailViewEvent({
	itemId: "ITEM_ID",
	customEventProperties: {
		brandName: "Nike",
		categoryName: "Shoes",
	},
});

객체 상세

itemId필수string

상품을 식별하는 고유 아이디입니다. 연동 시 사용한 상품 아이디를 입력하세요.

customEventPropertiesMap<String, Object>

이벤트 추가 속성입니다. 위 속성 이외의 속성을 추가하고 싶다면 이 필드를 사용하세요.

AddCartaddEvent

유저가 상품에 대한 강한 선호를 표현한 순간이에요. 예를 들어, 유저가 상품을 장바구니에 담은 순간을 의미해요.

const addCartaddEvent = new AddCartaddEvent({
	itemId: "ITEM_ID",
	customEventProperties: {
		brandName: "Nike",
		addedFrom: "product_detail",
	},
});

객체 상세

itemId필수string

상품을 식별하는 고유 아이디입니다. 연동 시 사용한 상품 아이디를 입력하세요.

customEventPropertiesMap<String, Object>

이벤트 추가 속성입니다. 위 속성 이외의 속성을 추가하고 싶다면 이 필드를 사용하세요.

AddOrderEvent

유저가 상품을 구매하여 비용을 지불한 순간이에요.

const addOrderEvent = new AddOrderEvent({
	items: [
		{
			id: "ITEM_ID_1",
			price: 1000,
			quantity: 1,
			custom_event_properties: {
				brandName: "Nike",
				optionName: "Black / 270",
			},
		},
	],
	orderId: "ORDER_ID",
	paidAmount: 1200,
	orderAmount: 2000,
	customEventProperties: {
		couponCode: "WELCOME10",
		paymentMethod: "kakao_pay",
	},
});

객체 상세

items필수List<Item>

주문에 포함된 상품 목록입니다. 상품 아이디 (id), 상품 가격 (price), 상품 수량 (quantity)을 입력하세요.

orderId필수string

주문을 식별하는 고유 아이디입니다.

orderAmount필수number

해당 주문건의 총 주문 금액입니다.

paidAmount필수number

유저가 해당 주문에서 실제 결제한 금액입니다. 캠페인 성과 페이지에서 해당 필드를 기준으로 계산됩니다.

customEventPropertiesMap<String, Object>

이벤트 추가 속성입니다. 위 속성 이외의 속성을 추가하고 싶다면 이 필드를 사용하세요.

AddLikeEvent

유저가 상품에 대한 약한 선호를 표현한 순간이에요. 예를 들어, 유저가 상품에 좋아요 버튼을 누른 순간을 의미해요.

const addLikeEvent = new AddLikeEvent({
	itemId: "ITEM_ID",
	customEventProperties: {
		brandName: "Nike",
		collectionName: "Spring 2026",
	},
});

객체 상세

itemId필수string

상품을 식별하는 고유 아이디입니다. 연동 시 사용한 상품 아이디를 입력하세요.

customEventPropertiesMap<String, Object>

이벤트 추가 속성입니다. 위 속성 이외의 속성을 추가하고 싶다면 이 필드를 사용하세요.

AddRateEvent

유저가 상품에 대한 선호를 구체적인 숫자로 표현한 순간이에요. 예를 들어, 유저가 상품에 별점을 남기는 순간을 의미해요.

const addRateEvent = new AddRateEvent({
	itemId: "ITEM_ID",
	rating: 4.5,
	customEventProperties: {
		brandName: "Nike",
		reviewSource: "in_app",
	},
});

객체 상세

itemId필수string

상품을 식별하는 고유 아이디입니다. 연동 시 사용한 상품 아이디를 입력하세요.

rating필수number

상품에 대한 유저의 평가 점수입니다.

customEventPropertiesMap<String, Object>

이벤트 추가 속성입니다. 위 속성 이외의 속성을 추가하고 싶다면 이 필드를 사용하세요.

커스텀 이벤트

커스텀 이벤트는 고객님이 직접 정의할 수 있는 이벤트 객체입니다. 기본 이벤트가 아닌 행동 데이터를 수집해야 할 때 이용하세요

* 커스텀 이벤트 사용이 필요하다면, 블럭스에 문의하세요.

const addCustomEvent = new AddCustomEvent({
  eventType: "CUSTOM_EVENT",
  customEventProperties: {
    custom_key1: "any_value",
    custom_key2: true,
    custom_key3: 300,
  },
});

파라미터

eventType필수string

이벤트 타입입니다. 기본 이벤트 인스턴스 생성 시, 블럭스 SDK가 자동으로 할당합니다. 커스텀 이벤트 인스턴스 생성 시에는 직접 할당하세요.

customEventPropertiesRecord<string, any>

이벤트 추가 속성입니다.

sendEvent()

유저의 행동 데이터를 블럭스 데이터베이스에 저장합니다.

bluxClient.sendEvent(
	new AddOrderEvent({
		items: [
			{
				id: "ITEM_ID_1",
				price: 1000,
				quantity: 1,
				custom_event_properties: {
					brandName: "Nike",
					optionName: "Black / 270",
				},
			},
		],
		orderId: "ORDER_ID",
		paidAmount: 1200,
		orderAmount: 2000,
	})
)

파라미터

event필수Event

유저 행동 데이터를 담은 이벤트입니다. 기본 이벤트 혹은 커스텀 이벤트 인스턴스를 입력하세요.

응답

void

푸시 알림

getNotifications()

* Web SDK 2.2.28 이상에서 지원됩니다.

현재 유저에게 블럭스로 발송된 앱푸시 알림 이력을 조회합니다. 알림함 노출, 발송 히스토리 표시 등에 사용하세요. 응답은 발송 시각 내림차순으로 정렬됩니다.

const { notifications, nextCursor } = await bluxClient.getNotifications({
	limit: 30,
	fromSentAt: "2026-05-01T00:00:00.000Z",
});

파라미터

limitnumber

한 번에 조회할 알림 개수입니다. 기본값은 50이고 최댓값은 100입니다.

fromSentAtstring | Date

이 시각 이후에 발송된 알림만 조회합니다. ISO 8601 문자열 또는 Date 객체를 입력하세요.

toSentAtstring | Date

이 시각 이전에 발송된 알림만 조회합니다. ISO 8601 문자열 또는 Date 객체를 입력하세요.

cursorstring

다음 페이지를 가져올 때 이전 응답의 nextCursor 값을 그대로 전달하세요.

응답

Promise<{ notifications, nextCursor? }>

응답

notifications필수List<Notification>

조회된 알림 목록입니다. 발송 시각 내림차순으로 정렬됩니다.

id필수string
알림을 식별하는 고유 아이디입니다.
title필수string
푸시 알림의 제목입니다.
body필수string
푸시 알림의 본문입니다.
imageUrlstring
푸시 알림에 첨부된 이미지 URL입니다.
urlstring
푸시 알림 클릭 시 이동할 랜딩 URL입니다.
sentAt필수string
알림 발송 시각입니다. ISO 8601 형식의 문자열입니다.

nextCursorstring

다음 페이지 조회용 커서입니다. 더 이상 조회할 알림이 없으면 응답에 포함되지 않습니다.

* 발송된 지 60일이 지난 알림은 응답에 포함되지 않습니다.

* fromSentAt은 toSentAt보다 같거나 이전이어야 합니다. 그렇지 않으면 400 에러를 반환합니다.

Custom HTML 인앱 메시지

Custom HTML 인앱 메시지를 사용하면 자유로운 형태의 인앱 메시지를 표시하고, 앱 내에서 커스텀 액션을 처리할 수 있습니다.

개인화 변수

HTML 본문에 {{ 변수명 }} 문법으로 유저 속성을 참조할 수 있습니다. 정의되지 않은 변수는 빈 문자열로 대체되므로 default 필터로 기본값을 지정하는 것을 권장합니다.

<h1>{{ name | default: "고객" }}님 안녕하세요</h1>
<p>{{ phone_number }}</p>

사용 가능한 전체 변수 목록은 블럭스 콘솔의 Custom HTML 에디터에서 확인할 수 있습니다.

변수 출력과 default 필터만 지원합니다. {% if %}, {% for %} 등 제어 태그나 upcase, round 등 다른 필터는 사용할 수 없습니다. 잘못된 문법은 인앱 메시지 저장 시 차단됩니다.

유저 속성 값에 포함된 HTML 특수문자는 서버에서 자동으로 이스케이프되어 표시됩니다. 따라서 유저 입력값을 변수로 사용해도 XSS 위험이 없습니다.

BluxBridge API

Custom HTML 인앱 메시지 내에서 BluxBridge 객체를 사용하여 SDK와 통신할 수 있습니다.

BluxBridge.triggerAction()

BluxBridge.triggerAction(actionId, data?, shouldDismiss?)

파라미터

actionId필수string

액션 식별자입니다. 커스텀 핸들러에서 어떤 액션인지 구분하는 데 사용됩니다.

dataRecord<string, any>

액션과 함께 전달할 데이터입니다. 기본값은 빈 객체({})입니다.

shouldDismissboolean

인앱 메시지를 닫을지 여부입니다. 기본값은 true입니다. 즉, 별도로 지정하지 않으면 액션 호출 시 인앱 메시지가 자동으로 닫힙니다. 인앱 메시지를 유지하려면 명시적으로 false를 전달하세요.

사용 예시

<!-- 기본 사용: 닫기 버튼 (shouldDismiss 기본값 true) -->
<button onclick="BluxBridge.triggerAction('close')">닫기</button>

<!-- 커스텀 액션 호출 (기본적으로 인앱 닫힘) -->
<button
  onclick="BluxBridge.triggerAction('share', { url: 'https://example.com' })"
>
  공유하기
</button>

<!-- 인앱 메시지 유지: shouldDismiss를 false로 설정 -->
<button onclick="BluxBridge.triggerAction('like', { itemId: '123' }, false)">
  좋아요
</button>

shouldDismiss의 기본값이 true이므로, 대부분의 버튼 클릭은 자동으로 인앱 메시지를 닫습니다. 비동기 작업 후 수동으로 닫아야 하거나, 인앱 메시지를 유지한 채 여러 액션을 처리하려면 shouldDismiss: false를 사용하세요.

BluxBridge.resize()

* Web SDK 2.2.15 이상에서 지원됩니다.

인앱 메시지의 크기와 위치를 변경합니다. 두 가지 방식을 지원합니다.

배너 모드 — 화면 상단 또는 하단에 배너 형태로 배치합니다.

BluxBridge.resize({ height, location });

파라미터

height필수number

배너의 높이(px)입니다.

location필수'top' | 'bottom'

배너를 화면 상단에 배치할지 하단에 배치할지 지정합니다.

절대 위치 모드 — 화면의 원하는 위치에 자유롭게 배치합니다.

BluxBridge.resize({ width?, height?, top?, bottom?, left?, right? })

파라미터

widthnumber

인앱 메시지의 너비(px)입니다. 지정하지 않으면 화면 전체 너비를 사용합니다.

heightnumber

인앱 메시지의 높이(px)입니다. 지정하지 않으면 화면 전체 높이를 사용합니다.

topnumber

화면 상단으로부터의 거리(px)입니다.

bottomnumber

화면 하단으로부터의 거리(px)입니다.

leftnumber

화면 좌측으로부터의 거리(px)입니다.

rightnumber

화면 우측으로부터의 거리(px)입니다.

사용 예시

<!-- 배너 모드: 하단 배너 -->
<button onclick="BluxBridge.resize({ height: 80, location: 'bottom' })">
  하단 배너
</button>

<!-- 절대 위치: 하단 바 -->
<button
  onclick="BluxBridge.resize({ height: 70, bottom: 16, left: 16, right: 16 })"
>
  하단 바
</button>

<!-- 절대 위치: 우상단 토스트 -->
<button
  onclick="BluxBridge.resize({ width: 320, height: 60, top: 20, right: 20 })"
>
  토스트
</button>

<!-- 절대 위치: 좌하단 플로팅 -->
<button
  onclick="BluxBridge.resize({ width: 200, height: 64, bottom: 80, left: 16 })"
>
  플로팅 위젯
</button>

절대 위치 모드에서 top과 bottom을 동시에 지정하면 top이 우선됩니다. left와 right를 동시에 지정하면 left가 우선되며, width는 화면 너비에서 left와 right를 뺀 값이 됩니다. 모바일 앱에서는 절대 위치 좌표가 safe area 안쪽을 기준으로 적용됩니다. 자세한 동작은 각 플랫폼 문서를 참고하세요.

BluxBridge.close()

인앱 메시지를 닫으며, 선택적으로 특정 기간 동안 다시 표시하지 않도록 설정합니다.

BluxBridge.close(daysToHide?)

파라미터

daysToHidenumber

인앱 메시지를 다시 표시하지 않을 일수입니다. 생략하거나 0을 전달하면 닫기만 합니다.

<!-- 7일간 보지 않기 -->
<button onclick="BluxBridge.close(7)">7일간 보지 않기</button>

<!-- 1일간 보지 않기 -->
<button onclick="BluxBridge.close(1)">오늘 하루 보지 않기</button>

<!-- 닫기만 -->
<button onclick="BluxBridge.close()">닫기</button>

클릭 추적 (data-blux-click)

data-blux-click 속성을 사용하면 요소 클릭 시 자동으로 inapp_opened 이벤트가 전송됩니다. 인앱 메시지 내 버튼 클릭률을 추적할 때 사용합니다.

<!-- 클릭 시 inapp_opened 이벤트 전송 -->
<a href="https://example.com" data-blux-click="main-cta">자세히 보기</a>

<!-- 버튼에도 사용 가능 -->
<button data-blux-click="secondary-cta" onclick="...">확인</button>

data-blux-click 속성이 있는 요소를 클릭하면 inapp_opened 이벤트가 전송되지만, 인앱 메시지는 닫히지 않습니다. 인앱 메시지를 닫으려면 BluxBridge.triggerAction('close')를 호출하세요.

addInAppCustomActionHandler()

Custom HTML 인앱 메시지에서 BluxBridge.triggerAction() 호출 시 실행될 핸들러를 등록합니다. 여러 핸들러를 등록할 수 있으며, 등록 순서대로 실행됩니다.

const unsubscribe = bluxClient.addInAppCustomActionHandler((event) => {
if (event.actionId === 'share') {
	// 공유 로직 구현
	navigator.share({ url: event.data.url });
} else if (event.actionId === 'navigate') {
	// 페이지 이동 로직 구현
	window.location.href = event.data.url;
}
});

// 핸들러 제거
unsubscribe();

파라미터

handler필수(event: InAppCustomActionEvent) => void

커스텀 액션 핸들러 함수입니다.

event.actionId필수string
액션 식별자입니다. HTML에서 triggerAction()의 첫 번째 인자로 전달한 값입니다.
event.data필수Record<string, any>
액션과 함께 전달된 데이터입니다. HTML에서 triggerAction()의 두 번째 인자로 전달한 값입니다.

응답

Function (unsubscribe function)

dismissInApp()

현재 표시 중인 인앱 메시지를 프로그래밍 방식으로 닫습니다. 비동기 작업 완료 후 수동으로 인앱 메시지를 닫아야 할 때 사용합니다.

bluxClient.addInAppCustomActionHandler(async (event) => {
if (event.actionId === 'share') {
	await navigator.share({ url: event.data.url });
	// 비동기 작업 완료 후 수동으로 닫기
	bluxClient.dismissInApp();
}
});

// HTML에서 shouldDismiss: false로 호출
// BluxBridge.triggerAction('share', { url: '...' }, false);

응답

void

SDK 설치​

BluxClient 초기화​

파라미터

유저​

signIn()​

파라미터

응답

signOut()​

응답

setUserProperties()​

파라미터

응답

setCustomUserProperties()​

파라미터

응답

이벤트​

Event 객체​

기본 이벤트​

객체 상세

객체 상세

객체 상세

객체 상세

객체 상세

커스텀 이벤트​

파라미터

sendEvent()​

파라미터

응답

푸시 알림​

getNotifications()​

파라미터

응답

응답

Custom HTML 인앱 메시지​

개인화 변수​

BluxBridge API​

BluxBridge.triggerAction()​

파라미터

사용 예시​

BluxBridge.resize()​

파라미터

파라미터

사용 예시​

BluxBridge.close()​

파라미터

클릭 추적 (data-blux-click)​

addInAppCustomActionHandler()​

파라미터

응답

dismissInApp()​

응답

SDK 설치

BluxClient 초기화

유저

signIn()

signOut()

setUserProperties()

setCustomUserProperties()

이벤트

Event 객체

기본 이벤트

커스텀 이벤트

sendEvent()

푸시 알림

getNotifications()

Custom HTML 인앱 메시지

개인화 변수

BluxBridge API

BluxBridge.triggerAction()

사용 예시

BluxBridge.resize()

사용 예시

BluxBridge.close()

클릭 추적 (data-blux-click)

addInAppCustomActionHandler()

dismissInApp()