Node
최신 버전: v0.0.2
업데이트 날짜: 2026-10-29
1. 개요
AE 6.1 버전부터 실험 키트는 AE 콘솔에서 실험을 만들고 대조군과 실험 그룹에 서로 다른 변수 값을 설정하는 기능을 지원합니다. Node.js 서버단 실험 SDK는 이러한 Feature 설정을 가져오는 데 사용됩니다. 비즈니스에서 현재 사용자 식별 정보와 Feature Key를 전달하면 설정 센터(RCC)가 원격 분기를 수행하고, SDK가 설정값과 일치한 실험 정보를 반환합니다. 비즈니스에서 설정을 사용한 후 실제 노출 시점에 맞춰 이벤트를 전송합니다.
- Feature Key는 AE 콘솔에서 설정한 변수 식별자입니다. 예시에서는 checkout_button을 사용하며, 통합 시 프로젝트에서 실제 게시한 Key로 바꿉니다.
- createClient()는 클라이언트를 검증하고 만들기만 합니다. 네트워크에 접근하거나 설정을 자동으로 가져오지 않습니다. client.fetch(request)를 통해 조회를 시작합니다.
- 실험과 일치하지 않아도 AE 콘솔의 기본 설정값이 반환될 수 있습니다. Feature에 값이 있는지와 실험과 일치하는지는 서로 별도로 판단해야 합니다.
- 현재 버전은 원격 분기(REMOTE)만 지원합니다. LOCAL은 예약된 값이며 전달하면 INVALID_CONFIG 오류가 발생합니다. 결과 캐시와 비즈니스 기본값은 로컬 분기를 수행하지 않습니다.
2. 통합
2.1 환경 및 의존성
Node.js 12.0.0 이상이 필요합니다. SDK는 CommonJS로 배포되며 TypeScript 타입 선언을 제공합니다. 아래 CommonJS 예시는 최소 지원 런타임에서 사용할 수 있습니다.
SDK는 npm에 게시되어 있습니다. 최신 버전을 설치합니다.
npm install td-feature-node@latest
npm은 프로덕션 의존성도 함께 설치하며, 공식 데이터 수집 SDK는 thinkingdata-node@1.5.0입니다. 비즈니스 실행 시 TypeScript나 다른 개발 도구는 필요하지 않습니다. 설치하려면 설정된 npm registry에 접근할 수 있어야 합니다.
2.2 통합 전 준비
| 정보 | 용도 |
|---|---|
| appId | 실험 프로젝트의 App ID입니다. 플랫폼에서 제공한 값을 사용합니다. |
| serverUrl | 원격 의사 결정과 노출 수집을 지원하는 서비스 기본 주소입니다. 예: https://service.example.com. |
| Feature Key | 플랫폼에서 설정하고 게시한 변수 식별자입니다. |
| 현재 사용자 식별 정보 | accountId와 distinctId 중 하나 이상이 비어 있지 않은 문자열이어야 하며, AE 콘솔의 분할 단위 및 타겟 사용자 조건을 충족해야 합니다. |
| 사용자 지정 요청 파라미터 | AE 콘솔 규칙에 필요한 컨텍스트입니다. 파라미터 이름, 타입, 의미가 AE 콘솔 설정과 일치해야 합니다. |
3. 초기화 및 빠른 시작
3.1 전체 예시
quickstart.js로 저장하고 App ID, 서비스 주소, 사용자 식별 정보, 비즈니스 Key를 실제 값으로 바꾼 다음 node quickstart.js를 실행합니다. 이 예시는 기본 설정으로 모든 Key를 가져오고 checkout_button을 읽은 후, 결과를 사용한 뒤 수동으로 노출을 전송합니다. SDK는 데이터 수집 인스턴스를 자동으로 만듭니다.
const { createClient, SplitMode } = require('td-feature-node');
// 장기 실행 서비스에서는 프로세스별, 프로젝트별로 하나의 Client를 재사용합니다.
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
splitMode: SplitMode.REMOTE,
});
async function main() {
try {
const config = await client.fetch({
accountId: 'user_123',
distinctId: 'visitor_456',
// featureKeys를 지정하지 않으면 현재 식별 정보로 조회 가능한 모든 설정을 가져옵니다.
});
console.log('이번 요청에서 반환된 모든 Feature Key:', Object.keys(config.features));
const feature = config.features['checkout_button'];
const buttonStyle = feature ? feature.asString('control') : 'control';
console.log('사용한 버튼 스타일:', buttonStyle); // 실제 비즈니스 로직으로 바꿉니다.
// 결과를 실제로 사용한 후 노출을 전송합니다. 유효한 실험과 일치하지 않으면 SDK가 건너뜁니다.
client.expose(feature, { scene: 'checkout' });
} catch (error) {
// 요청 실패 시 비즈니스 기본값을 사용하며 실험 결과를 만들거나 노출을 전송하지 않습니다.
console.error('설정 요청 실패:', error.code, error.message);
console.log('사용한 버튼 스타일: control');
} finally {
// 이 코드는 일회성 스크립트입니다. 장기 실행 서비스는 애플리케이션 종료 시에만 공유 Client를 닫습니다.
await client.close();
}
}
main().catch(function (error) {
console.error(error);
process.exitCode = 1;
});
장기 실행 서비스는 각 프로세스 내에서 프로젝트와 서비스 주소별로 Client를 재사용해야 합니다. 각 비즈니스 요청에 현재 사용자의 식별 정보를 전달합니다. 요청마다 Client를 만들거나 닫지 말고, 서로 다른 사용자 간에 Feature를 재사용하지 마세요. client.options는 정규화된 읽기 전용 설정이며, client.closed는 종료가 시작되었는지를 나타냅니다.
3.2 기존 데이터 수집 인스턴스 재사용
비즈니스에서 이미 공식 Node.js 데이터 수집 SDK를 사용하고 있다면 기존 인스턴스의 Consumer, 배치 및 주기적 플러시 설정을 유지합니다. 데이터 수집 인스턴스 초기화가 완료된 후 동일한 인스턴스를 tdAnalytics에 전달합니다.
const { createClient, SplitMode } = require('td-feature-node');
// existingAnalytics는 비즈니스에서 초기화한 track/flush/close 인스턴스입니다.
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
splitMode: SplitMode.REMOTE,
tdAnalytics: existingAnalytics,
});
인스턴스를 주입하지 않으면 SDK가 최초 노출 시 동일한 appId와 serverUrl로 공식 Batch 데이터 수집 인스턴스를 지연 생성합니다.
3.3 ESM 및 TypeScript
ESM 프로젝트는 기본 가져오기로 CommonJS 패키지를 사용합니다. 가져오기 구문은 아래와 같으며, 나머지 호출은 async 함수 안에 작성합니다.
import sdk from 'td-feature-node';
const { createClient, SplitMode } = sdk;
TypeScript 프로젝트는 API와 공개 타입을 직접 가져올 수 있습니다. 컴파일 도구 버전은 비즈니스 프로젝트에 맞춰야 합니다.
import { createClient, SplitMode } from 'td-feature-node';
import type { ClientOptions, FeatureRequest } from 'td-feature-node';
const options: ClientOptions = {
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
splitMode: SplitMode.REMOTE,
};
const client = createClient(options);
const request: FeatureRequest = {
accountId: 'user_123',
featureKeys: ['checkout_button'],
};
3.4 초기화 설정 참조
3.4.1 연결 및 요청
| 설정 | 기본값 | 설명 |
|---|---|---|
| appId | 필수 | 비어 있지 않은 문자열 형식의 프로젝트 App ID입니다. |
| serverUrl | 필수 | 원격 의사 결정과 SDK가 자체 생성한 데이터 수집에 공통으로 사용하는 HTTP(S) 기본 주소입니다. |
| splitMode | SplitMode.REMOTE | 문자열 REMOTE도 전달할 수 있습니다. LOCAL은 현재 지원하지 않습니다. |
| timeout | 5000 ms | 각 HTTP 시도의 제한 시간입니다. |
| maxHttpConnections | 20 | RCC 연결 풀의 최대 연결 수입니다. |
| tlsCa | Node의 기본 신뢰 루트 | 선택 사항인 PEM CA 문자열 또는 배열입니다. 명시적으로 설정하면 해당 Client의 기본 CA 목록을 대체합니다. |
3.4.2 재시도
| 설정 | 기본값 | 설명 |
|---|---|---|
| retryTimes | 0 | 첫 요청 이후의 추가 재시도 횟수이며, 범위는 0~10입니다. |
| retryStrategy | EXPONENTIAL_BACKOFF | FIXED_INTERVAL도 선택할 수 있습니다. |
| retryInterval | 500 ms | 초기 백오프 간격입니다. 0도 허용됩니다. |
3.4.3 결과 캐시
| 설정 | 기본값 | 설명 |
|---|---|---|
| enableCache | false | 성공한 결과의 캐싱을 명시적으로 활성화합니다. |
| cacheExpireTime | 86400초 | RCC TTL이 0 이하일 때만 대체값으로 사용합니다. 0도 허용됩니다. |
| maxCacheSize | 10000 | 결과 캐시 항목의 최대 개수입니다. 0이면 저장하지 않습니다. |
3.4.4 노출 및 데이터 수집
| 설정 | 기본값 | 설명 |
|---|---|---|
| autoExposure | false | 원시 값 또는 타입별 값을 처음 읽을 때 노출 전송을 시도합니다. |
| exposureDedupMaxSize | 100000 | 노출 중복 제거 항목의 최대 개수입니다. |
| exposureDedupExpireSeconds | 86400초 | 비슬라이딩 중복 제거 TTL입니다. |
| tdAnalytics | 지정하지 않음 | 비즈니스에서 기존에 사용하는 공식 데이터 수집 인스턴스입니다. 비즈니스에서 소유하고 닫습니다. |
| exposureAdapter | 지정하지 않음 | 사용자 지정 데이터 수집 어댑터입니다. tdAnalytics와 함께 지정할 수 없으며 비즈니스에서 소유합니다. |
3.4.5 사설 CA 및 사용자 지정 데이터 수집
사설 CA를 사용할 때는 신뢰하는 인증서를 명시적으로 전달할 수 있습니다. 인증서 체인과 호스트 이름 검증은 계속 적용됩니다. tlsCa는 RCC와 SDK가 자체 생성한 수집기에만 영향을 줍니다. 외부 인스턴스는 자체 TLS 설정을 계속 사용합니다.
const fs = require('fs');
const { createClient } = require('td-feature-node');
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
tlsCa: fs.readFileSync('/path/to/trusted-ca.pem', 'utf8'),
});
4. 설정 및 실험 정보 가져오기
4.1 현재 사용자 식별 정보 전달
| 요청 파라미터 | 의미 | 사용 요구 사항 |
|---|---|---|
| accountId | #account_id에 해당하는 계정 ID | 계정을 기준으로 분기할 때 안정적이고 정확한 계정 식별자를 전달합니다. |
| distinctId | #distinct_id에 해당하는 방문자 또는 디바이스 ID | 방문자를 기준으로 분기할 때 AE 콘솔 정의와 일치하는 식별자를 전달합니다. |
accountId와 distinctId 중 하나 이상이 비어 있지 않은 문자열이어야 하며, 둘 다 전달할 수도 있습니다. 숫자 ID는 비즈니스에서 명시적으로 문자열로 변환해야 합니다. 식별 정보에는 제어 문자를 포함할 수 없습니다.
4.2 하나 이상의 Feature 가져오기
client.fetch(request, options?)는 Promise<Evaluation>을 반환합니다. 아래 부분 예시의 client는 3절에서 만든 공유 Client이며, await 호출은 async 함수 안에 작성해야 합니다. 단일 Key와 여러 Key 모두 featureKeys 배열을 사용합니다.
const config = await client.fetch({
accountId: 'user_123',
distinctId: 'visitor_456',
featureKeys: ['checkout_button', 'recommendation_enabled'],
});
const feature = config.features['checkout_button'];
4.3 타입별 설정값 읽기
| AE 콘솔의 변수 타입 | 읽기 메서드 | 반환 타입 및 대체 규칙 |
|---|---|---|
| 문자열 | feature.asString(defaultValue) | string. null이 아닌 값을 문자열로 변환하고, 객체와 배열은 JSON 텍스트로 변환합니다. |
| 숫자 | feature.asNumber(defaultValue) | number. 숫자 또는 비어 있지 않은 숫자 문자열을 허용하며, 네이티브 Number()로 변환합니다. |
| 불리언 | feature.asBoolean(defaultValue) | boolean. 불리언 값과 대소문자를 구분하지 않는 true/false 문자열을 허용합니다. 숫자 0/1은 변환하지 않습니다. |
| JSON 객체 | feature.asJson(defaultValue) | JSON 객체. 객체 또는 객체로 파싱할 수 있는 JSON 문자열을 허용합니다. 배열, null, 유효하지 않은 JSON은 대체값을 사용합니다. |
| 원시 값 | feature.value | 배열과 null을 포함하는 원시 JSON 값입니다. |
const config = await client.fetch({
accountId: 'user_123',
featureKeys: ['recommendation_enabled', 'discount_rate', 'page_config'],
});
const enabledFeature = config.features['recommendation_enabled'];
const enabled = enabledFeature ? enabledFeature.asBoolean(false) : false;
const rateFeature = config.features['discount_rate'];
const rate = rateFeature ? rateFeature.asNumber(0) : 0;
const defaults = { theme: 'default' };
const pageFeature = config.features['page_config'];
const page = pageFeature ? pageFeature.asJson(defaults) : defaults;
네 가지 타입별 읽기 메서드는 기본값을 생략하면 대체값으로 null을 사용합니다. 값이 null이거나 변환할 수 없으면 전달한 기본값을 사용합니다. 설정 누락과 변환 실패는 각각 처리해야 합니다. false, 0, 빈 문자열은 유효한 값이므로 value || defaultValue로 덮어쓰지 마세요.
4.4 실험 정보 가져오기
const feature = config.features['checkout_button'];
if (feature) {
console.log('Feature Key:', feature.key);
console.log('값 존재 여부:', feature.hasValue);
const info = feature.experiment;
if (info && info.experimentId && info.experimentGroupId) {
console.log('실험 ID:', info.experimentId);
console.log('그룹 ID:', info.experimentGroupId);
console.log('대조군 여부:', info.isControlGroup);
console.log('버킷 식별 정보:', info.bucketId);
}
}
4.5 현재 요청에 보이는 모든 설정 가져오기
const all = await client.fetch({
accountId: 'user_123',
distinctId: 'visitor_456',
});
const keys = Object.keys(all.features);
console.log(keys);
console.log(all.ttl); // RCC의 원래 TTL이며 단위는 초입니다. 캐시의 남은 유효 시간이 아닙니다.
featureKeys를 생략하거나 null 또는 빈 배열로 지정하면 현재 식별 정보와 요청 조건에 따라 서버에서 반환하는 모든 설정을 가져옵니다.
4.6 사용자 지정 요청 파라미터
const config = await client.fetch({
accountId: 'user_123',
featureKeys: ['checkout_button'],
customParams: {
vip_level: 3,
channel: 'app_store',
country: 'CN',
},
});
customParams는 JSON 객체입니다. 파라미터 이름, 타입, 의미가 AE 콘솔 규칙과 일치해야 합니다. 문자열, 유한한 숫자, 불리언, null, 배열, 중첩 객체를 지원합니다. undefined, Date, BigInt, 함수, NaN, Infinity, 순환 참조는 허용하지 않습니다. 객체와 배열의 null은 유지됩니다. #account_id, #distinct_id, #lib, #feature_key는 SDK에서 관리하므로 사용자 지정 파라미터로 덮어쓸 수 없습니다. 사용자 지정 파라미터는 새 분할 단위를 설정하는 것이 아닙니다.
5. 노출 이벤트 전송
노출은 실험 설정이 비즈니스에 실제로 사용되었음을 의미합니다. fetch 성공, Feature 가져오기, 실험 메타데이터 확인만으로는 노출이 발생한 것이 아닙니다. SDK는 데이터 수집 인스턴스를 통해 #experiment_id, #experiment_group_id, #is_control_group, #rule_type="experiment"가 포함된 te_experiment_exposure를 전송합니다. 현재 원격 파싱에서 제공하지 않는 Feature 버전, 분기 출처 등의 필드를 이벤트에 임의로 만들어 넣지 않습니다.
5.1 수동 노출(기본 방식)
기본값은 autoExposure: false입니다. 비즈니스에서 설정을 실제로 사용한 후 이번 요청에서 반환된 Feature 객체를 expose()에 전달합니다. 인자는 Feature Key 문자열이 아닙니다.
const feature = config.features['checkout_button'];
const style = feature.asString('control');
console.log('비즈니스에서 사용한 값:', style); // 실제 비즈니스 로직으로 바꿉니다.
const accepted = client.expose(feature, { scene: 'checkout', channel: 'web' });
console.log('노출 큐 등록 여부:', accepted);
5.2 자동 노출(선택 사항)
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
autoExposure: true,
});
const config = await client.fetch({
accountId: 'user_123',
featureKeys: ['checkout_button'],
});
const feature = config.features['checkout_button'];
const style = feature ? feature.asString('control') : 'control';
활성화하면 유효한 실험 정보가 있는 경우 feature.value를 처음 읽거나 asString/asNumber/asBoolean/asJson을 처음 호출할 때 노출 전송을 시도합니다. 반환된 각 Feature는 자동 노출을 최대 한 번 트리거한 다음 Client 수준의 중복 제거를 거칩니다. 캐시 적중 시에는 독립적인 자동 트리거 상태를 가진 새 Feature를 반환합니다.
5.3 중복 제거, 비동기 전송 및 플러시
- 현재 Client의 메모리에서 "분할 단위 + 실험 ID + 그룹 ID"를 기준으로 중복을 제거합니다. 주체는 bucketId의 첫 번째 비어 있지 않은 항목, accountId, distinctId 순서로 선택합니다. Feature Key는 중복 제거 기준에 포함되지 않으며, 동일한 실험 그룹의 여러 Feature는 한 번의 노출을 공유합니다.
- 중복 제거는 항상 활성화되며, 기본 최대 100000개 항목과 86400초의 TTL을 사용합니다. 읽어도 유효 기간은 연장되지 않습니다. 만료, 용량 제한에 따른 항목 제거, Client 재생성 또는 프로세스 재시작 후에는 다시 전송될 수 있습니다.
- 노출은 용량이 제한된 비동기 큐로 전송됩니다. 기본적으로 대기 슬롯은 10000개이며, 별도로 활성 작업 하나가 있습니다. SDK가 자체 생성한 수집기는 기본적으로 100개씩 배치 처리하며, 배치가 채워지지 않으면 최대 1000 ms 동안 버퍼링합니다.
6. 비동기 설정 가져오기
6.1 async/await 및 Promise
async function readStyle(accountId) {
try {
const config = await client.fetch({
accountId: accountId,
featureKeys: ['checkout_button'],
});
const feature = config.features['checkout_button'];
return feature ? feature.asString('control') : 'control';
} catch (error) {
console.error('설정 요청 실패:', error.code);
return 'control';
}
}
client.fetch({ accountId: 'user_123', featureKeys: ['checkout_button'] })
.then(function (config) {
const feature = config.features['checkout_button'];
console.log(feature ? feature.asString('control') : 'control');
})
.catch(function (error) {
console.error(error.code, error.message);
});
위의 비동기 값 가져오기 예시는 조회만 보여 주며, 기본적으로 노출을 전송하지 않습니다. 반환값을 실제로 사용하는 위치에 5절에 따라 노출 호출을 추가합니다.
6.2 제한 시간, 재시도 및 동시 실행
- timeout은 기본 5000 ms이며, 연결 대기와 응답 읽기를 포함한 각 HTTP 시도에만 적용됩니다. 큐 대기, 재시도 백오프, RCC 필드 디코딩은 이 HTTP 제한 시간에 포함되지 않습니다. 재시도를 활성화하면 각 시도마다 제한 시간을 새로 계산합니다.
- retryTimes는 기본 0이며 자동으로 재시도하지 않습니다. 명시적으로 양수로 설정하면 최대 시도 횟수는 1 + retryTimes입니다. 일시적인 네트워크 오류, 개별 시도의 시간 초과, HTTP 408/429/500/502/503/504는 제한된 횟수만큼 재시도할 수 있습니다. RCC 비즈니스 오류, 유효하지 않은 응답, 영구적인 DNS/인증서 오류 등은 재시도하지 않습니다.
- 기본적으로 활성 fetch는 최대 20개이며 대기 큐는 없습니다(maxQueueSize: 0). 동시 실행 슬롯이 가득 차면 즉시 QUEUE_FULL로 거부합니다. maxQueueSize를 명시적으로 양수로 설정해야 용량이 제한된 FIFO 대기 큐가 활성화되며, 대기 슬롯이 가득 찬 경우에도 거부합니다. 캐시 적중 시에는 큐를 사용하지 않고 바로 반환합니다.

