` on your page and initialize `FaceAge` with your license ID\n2. **User scans** — via camera or image upload; the SDK runs AI analysis in the browser\n3. **Results display** — skin age, damage score, and detected problems are shown\n4. **Recommendations** — matched products and routines from your catalog appear automatically\n5. **Your code reacts** — use the API and event callbacks to connect to your cart, CRM, or analytics\n\nYou only need a [Face Age Client ID](https://panel.getfaceage.com) to get started.\n\n---\n\n## Installation\n\n### npm / yarn\n\n```bash\nnpm install face-age --save\n```\n\n```bash\nyarn add face-age --save\n```\n\n### CDN (script tag)\n\n```html\n\n```\n\n### Framework Wrappers\n\nPre-built wrappers are available for component-based frameworks:\n\n| Framework | Package |\n|-----------|---------|\n| React | [react-face-age](https://www.npmjs.com/package/react-face-age) |\n| Vue 2 | [vue-face-age](https://www.npmjs.com/package/vue-face-age) |\n| Vue 3 | [vue3-face-age](https://www.npmjs.com/package/vue3-face-age) |\n\n---\n\n## Quick Start\n\nAdd a container element to your HTML:\n\n```html\n
\n```\n\nThen initialize and render:\n\n```js\nimport FaceAge from 'face-age';\n\nconst faceAge = new FaceAge({\n elementId: 'FaceAge-module', // your container element ID\n faceageId: '
', // get yours at panel.getfaceage.com\n showProducts: true,\n showRoutine: true,\n});\n\nfaceAge.render();\n```\n\n> **Get your Client ID** at [panel.getfaceage.com](https://panel.getfaceage.com) — free account required.\n\n### Full Configuration Example\n\n```js\nimport FaceAge from 'face-age';\n\nconst faceAge = new FaceAge({\n elementId: 'FaceAge-module',\n faceageId: '',\n displayModel: 'section', // 'widget' | 'section' | 'modal'\n language: 'en',\n height: '550px',\n currency: '$',\n\n // Quiz\n quiz: true,\n defaultQuiz: { email: 'user@example.com' },\n\n // History\n history: true,\n\n // Products & routines\n showProducts: true,\n showRoutine: true,\n showAddToCard: true,\n showAddToCardAll: false,\n routinesSupport: ['cleanser', 'serum', 'moisturizer'],\n showEmptyRoutines: false,\n\n // Skin problems to analyze\n problems: ['fineWrinkles', 'eyeWrinkles', 'acne', 'pores'],\n\n // Capture\n showCamera: true,\n showUpload: true,\n\n // Legal & promotions\n privacyUrl: 'https://example.com/privacy',\n discount: { title: 'Use this code at checkout', code: 'FACEAGE20' },\n\n // Display toggles\n disableSkinHealth: false,\n disableSkinAge: false,\n disableImageAlert: false,\n});\n\nfaceAge.render();\n```\n\n---\n\n## Configuration Options\n\nAll options are passed to `new FaceAge(options)`.\n\n### Core\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `elementId` | `String` | — | **Required** for `widget` and `section` display modes. ID of the container element. |\n| `faceageId` | `String` | — | **Required.** Your Face Age license ID from the [panel](https://panel.getfaceage.com). |\n| `displayModel` | `String` | `'section'` | Display mode: `'widget'`, `'section'`, or `'modal'`. |\n| `language` | `String` | `'en'` | UI language code. See [supported languages](#supported-languages) below. |\n| `width` | `String` | `'360px'` | Width of the widget — only applies when `displayModel` is `'widget'`. |\n| `height` | `String` | `'800px'` / `'580px'` | Height of the widget — defaults differ for `section` vs `widget`. |\n| `currency` | `String` | `'$'` | Currency symbol shown next to product prices. |\n\n### Display Modes\n\n| Mode | Behavior |\n|------|----------|\n| `'section'` | Renders inline, expanding to fill one content row on the page |\n| `'widget'` | Renders as a fixed-size standalone panel (respects `width` and `height`) |\n| `'modal'` | Opens as a full-screen overlay; no `elementId` required |\n\n### Quiz\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `quiz` | `Boolean` | `true` | Show the pre-analysis quiz form. |\n| `defaultQuiz` | `Object` | — | Pre-fill quiz fields. Example: `{ email: 'user@example.com' }`. |\n\n### Products & Routines\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `showProducts` | `Boolean` | `false` | Show product recommendations after analysis. |\n| `showRoutine` | `Boolean` | `false` | Show skincare routine groupings. |\n| `showAddToCard` | `Boolean` | `true` | Show add-to-cart buttons on products. |\n| `showAddToCardAll` | `Boolean` | `false` | Show a single \"add all to cart\" button when template supports it. |\n| `routinesSupport` | `Array` | `[]` | Limit routines to specific groups, e.g. `['cleanser', 'serum', 'moisturizer']`. Empty = all groups. |\n| `showEmptyRoutines` | `Boolean` | `false` | Show routine sections even when no product is matched. |\n\n### Skin Analysis\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `problems` | `Array` | all 13 | Skin issues to detect and display. See full list below. |\n| `showCamera` | `Boolean` | `true` | Allow users to capture a photo with their camera. |\n| `showUpload` | `Boolean` | `true` | Allow users to upload an image from their device. |\n| `disableSkinHealth` | `Boolean` | `false` | Hide the skin health/damage summary. Alias: `disable_skin_health`. |\n| `disableSkinAge` | `Boolean` | `false` | Hide the skin age result. Alias: `disable_skin_age`. |\n| `disableImageAlert` | `Boolean` | `false` | Disable the image quality warning. Alias: `disable_image_alert`. |\n\n**Available `problems` values:**\n\n`fineWrinkles` · `eyeWrinkles` · `deepWrinkles` · `darkCircle` · `eyeBag` · `pores` · `pigment` · `redness` · `oiliness` · `dryness` · `sagginess` · `dullness` · `acne`\n\n### History\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `history` | `Boolean` | `false` | Enable previous-analysis history. Stored in `localStorage`/cookies by default, or inject via `faceAge.API.setHistoryData()`. |\n\n### Promotions & Legal\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `privacyUrl` | `String` | `null` | URL to your privacy policy. Invalid URLs are silently ignored. |\n| `discount` | `Object` | `null` | Show a copyable promo code. Example: `{ title: 'Code at checkout', code: 'SAVE20' }`. |\n\n### Supported Languages\n\n40 language codes are supported:\n\n`ar` · `bg` · `bn` · `cs` · `da` · `de` · `el` · `en` · `es` · `et` · `fa` · `fi` · `fr` · `he` · `hi` · `hr` · `hu` · `id` · `it` · `ja` · `ko` · `lt` · `lv` · `ms` · `nl` · `no` · `pl` · `pt` · `ro` · `ru` · `sk` · `sr` · `sv` · `th` · `tl` · `tr` · `uk` · `ur` · `vi` · `zh`\n\nArabic (`ar`), Persian (`fa`), and Urdu (`ur`) automatically switch the UI to RTL layout.\n\n---\n\n## Analytics Integration\n\nFace Age fires events automatically. Connect Google Analytics or Facebook Pixel by passing your IDs as options.\n\n### Google Analytics / GTM\n\n```js\nconst faceAge = new FaceAge({\n elementId: 'FaceAge-module',\n faceageId: '',\n gtag: 'G-XXXXXXXXXX', // G-..., GT-..., or GTM-... format\n gtagInsert: true, // auto-inject GTM script (default: true)\n gtagDataLayer: window.dataLayer, // optional: use a custom dataLayer\n});\n```\n\n### Facebook Pixel\n\n```js\nconst faceAge = new FaceAge({\n elementId: 'FaceAge-module',\n faceageId: '',\n fbPixel: '123456789012345', // your numeric Pixel ID\n fbPixelInsert: true, // auto-inject Pixel script (default: true)\n});\n```\n\n### Tracked Events\n\nThe following interactions are tracked automatically in both GA and Pixel:\n\n| Event | Description |\n|-------|-------------|\n| Quiz start / completion | User begins or finishes the quiz |\n| Quiz question views & choices | Each question view and answer selection |\n| Skin analysis start | Analysis begins |\n| Photo selection / capture | Image uploaded or camera used |\n| Results view | Analysis results displayed |\n| Product view / interaction | Product card viewed or clicked |\n| Add to cart | Add-to-cart button clicked |\n| Checkout | Checkout button clicked |\n| Modal open / close | Modal opened or dismissed |\n| Download report | PDF report download initiated |\n\n---\n\n## API Reference\n\nAfter calling `faceAge.render()`, use `faceAge.API` to read results and interact with the SDK programmatically.\n\n### Read Analysis Results\n\n```js\nfaceAge.API.getAdvisorData((data) => {\n console.log(data.analysis); // skin age, damage %, detected problems\n console.log(data.activeSelections); // quiz answers\n});\n```\n\n### Read Quiz Answers\n\n```js\nfaceAge.API.getActiveSelections((data) => {\n console.log(data); // { email, skinType, ... }\n});\n```\n\n### Read the Submitted Image\n\n```js\nconst image = faceAge.API.getImage();\n```\n\n### Read Available Routine Groups\n\n```js\nconst groups = faceAge.API.getRoutineGroup();\n```\n\n### Set Custom Products\n\nPush your own product catalog into the SDK — it will match products to detected skin problems automatically.\n\n```js\nfaceAge.API.setCustomProducts([\n {\n id: 1,\n url: 'https://yourstore.com/product',\n image: 'https://yourstore.com/product.png',\n title: 'Skin Moisturizer',\n description: 'Vitamin C · 30ml', // optional\n price: 40,\n offerPrice: 18.99, // optional sale price\n problems: ['acne', 'wrinkles'], // optional: target problems\n routineGroups: { morning: ['cleanser', 'serum'] }, // optional\n variables: { // optional: size/variant picker\n size: {\n title: 'Size',\n option: [\n { label: '10 cc', value: '10', price: 40, offerPrice: 18.99 },\n { label: '25 cc', value: '25', price: 52 },\n { label: '35 cc', value: '35' },\n ],\n },\n },\n },\n]);\n```\n\n### History Management\n\n**Restore history from your backend** (requires `history: true`):\n\n```js\nfaceAge.API.setHistoryData({\n analysis: {\n analyze_ref_token: 'analyze_ref_abc123',\n skinAge: 28,\n damagePercentage: 12.4,\n problems: [],\n },\n activeSelections: {\n email: 'user@example.com',\n skinType: 'combination',\n },\n meta: {\n ts: Date.now(),\n image: 'https://example.com/scan.jpg',\n },\n});\n```\n\n**Remove a history entry** by reference token. Pass `null` to clear all local history:\n\n```js\nfaceAge.API.removeHistoryItem('analyze_ref_abc123').then((removed) => {\n console.log('Removed:', removed);\n});\n```\n\n### Generate PDF Report\n\nRequires PDF access on your Face Age plan.\n\n```js\nfaceAge.API.getReportPdf()\n .then((report) => console.log('Report:', report))\n .catch((err) => console.error('Failed:', err));\n```\n\n### Submit SDK Integration\n\nSend the full analysis payload (skin results, products, quiz data, brand metadata) to the SDK-call integration endpoint. If no email is provided, Face Age falls back to `email` or `clientEmail` from quiz answers.\n\n```js\n// Basic\nfaceAge.API.submitSdkIntegration('user@example.com').then((res) => {\n console.log('Submitted:', res);\n});\n\n// With extra metadata\nfaceAge.API.submitSdkIntegration('user@example.com', {\n name: 'Jane Doe',\n skinType: 'dry',\n skinConcern: ['fineWrinkles', 'dryness'],\n});\n```\n\nQuiz data is automatically normalized to `[{ question, answer }]` before submission.\n\n---\n\n## Events\n\nRegister callbacks to react to user interactions in real time.\n\n| Event | Callback signature | Fires when |\n|-------|--------------------|------------|\n| `onClickProblem` | `(key: string)` | User taps a skin problem in the results |\n| `onDisplayProducts` | `(data)` | Product list becomes visible |\n| `onDisplayRoutines` | `(data)` | Routine list becomes visible |\n| `onAddToCart` | `(data)` | User clicks add to cart |\n| `onClickProduct` | `(product)` | User clicks a product card |\n| `onResetData` | `()` | User clicks reset / start over |\n| `onCloseModal` | `()` | User closes the modal |\n| `onCheckout` | `(data)` | User clicks the checkout button |\n\n**Example:**\n\n```js\nfaceAge.onAddToCart((data) => {\n // data contains product details\n myCart.add(data);\n});\n\nfaceAge.onCloseModal(() => {\n // redirect to cart if items were added\n if (myCart.hasItems()) window.location.href = '/cart';\n});\n\nfaceAge.onClickProblem((key) => {\n console.log('Problem selected:', key); // e.g. 'acne'\n});\n```\n\n---\n\n## Contact\n\n| | |\n|--|--|\n| Website | [getfaceage.com](https://getfaceage.com/) |\n| Dashboard | [panel.getfaceage.com](https://panel.getfaceage.com/) |\n| Email | [dev@getfaceage.com](mailto:dev@getfaceage.com) |\n","readmeFilename":"README.md"}![](\"https://static.getfaceage.com/logo.png\"){kind=logo}
![\"npm](\"https://img.shields.io/npm/v/face-age.svg\")
\n ![\"npm](\"https://img.shields.io/npm/dm/face-age.svg\")
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n![](\"https://static.getfaceage.com/v2.0/preview.png\")
\n \n