認証とライセンス - Facebetter Docs

SDK 2.0 は ライセンストークン で認証します。ネイティブプラットフォームでは、オンライン認証に appId + appKey も使えます。Web では、フロントエンドの JavaScript に appKey を埋め込まないでください。

先にサブスクリプションを完了してください。ダッシュボードでアプリ識別子（Bundle ID / パッケージ名 / ドメイン）をバインドし、プランを有効にします。

ネイティブ（Android / iOS / macOS / Windows）

エンジン作成時に、次のいずれか一方を渡します。

モード	設定フィールド	使うタイミング
オンライン	`appId` + `appKey`	デバイスが `/facebetter/v2/auth` に到達できる場合
トークン	`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';

// 本文は素のトークン、または token フィールドを含む上流 JSON テキストのいずれか
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 → body をフロントエンドへ渡します。実行可能な参考実装: 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`	認証失敗（メッセージを参照）
100	`INITIALIZATION_COMPLETE`	エンジン準備完了
101	`INITIALIZATION_FAILED`	エンジン初期化失敗

​ネイティブ（Android / iOS / macOS / Windows）

​Web

​推奨フロー

​フロントエンド

​サーバープロキシ（Node の例）

​上流リクエストのフィールド

​オフラインライセンス

​注意事項

​エンジンイベント

ネイティブ（Android / iOS / macOS / Windows）

Web

推奨フロー

フロントエンド

サーバープロキシ（Node の例）

上流リクエストのフィールド

オフラインライセンス

注意事項

エンジンイベント