@humanlabs-kr/link-server-sdk

서버(신뢰 백엔드) 전용 HumanlabsLink 클라이언트. 링크 생성을 위한 패키지입니다.

링크 생성(POST /api/links)은 Cloudflare Access로 보호되는 컨트롤플레인 작업입니다. 유일하게 지원되는 호출자는 Access service token(CF-Access-Client-Id / CF-Access-Client-Secret)을 가진 백엔드입니다. 이 토큰은 비밀이므로 모바일 앱에 절대 넣지 마세요 — 모바일 SDK는 의도적으로 링크를 생성하지 않고, 딥링크/지연 어트리뷰션 수신만 합니다.

설치

npm i @humanlabs-kr/link-server-sdk
# pnpm add @humanlabs-kr/link-server-sdk
# yarn add @humanlabs-kr/link-server-sdk

Node 18+ (전역 fetch 사용). 더 낮은 런타임이면 생성자에 fetch 를 주입하세요.

Service token 사용

두 값을 백엔드 환경변수로 둡니다 (예: HUMANLABSLINK_ACCESS_CLIENT_ID, HUMANLABSLINK_ACCESS_CLIENT_SECRET).

사용법

import { HumanlabsLinkServer } from '@humanlabs-kr/link-server-sdk';

const lf = new HumanlabsLinkServer({
  accessClientId: process.env.HUMANLABSLINK_ACCESS_CLIENT_ID!,
  accessClientSecret: process.env.HUMANLABSLINK_ACCESS_CLIENT_SECRET!,
  // baseUrl 기본값 = production (https://link.humanlabs.world)
});

// 사용자별 referral 링크 — 유저당 1회 생성 후 url 저장/재사용 권장
const link = await lf.createLink({
  appId: 'your-app-uuid',
  originalUrl: 'https://humanlabs.world/invite',
  deepLinkParameters: { ref: userId },   // 앱에서 data.customParameters.ref 로 수신
});

console.log(link.shortUrl);   // 공유할 단축 URL

appId 를 넣으면 해당 앱의 기본값(스킴/스토어 URL)을 상속하고, 정규 URL 이 /<appSlug>/<code> 형태로 생성됩니다. originalUrl 은 서버 스키마상 필수입니다.

중복 방지: 서버는 자동 dedup 을 하지 않습니다. 생성한 shortUrl/id 를 호출 측에서 저장하고 재사용하세요.

동등한 curl

curl -X POST https://link.humanlabs.world/api/links \
  -H "Content-Type: application/json" \
  -H "CF-Access-Client-Id: $HUMANLABSLINK_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $HUMANLABSLINK_ACCESS_CLIENT_SECRET" \
  -d '{"appId":"...","originalUrl":"https://...","deepLinkParameters":{"ref":"user_123"}}'

에러 처리

non-2xx 응답은 HumanlabsLinkServerError 로 던져지며 HTTP status 와 body 를 담습니다.

import { HumanlabsLinkServer, HumanlabsLinkServerError } from '@humanlabs-kr/link-server-sdk';

try {
  const link = await lf.createLink({ appId, originalUrl: 'https://...' });
} catch (e) {
  if (e instanceof HumanlabsLinkServerError) {
    console.error(e.status, e.body);  // 403 = service token 문제, 400 = 잘못된 입력
  }
  throw e;
}

createLink 옵션

| 필드 | 필수 | 설명 | |------|:---:|------| | originalUrl | ✅ | 목적지 URL | | appId | | 소속 앱. 앱 기본값(스킴/스토어 URL) 상속 + /<appSlug>/<code> 정규 URL | | deepLinkParameters | | 앱에 전달할 커스텀 파라미터 (예: { ref: userId }) | | customCode | | 랜덤 대신 지정 단축코드 | | title · description | | 메타데이터 | | utmParameters | | { source, medium, campaign, term, content } | | targetingRules | | { countries, devices, languages } | | iosAppStoreUrl · androidAppStoreUrl · webFallbackUrl | | 스토어/웹 폴백 (appId 기본값 override) | | appScheme · deepLinkPath | | 커스텀 스킴 딥링크 | | attributionWindowHours | | 어트리뷰션 윈도우(1–2160, 기본 168=7일) | | expiresAt | | ISO-8601 만료 시각 | | templateId | | 사용할 템플릿 |

반환 CreatedLink: id, shortCode, shortUrl(공유용), appId, appSlug, originalUrl, deepLinkParameters, utmParameters, attributionWindowHours, isActive, expiresAt, createdAt.

앱에서 파라미터 받기

deepLinkParameters 로 실은 값은 모바일 SDK에서 customParameters 로 들어옵니다 (설치 여부 무관):

// 앱 미설치 → 설치 후 첫 실행 (deferred)
HumanlabsLink.onDeferredDeepLink((data) => {
  const ref = data?.customParameters?.ref;   // 'user_123'
});

// 앱 이미 설치 → 링크로 열림
HumanlabsLink.onDeepLink((_url, data) => {
  const ref = data?.customParameters?.ref;
});