Auth & License

SDK 2.0 authenticates with a license token. Native platforms can also use appId + appKey for online auth. Web must never embed appKey in frontend JavaScript.

Complete Subscription first: bind your app identifiers in the Dashboard (Bundle ID / package name / domain) and enable a plan.

Native (Android / iOS / macOS / Windows)

Pass one of the following when creating the engine:

Mode	Config fields	When to use
Online	`appId` + `appKey`	Device can reach `/facebetter/v2/auth`
Token	`licenseToken`	License token string, `{token}` JSON, or native offline `.lic`

Priority: if licenseToken is non-empty, the SDK validates that token locally and does not call the network with appId / appKey.

Recommended (same idea as Web): keep appId / appKey on your server, mint a short-lived licenseToken, and deliver it to the app. Set platform in the signed request to match the client (ios / android / macos / windows). See Web → Server proxy below. Direct appId + appKey and offline .lic remain supported.

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);

Online alternative on native platforms:

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

Prefer shipping the offline .lic as an app asset and loading it at runtime instead of hard-coding it in source. How to obtain one: Offline license below.

Web

The browser SDK has no appId / appKey fields. The engine only accepts licenseToken and verifies it locally. Fetch the token from your server before init().

Recommended flow

Create an app in the Dashboard, bind your Web domain, and copy appId / appKey (see Subscription)
Keep the keys on your backend; expose an endpoint (for example POST /api/facebetter/auth)
Your backend signs a request to https://facebetter.pixpark.net/facebetter/v2/auth and returns the raw response body to the page
Pass that string to EngineConfig.licenseToken, then call init()

The official demo (demo/web/react) uses the same pattern: frontend in src/fetchLicenseToken.js, server proxy in api/facebetter/auth.js.

Do not put appKey in a frontend bundle. Web does not support offline .lic files. Online tokens expire in minutes — fetch a new one before creating the engine again.

Frontend

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();

Server proxy (Node example)

Store FB_APP_ID / FB_APP_KEY in environment variables. Drop this into Express / Fastify / a serverless function:

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());
});

In other languages, implement the same steps: build the sign string → HMAC-SHA256 (hex) → POST upstream → hand the body to the frontend. Runnable reference: GitHub Demo api/facebetter/auth.js.

Upstream request fields

Field	Description
`app_id`	Dashboard AppID
`hmac_signature`	HMAC-SHA256 of `v2\|{app_id}\|{timestamp}\|{nonce}\|web`, hex-encoded
`timestamp`	Unix seconds
`nonce`	Random string (recommend ≥16 bytes hex)
`platform`	Always `web`
`user_agent`	Optional; pass the browser UA when available

On success the upstream returns JSON (including a token field). You may forward the response text as-is, or extract only the token string — the SDK accepts either.

Offline license (native)

The Dashboard no longer offers self-serve offline .lic downloads. To get an offline license, contact sales or an administrator:

Email: hello@facebetter.net (subject tip: [Business Partnership] Offline license)
More options: Contact Us

After you receive the file, pass the entire contents as licenseToken / license_token. Validity matches your current subscription; after renewing or changing the plan, request a new file and replace it in the app.

Notes

The offline license is bound to the app identifiers configured in the Dashboard; a mismatch fails validation.
Not expired: features follow your subscription plan.
Expired: the engine can still initialize, but capabilities fall back to the Free plan (watermarked trial, no keypoint callbacks). Renew and request a new license.
Web cannot use offline licenses; it must complete an online v2 auth path.

Engine events

Listen for license and init results via onEngineEvent:

Code	Name	Meaning
0	`LICENSE_VALIDATION_SUCCESS`	Token / online auth succeeded
1	`LICENSE_VALIDATION_FAILED`	Auth failed (see message)
100	`INITIALIZATION_COMPLETE`	Engine ready
101	`INITIALIZATION_FAILED`	Engine init failed

Introduction

Android

iOS

macOS

Windows

Linux

Web

Native (Android / iOS / macOS / Windows)

Web

Recommended flow

Frontend

Server proxy (Node example)

Upstream request fields

Offline license (native)

Notes

Engine events

​Native (Android / iOS / macOS / Windows)

​Web

​Recommended flow

​Frontend

​Server proxy (Node example)

​Upstream request fields

​Offline license (native)

​Notes

​Engine events

Native (Android / iOS / macOS / Windows)

Web

Recommended flow

Frontend

Server proxy (Node example)

Upstream request fields

Offline license (native)

Notes

Engine events