인증 및 라이선스 - Facebetter Docs

SDK 2.0은 라이선스 토큰으로 인증합니다. 네이티브 플랫폼은 온라인 인증에 appId + appKey도 사용할 수 있습니다. Web에서는 프론트엔드 JavaScript에 appKey를 넣지 마세요.

먼저 구독을 완료하세요. 대시보드에서 앱 식별자(Bundle ID / 패키지 이름 / 도메인)를 바인딩하고 요금제를 활성화합니다.

네이티브 (Android / iOS / macOS / Windows)

엔진을 만들 때 다음 중 하나를 전달합니다.

모드	설정 필드	사용 시점
온라인	`appId` + `appKey`	기기가 `/facebetter/v2/auth`에 도달할 수 있을 때
Token	`licenseToken`	라이선스 토큰 문자열, `{token}` JSON, 또는 오프라인 `.lic`

우선순위: licenseToken이 비어 있지 않으면 SDK는 해당 토큰을 로컬에서 검증하며, appId / appKey로 네트워크를 호출하지 않습니다.

권장 방식은 Web과 같습니다. appId / appKey는 서버에 두고, 수명이 짧은 licenseToken을 발급해 앱에 전달하세요. 서명 요청의 platform은 클라이언트와 일치해야 합니다(ios / android / macos / windows). 아래 Web → 서버 프록시를 참고하세요. appId + appKey 직접 전달과 오프라인 .lic도 계속 지원됩니다.

iOS / macOS

FBEngineConfig *config = [[FBEngineConfig alloc] init];
config.licenseToken = @"/* license token, {token} JSON, or .lic contents */";
self.beautyEffectEngine = [FBBeautyEffectEngine createEngineWithConfig:config];

Android

BeautyEffectEngine.EngineConfig config = new BeautyEffectEngine.EngineConfig();
config.licenseToken = "/* license token, {token} JSON, or .lic contents */";
mBeautyEngine = new BeautyEffectEngine(this, config);

C++ (Windows)

facebetter::EngineConfig config;
config.license_token = "/* license token, {token} JSON, or .lic contents */";
config.resource_path = "/path/to/resource.fbd";
auto engine = facebetter::BeautyEffectEngine::Create(config);

네이티브 플랫폼의 온라인 대안:

config.appId = "your appId";
config.appKey = "your appKey";

오프라인 .lic는 소스에 하드코딩하지 말고 앱 에셋으로 넣고 런타임에 로드하는 것을 권장합니다. 발급 방법은 아래 오프라인 라이선스를 참고하세요.

Web

브라우저 SDK에는 appId / appKey 필드가 없습니다. 엔진은 licenseToken만 받으며 로컬에서 검증합니다. init() 전에 서버에서 토큰을 가져오세요.

권장 흐름

대시보드에서 앱을 만들고 Web 도메인을 바인딩한 뒤 appId / appKey를 복사합니다(구독 참고)
키는 백엔드에 두고, 엔드포인트(예: POST /api/facebetter/auth)를 제공합니다
백엔드는 https://facebetter.pixpark.net/facebetter/v2/auth에 서명 요청을 보내고 원본 응답 본문을 페이지에 반환합니다
해당 문자열을 EngineConfig.licenseToken에 전달한 뒤 init()을 호출합니다

공식 데모(demo/web/react)도 같은 패턴입니다. 프론트엔드는 src/fetchLicenseToken.js, 서버 프록시는 api/facebetter/auth.js입니다.

프론트엔드 번들에 appKey를 넣지 마세요. Web 오프라인 .lic는 페이지 origin(예: https://app.example.com)과 일치해야 합니다. Electron은 origin을 검사하지 않습니다. 온라인 토큰은 수 분 안에 만료되므로, 엔진을 다시 만들기 전에 새 토큰을 받으세요.

프론트엔드

import { BeautyEffectEngine, EngineConfig } from 'facebetter';

// Body may be a bare token, or the upstream JSON text (with a token field)
const licenseToken = await fetch('/api/facebetter/auth', {
  method: 'POST',
}).then((r) => {
  if (!r.ok) throw new Error(`auth failed: ${r.status}`);
  return r.text();
});

const engine = new BeautyEffectEngine(new EngineConfig({ licenseToken }));
await engine.init();

서버 프록시 (Node 예시)

FB_APP_ID / FB_APP_KEY를 환경 변수에 저장하세요. Express / Fastify / 서버리스 함수에 그대로 넣을 수 있습니다.

import { createHmac, randomBytes } from 'node:crypto';

const AUTH_URL = 'https://facebetter.pixpark.net/facebetter/v2/auth';

app.post('/api/facebetter/auth', async (req, res) => {
  const appId = process.env.FB_APP_ID;
  const appKey = process.env.FB_APP_KEY;
  if (!appId || !appKey) {
    res.status(500).json({ error: 'FB_APP_ID / FB_APP_KEY not configured' });
    return;
  }

  const nonce = randomBytes(16).toString('hex');
  const timestamp = Math.floor(Date.now() / 1000);
  const platform = 'web';
  // Sign string: v2|{app_id}|{timestamp}|{nonce}|{platform}
  const payload = `v2|${appId}|${timestamp}|${nonce}|${platform}`;
  const hmac = createHmac('sha256', appKey).update(payload).digest('hex');

  const upstream = await fetch(AUTH_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      app_id: appId,
      hmac_signature: hmac,
      timestamp,
      nonce,
      platform,
      user_agent: req.headers['user-agent'] || '',
    }),
  });

  // Forward as-is for EngineConfig.licenseToken
  res.status(upstream.status).send(await upstream.text());
});

다른 언어에서도 단계는 같습니다. 서명 문자열 구성 → HMAC-SHA256(hex) → 업스트림 POST → 본문을 프론트엔드에 전달. 실행 가능한 참고 구현: GitHub Demo api/facebetter/auth.js.

업스트림 요청 필드

필드	설명
`app_id`	대시보드 AppID
`hmac_signature`	`v2\|{app_id}\|{timestamp}\|{nonce}\|web`의 HMAC-SHA256, hex 인코딩
`timestamp`	Unix 초
`nonce`	난수 문자열(16바이트 이상 hex 권장)
`platform`	항상 `web`
`user_agent`	선택. 가능하면 브라우저 UA를 전달합니다

성공 시 업스트림은 JSON(token 필드 포함)을 반환합니다. 응답 텍스트를 그대로 전달하거나 token 문자열만 추출해도 됩니다. SDK는 둘 다 받습니다.

오프라인 라이선스

대시보드 인증 정보 페이지에서 오프라인 .lic를 받아 전체 내용을 licenseToken / license_token으로 전달하세요. 유료 플랜은 저장된 식별자를 잠급니다. 비어 있는 플랫폼은 한 번만 입력할 수 있습니다. 잠긴 값을 바꾸려면 지원에 문의하세요. 무료 플랜은 식별자를 바꾸고 언제든 다운로드할 수 있습니다. 파일은 구독 종료 15일 후에 만료됩니다. 다시 받아도 날짜는 늘어나지 않습니다. 갱신 후 새 파일을 다운로드하세요.

참고

온라인 토큰과 오프라인 라이선스 모두 대시보드의 앱 식별자를 확인합니다. iOS / macOS는 Bundle ID, Android는 패키지 이름, Windows / Linux는 실행 파일 이름, 브라우저는 페이지 origin입니다. Electron은 origin을 검사하지 않습니다. 불일치하면 검증이 실패합니다.
만료되지 않음: 기능은 구독 요금제를 따릅니다.
만료됨: 엔진은 초기화할 수 있지만, 기능은 Free 요금제로 떨어집니다(워터마크 체험). 갱신 후 대시보드에서 새 파일을 다운로드하세요.
Web 오프라인 라이선스는 페이지 origin에 바인딩됩니다. .lic 전문을 licenseToken에 전달하세요.

엔진 이벤트

onEngineEvent로 라이선스와 초기화 결과를 수신합니다.

코드	이름	의미
0	`LICENSE_VALIDATION_SUCCESS`	토큰 / 온라인 인증 성공
1	`LICENSE_VALIDATION_FAILED`	인증 실패(message 참고)
100	`INITIALIZATION_COMPLETE`	엔진 준비 완료
101	`INITIALIZATION_FAILED`	엔진 초기화 실패

​네이티브 (Android / iOS / macOS / Windows)

​Web

​권장 흐름

​프론트엔드

​서버 프록시 (Node 예시)

​업스트림 요청 필드

​오프라인 라이선스

​참고

​엔진 이벤트

네이티브 (Android / iOS / macOS / Windows)

Web

권장 흐름

프론트엔드

서버 프록시 (Node 예시)

업스트림 요청 필드

오프라인 라이선스

참고

엔진 이벤트