face-age 2.3.13 → 2.4.2

package/README.md

@@ -1,482 +1,469 @@
-<br />
+# Face Age — AI Skin Analysis SDK
+
+**AI-powered JavaScript SDK for skin analysis, face scanning, and beauty tech applications.**
+
+Detect skin age, wrinkles, acne, dark circles, pores, pigmentation, oiliness, and more — then deliver personalized skincare product recommendations and routines, all embedded directly in your website or app.
 
 <p align="center"><img src="https://static.getfaceage.com/logo.png" width="232px"></p>
 
 <p align="center">
-  <a href="https://demo.getfaceage.com" target="_blank" rel="noopener noreferrer">Demo</a> /
-  <a href="https://panel.getfaceage.com" target="_blank" rel="noopener noreferrer">Get Face Age ID</a>
+  <a href="https://www.npmjs.com/package/face-age"><img src="https://img.shields.io/npm/v/face-age.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/face-age"><img src="https://img.shields.io/npm/dm/face-age.svg" alt="npm downloads" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" /></a>
 </p>
 
-<br />
-
 <p align="center">
-  A modern JavaScript library for skin beauty and healthcare, enabling the creation of interactive data visualizations with a simple-to-use API. The platform provides customized skincare solutions through precise skin analysis and is suitable for both commercial and non-commercial projects.
+  <a href="https://demo.getfaceage.com" target="_blank" rel="noopener noreferrer">Live Demo</a> ·
+  <a href="https://panel.getfaceage.com" target="_blank" rel="noopener noreferrer">Get Your API Key</a> ·
+  <a href="https://getfaceage.com/" target="_blank" rel="noopener noreferrer">Website</a>
 </p>
 
-<br />
-
 <p align="center">
   <a href="https://getfaceage.com/">
     <img src="https://static.getfaceage.com/v2.0/preview.png" />
   </a>
 </p>
 
-<br />
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [How It Works](#how-it-works)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration Options](#configuration-options)
+- [Analytics Integration](#analytics-integration)
+- [API Reference](#api-reference)
+- [Events](#events)
+- [Contact](#contact)
+
+---
+
+## Features
+
+- **AI Skin Analysis** — camera capture or image upload with real-time face detection
+- **13 Skin Metrics** — wrinkles, acne, dark circles, pores, pigment, redness, oiliness, dryness, and more
+- **3 Display Modes** — embed as a widget, inline section, or full-screen modal
+- **Product Recommendations** — show matched products with add-to-cart and checkout callbacks
+- **Skincare Routines** — group recommendations by morning/evening routine steps
+- **Quiz Flow** — collect user preferences with pre-fillable form fields
+- **Analysis History** — persist previous scans via browser storage or your own backend
+- **Discount Banners** — display copyable promo codes in the recommendation flow
+- **PDF Reports** — generate downloadable skin analysis reports (plan-dependent)
+- **Analytics** — built-in Google Analytics (GTM) and Facebook Pixel event tracking
+- **40 Languages** — full RTL support for Arabic, Persian, and Urdu
+
+---
+
+## How It Works
+
+1. **Embed** a `<div>` on your page and initialize `FaceAge` with your license ID
+2. **User scans** — via camera or image upload; the SDK runs AI analysis in the browser
+3. **Results display** — skin age, damage score, and detected problems are shown
+4. **Recommendations** — matched products and routines from your catalog appear automatically
+5. **Your code reacts** — use the API and event callbacks to connect to your cart, CRM, or analytics
+
+You only need a [Face Age Client ID](https://panel.getfaceage.com) to get started.
+
+---
 
-## Getting Started
+## Installation
 
-### Installation
+### npm / yarn
 
 ```bash
 npm install face-age --save
 ```
 
-<p>or</p>
-
 ```bash
 yarn add face-age --save
 ```
 
-### Direct `<script>` Inclusion
-
-<p>You can also directly include the script in your HTML:</p>
+### CDN (script tag)
 
-```bash
+```html
 <script src="https://cdn.jsdelivr.net/npm/face-age"></script>
 ```
 
+### Framework Wrappers
 
-## Wrappers for React/Vue
-
-Integrate easily with 3rd party frameworks
+Pre-built wrappers are available for component-based frameworks:
 
-- [react-face-age](https://www.npmjs.com/package/react-face-age)
-- [vue-face-age](https://www.npmjs.com/package/vue-face-age)
-- [vue3-face-age](https://www.npmjs.com/package/vue3-face-age)
+| Framework | Package |
+|-----------|---------|
+| React | [react-face-age](https://www.npmjs.com/package/react-face-age) |
+| Vue 2 | [vue-face-age](https://www.npmjs.com/package/vue-face-age) |
+| Vue 3 | [vue3-face-age](https://www.npmjs.com/package/vue3-face-age) |
 
+---
 
+## Quick Start
 
-## Usage
+Add a container element to your HTML:
 
-```js
-import FaceAge from 'face-age';
+```html
+<div id="FaceAge-module"></div>
 ```
 
-To create a basic analysis with minimal configuration:
+Then initialize and render:
 
 ```js
-const options = {
-  elementId: 'FaceAge-module', // Required if using displayModel 'widget' or 'section'
-  faceageId: '<Face Age Client ID>', // Your Face Age license ID
+import FaceAge from 'face-age';
+
+const faceAge = new FaceAge({
+  elementId: 'FaceAge-module',   // your container element ID
+  faceageId: '<Your Client ID>', // get yours at panel.getfaceage.com
   showProducts: true,
   showRoutine: true,
-};
+});
 
-const faceAge = new FaceAge(options);
 faceAge.render();
 ```
 
-<a href="https://panel.getfaceage.com" target="_blank" rel="noopener noreferrer">Get Face Age ID</a>
+> **Get your Client ID** at [panel.getfaceage.com](https://panel.getfaceage.com) — free account required.
 
-For more advanced settings:
+### Full Configuration Example
 
 ```js
-const options = {
+import FaceAge from 'face-age';
+
+const faceAge = new FaceAge({
   elementId: 'FaceAge-module',
-  faceageId: '<Face Age Client ID>', // Your Face Age license ID
-  displayModel: 'section',
+  faceageId: '<Your Client ID>',
+  displayModel: 'section',         // 'widget' | 'section' | 'modal'
   language: 'en',
   height: '550px',
   currency: '$',
-  quiz: true,
-  defaultQuiz: { email: 'hi@getfaceage.com' },
-  showProducts: true,
-  showRoutine: true,
-  showAddToCart: true,
-  problems: ['fineWrinkles', 'eyeWrinkles'],
-  showCamera: true,
-  showUpload: true,
-};
-
-const faceAge = new FaceAge(options);
-faceAge.render();
-```
-
-## Options
-
-You can set analysis options using `new FaceAge()`. To modify global default options, use the `options` object.
-
-### elementId
-
-- Type: `String`
-
-Required if using the displayModel 'widget' or 'section'.
-
-### faceageId
-
-- Type: `String`
-
-Your Face Age license ID, obtainable from the <a href="https://panel.getfaceage.com" target="_blank">panel</a> after creating an account.
 
-### displayModel
-
-- Type: `String`
-- Default: `'section'`
-- Options:
-  - `'widget'`: Only displays the analysis environment.
-  - `'section'`: Occupies one line on the page.
-  - `'modal'`: Shows the analysis in a full-screen modal.
-
-You can choose between different display modes.
-
-### language
-
-- Type: `String`
-- Default: `'en'`
+  // Quiz
+  quiz: true,
+  defaultQuiz: { email: 'user@example.com' },
 
-Specify the desired language.
+  // History
+  history: true,
 
-### width
+  // Products & routines
+  showProducts: true,
+  showRoutine: true,
+  showAddToCard: true,
+  showAddToCardAll: false,
+  routinesSupport: ['cleanser', 'serum', 'moisturizer'],
+  showEmptyRoutines: false,
 
-- Type: `Number` (optional)
+  // Skin problems to analyze
+  problems: ['fineWrinkles', 'eyeWrinkles', 'acne', 'pores'],
 
-Applicable when displayModel is set to `'widget'`.
+  // Capture
+  showCamera: true,
+  showUpload: true,
 
-### height
+  // Legal & promotions
+  privacyUrl: 'https://example.com/privacy',
+  discount: { title: 'Use this code at checkout', code: 'FACEAGE20' },
 
-- Type: `Number` (optional)
+  // Display toggles
+  disableSkinHealth: false,
+  disableSkinAge: false,
+  disableImageAlert: false,
+});
 
-Applicable when displayModel is set to `'widget'`.
+faceAge.render();
+```
 
-### currency
+---
 
-- Type: `String`
-- Default: `'$'`
+## Configuration Options
 
-Set the currency unit.
+All options are passed to `new FaceAge(options)`.
 
-### quiz
+### Core
 
-- Type: `Boolean`
-- Default: `true`
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `elementId` | `String` | — | **Required** for `widget` and `section` display modes. ID of the container element. |
+| `faceageId` | `String` | — | **Required.** Your Face Age license ID from the [panel](https://panel.getfaceage.com). |
+| `displayModel` | `String` | `'section'` | Display mode: `'widget'`, `'section'`, or `'modal'`. |
+| `language` | `String` | `'en'` | UI language code. See [supported languages](#supported-languages) below. |
+| `width` | `String` | `'360px'` | Width of the widget — only applies when `displayModel` is `'widget'`. |
+| `height` | `String` | `'800px'` / `'580px'` | Height of the widget — defaults differ for `section` vs `widget`. |
+| `currency` | `String` | `'$'` | Currency symbol shown next to product prices. |
 
-Toggle quiz display for users.
+### Display Modes
 
-### defaultQuiz
+| Mode | Behavior |
+|------|----------|
+| `'section'` | Renders inline, expanding to fill one content row on the page |
+| `'widget'` | Renders as a fixed-size standalone panel (respects `width` and `height`) |
+| `'modal'` | Opens as a full-screen overlay; no `elementId` required |
 
-- Type: `Object`
-- Example: `{ email: 'hi@getfaceage.com' }`
+### Quiz
 
-Prepopulate quiz fields with user information.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `quiz` | `Boolean` | `true` | Show the pre-analysis quiz form. |
+| `defaultQuiz` | `Object` | — | Pre-fill quiz fields. Example: `{ email: 'user@example.com' }`. |
 
-### showProducts
+### Products & Routines
 
-- Type: `Boolean`
-- Default: `false`
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `showProducts` | `Boolean` | `false` | Show product recommendations after analysis. |
+| `showRoutine` | `Boolean` | `false` | Show skincare routine groupings. |
+| `showAddToCard` | `Boolean` | `true` | Show add-to-cart buttons on products. |
+| `showAddToCardAll` | `Boolean` | `false` | Show a single "add all to cart" button when template supports it. |
+| `routinesSupport` | `Array` | `[]` | Limit routines to specific groups, e.g. `['cleanser', 'serum', 'moisturizer']`. Empty = all groups. |
+| `showEmptyRoutines` | `Boolean` | `false` | Show routine sections even when no product is matched. |
 
-### showRoutine
+### Skin Analysis
 
-- Type: `Boolean`
-- Default: `false`
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `problems` | `Array` | all 13 | Skin issues to detect and display. See full list below. |
+| `showCamera` | `Boolean` | `true` | Allow users to capture a photo with their camera. |
+| `showUpload` | `Boolean` | `true` | Allow users to upload an image from their device. |
+| `disableSkinHealth` | `Boolean` | `false` | Hide the skin health/damage summary. Alias: `disable_skin_health`. |
+| `disableSkinAge` | `Boolean` | `false` | Hide the skin age result. Alias: `disable_skin_age`. |
+| `disableImageAlert` | `Boolean` | `false` | Disable the image quality warning. Alias: `disable_image_alert`. |
 
-### showAddToCart
+**Available `problems` values:**
 
-- Type: `Boolean`
-- Default: `true`
+`fineWrinkles` · `eyeWrinkles` · `deepWrinkles` · `darkCircle` · `eyeBag` · `pores` · `pigment` · `redness` · `oiliness` · `dryness` · `sagginess` · `dullness` · `acne`
 
-### showCamera
+### History
 
-- Type: `Boolean`
-- Default: `true`
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `history` | `Boolean` | `false` | Enable previous-analysis history. Stored in `localStorage`/cookies by default, or inject via `faceAge.API.setHistoryData()`. |
 
-Allow users to capture images using the camera.
+### Promotions & Legal
 
-### showUpload
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `privacyUrl` | `String` | `null` | URL to your privacy policy. Invalid URLs are silently ignored. |
+| `discount` | `Object` | `null` | Show a copyable promo code. Example: `{ title: 'Code at checkout', code: 'SAVE20' }`. |
 
-- Type: `Boolean`
-- Default: `true`
+### Supported Languages
 
-Enable or disable image uploads.
+40 language codes are supported:
 
-### problems
+`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`
 
-- Type: `Array`
-- Default: `['fineWrinkles', 'eyeWrinkles', 'deepWrinkles', 'darkCircle', 'eyeBag', 'pores', 'pigment', 'redness', 'oiliness', 'dryness', 'sagginess', 'dullness', 'acne']`
-- Options:
-  - `fineWrinkles`
-  - `eyeWrinkles`
-  - `deepWrinkles`
-  - `darkCircle`
-  - `eyeBag`
-  - `pores`
-  - `pigment`
-  - `redness`
-  - `oiliness`
-  - `dryness`
-  - `sagginess`
-  - `dullness`
-  - `acne`
+Arabic (`ar`), Persian (`fa`), and Urdu (`ur`) automatically switch the UI to RTL layout.
 
-Limit the types of skin issues displayed during analysis.
+---
 
 ## Analytics Integration
 
-Face Age supports integration with Google Analytics (GTM) and Facebook Pixel to track user interactions and conversions.
-
-### Google Analytics (GTM)
+Face Age fires events automatically. Connect Google Analytics or Facebook Pixel by passing your IDs as options.
 
-To integrate Google Analytics, add the following options:
+### Google Analytics / GTM
 
 ```js
-const options = {
+const faceAge = new FaceAge({
   elementId: 'FaceAge-module',
-  faceageId: '<Face Age Client ID>',
-  gtag: 'G-XXXXXXXXXX', // Your Google Analytics Measurement ID
-  gtagInsert: true, // Optional: Automatically inject GTM script (default: true)
-  gtagDataLayer: window.dataLayer, // Optional: Custom dataLayer (default: window.dataLayer)
-};
-
-const faceAge = new FaceAge(options);
-faceAge.render();
+  faceageId: '<Your Client ID>',
+  gtag: 'G-XXXXXXXXXX',        // G-..., GT-..., or GTM-... format
+  gtagInsert: true,             // auto-inject GTM script (default: true)
+  gtagDataLayer: window.dataLayer, // optional: use a custom dataLayer
+});
 ```
 
-#### GTM Options
-
-- **gtag** (`String`): Your Google Analytics Measurement ID (format: `G-XXXXXXXXXX`, `GT-XXXXXXXXXX`, or `GTM-XXXXXXXXXX`)
-- **gtagInsert** (`Boolean`, optional): Automatically inject the GTM script into the page. Default: `true`
-- **gtagDataLayer** (`Object`, optional): Custom dataLayer object. Default: `window.dataLayer`
-
 ### Facebook Pixel
 
-To integrate Facebook Pixel, add the following options:
-
 ```js
-const options = {
+const faceAge = new FaceAge({
   elementId: 'FaceAge-module',
-  faceageId: '<Face Age Client ID>',
-  fbPixel: '123456789012345', // Your Facebook Pixel ID
-  fbPixelInsert: true, // Optional: Automatically inject Facebook Pixel script (default: true)
-};
-
-const faceAge = new FaceAge(options);
-faceAge.render();
-```
-
-#### Facebook Pixel Options
-
-- **fbPixel** (`String`): Your Facebook Pixel ID (numeric string)
-- **fbPixelInsert** (`Boolean`, optional): Automatically inject the Facebook Pixel script into the page. Default: `true`
-
-### Using Both Analytics Services
-
-You can use both Google Analytics and Facebook Pixel simultaneously:
-
-```js
-const options = {
-  elementId: 'FaceAge-module',
-  faceageId: '<Face Age Client ID>',
-  gtag: 'G-XXXXXXXXXX',
-  gtagDataLayer: window.dataLayer,
-  fbPixel: '123456789012345',
-};
-
-const faceAge = new FaceAge(options);
-faceAge.render();
+  faceageId: '<Your Client ID>',
+  fbPixel: '123456789012345',  // your numeric Pixel ID
+  fbPixelInsert: true,          // auto-inject Pixel script (default: true)
+});
 ```
 
 ### Tracked Events
 
-Face Age automatically tracks the following user interactions:
+The following interactions are tracked automatically in both GA and Pixel:
 
-- Quiz start and completion
-- Quiz question views and choices
-- Skin analysis start
-- Photo selection and capture
-- Results view
-- Product views and interactions
-- Add to cart actions
-- Checkout button clicks
-- Modal open/close events
-- Download report actions
+| Event | Description |
+|-------|-------------|
+| Quiz start / completion | User begins or finishes the quiz |
+| Quiz question views & choices | Each question view and answer selection |
+| Skin analysis start | Analysis begins |
+| Photo selection / capture | Image uploaded or camera used |
+| Results view | Analysis results displayed |
+| Product view / interaction | Product card viewed or clicked |
+| Add to cart | Add-to-cart button clicked |
+| Checkout | Checkout button clicked |
+| Modal open / close | Modal opened or dismissed |
+| Download report | PDF report download initiated |
 
-## API
+---
 
-Once the image is analyzed, you can retrieve the results using the following commands:
+## API Reference
 
-### Get Advisor Data
+After calling `faceAge.render()`, use `faceAge.API` to read results and interact with the SDK programmatically.
 
-Retrieve advisor data after the analysis:
+### Read Analysis Results
 
 ```js
 faceAge.API.getAdvisorData((data) => {
-  console.log('Advisor data analysis:', data);
+  console.log(data.analysis);        // skin age, damage %, detected problems
+  console.log(data.activeSelections); // quiz answers
 });
 ```
 
-### Get Active Selections
-
-Retrieve active selections after completing the form:
+### Read Quiz Answers
 
 ```js
 faceAge.API.getActiveSelections((data) => {
-  console.log('Quiz active selection data:', data);
+  console.log(data); // { email, skinType, ... }
 });
 ```
 
-### Get Routine Groups
+### Read the Submitted Image
 
-Retrieve routine groups that the software supports:
+```js
+const image = faceAge.API.getImage();
+```
+
+### Read Available Routine Groups
 
 ```js
-console.log('Routine Groups:', faceAge.API.getRoutineGroup());
+const groups = faceAge.API.getRoutineGroup();
 ```
 
-### Add Custom Products
+### Set Custom Products
 
-Manually add and display custom products:
+Push your own product catalog into the SDK — it will match products to detected skin problems automatically.
 
 ```js
 faceAge.API.setCustomProducts([
   {
     id: 1,
-    url: 'https://getfaceage.com',
-    image: 'https://demo.getfaceage.com/static/products/pr5.png',
-    title: 'Skin moisturizers',
-    description: 'Vitamin C. Rooster 30ml', //optional
-    routineGroups: {'morning': ['cleanser', 'serum']}, //optional
-    problems: ['acne', 'wrinkles'], //optional
+    url: 'https://yourstore.com/product',
+    image: 'https://yourstore.com/product.png',
+    title: 'Skin Moisturizer',
+    description: 'Vitamin C · 30ml',          // optional
     price: 40,
-    offerPrice: 18.99, //optional
-    variables: { //optional
-      'size': {
+    offerPrice: 18.99,                         // optional sale price
+    problems: ['acne', 'wrinkles'],            // optional: target problems
+    routineGroups: { morning: ['cleanser', 'serum'] }, // optional
+    variables: {                               // optional: size/variant picker
+      size: {
         title: 'Size',
         option: [
-          {label: '10 cc', value: '10', price: 40 /*optional*/, offerPrice: 18.99 /*optional*/},
-          {label: '25 cc', value: '25', price: 52 /*optional*/, offerPrice: 19.99 /*optional*/},
-          {label: '35 cc', value: '35'}
-        ]
-      }
+          { label: '10 cc', value: '10', price: 40, offerPrice: 18.99 },
+          { label: '25 cc', value: '25', price: 52 },
+          { label: '35 cc', value: '35' },
+        ],
+      },
     },
-  }
+  },
 ]);
 ```
 
-## Complete Example of API Usage
+### History Management
 
-```js
-faceAge.API.getAdvisorData((data) => {
-  // Use the data from the analysis
-  console.log('Advisor data analysis:', data);
-
-  console.log('User Image:', faceAge.API.getImage());
-
-  faceAge.API.getActiveSelections((data) => {
-    console.log('Quiz active selection data:', data);
-  });
-
-  faceAge.API.setCustomProducts([
-    {
-      id: 1,
-      url: 'https://getfaceage.com',
-      image: 'https://demo.getfaceage.com/static/products/pr5.png',
-      title: 'Skin moisturizers',
-      description: 'Vitamin C. Rooster 30ml', //optional
-      routineGroups: {'morning': ['cleanser', 'serum']}, //optional
-      problems: ['acne', 'wrinkles'], //optional
-      price: 40,
-      offerPrice: 18.99, //optional
-    }
-  ]);
+**Restore history from your backend** (requires `history: true`):
 
+```js
+faceAge.API.setHistoryData({
+  analysis: {
+    analyze_ref_token: 'analyze_ref_abc123',
+    skinAge: 28,
+    damagePercentage: 12.4,
+    problems: [],
+  },
+  activeSelections: {
+    email: 'user@example.com',
+    skinType: 'combination',
+  },
+  meta: {
+    ts: Date.now(),
+    image: 'https://example.com/scan.jpg',
+  },
 });
 ```
 
-## Events
-
-Add custom event listeners for different interactions:
-
-### onClickProblem
+**Remove a history entry** by reference token. Pass `null` to clear all local history:
 
 ```js
-faceAge.onClickProblem((key) => {
-  // Get user status and information when they click on a problem
-  console.log('User clicked on problem:', key);
+faceAge.API.removeHistoryItem('analyze_ref_abc123').then((removed) => {
+  console.log('Removed:', removed);
 });
 ```
 
-### onDisplayProducts
+### Generate PDF Report
+
+Requires PDF access on your Face Age plan.
 
 ```js
-faceAge.onDisplayProducts((data) => {
-  // Display product information when the product list is shown
-  console.log('Display Products:', data);
-});
+faceAge.API.getReportPdf()
+  .then((report) => console.log('Report:', report))
+  .catch((err) => console.error('Failed:', err));
 ```
 
-### onDisplayRoutines
+### Submit SDK Integration
+
+Send 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.
 
 ```js
-faceAge.onDisplayRoutines((data) => {
-  // Display routine information when the routine list is shown
-  console.log('Display Routines:', data);
+// Basic
+faceAge.API.submitSdkIntegration('user@example.com').then((res) => {
+  console.log('Submitted:', res);
 });
-```
 
-### onAddToCart
-
-```js
-faceAge.onAddToCart((data) => {
-  // Retrieve product information when a user clicks add to cart
-  console.log('User clicked add to cart:', data);
+// With extra metadata
+faceAge.API.submitSdkIntegration('user@example.com', {
+  name: 'Jane Doe',
+  skinType: 'dry',
+  skinConcern: ['fineWrinkles', 'dryness'],
 });
 ```
 
-### onClickProduct
+Quiz data is automatically normalized to `[{ question, answer }]` before submission.
 
-```js
-faceAge.onClickProduct((product) => {
-  // Retrieve product details when a user clicks on a product
-  console.log('User clicked on product info:', product);
-});
-```
+---
 
-### onResetData
+## Events
 
-```js
-faceAge.onResetData(() => {
-  // Trigger when the user refreshes the information
-  console.log('User clicked reset data');
-});
-```
+Register callbacks to react to user interactions in real time.
+
+| Event | Callback signature | Fires when |
+|-------|--------------------|------------|
+| `onClickProblem` | `(key: string)` | User taps a skin problem in the results |
+| `onDisplayProducts` | `(data)` | Product list becomes visible |
+| `onDisplayRoutines` | `(data)` | Routine list becomes visible |
+| `onAddToCart` | `(data)` | User clicks add to cart |
+| `onClickProduct` | `(product)` | User clicks a product card |
+| `onResetData` | `()` | User clicks reset / start over |
+| `onCloseModal` | `()` | User closes the modal |
+| `onCheckout` | `(data)` | User clicks the checkout button |
 
-### onCloseModal
+**Example:**
 
 ```js
-faceAge.onCloseModal(() => {
-  // Trigger when the user closes the modal. You could forward them to checkout if products were added to cart.
-  console.log('User clicked close');
+faceAge.onAddToCart((data) => {
+  // data contains product details
+  myCart.add(data);
 });
-```
 
-### onCheckout
+faceAge.onCloseModal(() => {
+  // redirect to cart if items were added
+  if (myCart.hasItems()) window.location.href = '/cart';
+});
 
-```js
-faceAge.onCheckout((data) => {
-  // Trigger when the user clicks the checkout button
-  console.log('User clicked checkout');
+faceAge.onClickProblem((key) => {
+  console.log('Problem selected:', key); // e.g. 'acne'
 });
 ```
 
-## New Features
-
-- **Face Mask & Skin Routine:** Display skin routine products and allow users to manage their routines.
-- **Summary of Skin Information:** Provide users with a summary of their skin analysis.
-- **Multiple Languages:** Support for multiple languages and custom labels.
-- **Customizable Themes:** Customizable themes and layouts to match user preferences.
+---
 
 ## Contact
 
-- Website: [getfaceage.com](https://getfaceage.com/)
-- Panel: [panel.getfaceage.com](https://panel.getfaceage.com/)
-- Email: [dev@getfaceage.com](mailto:dev@getfaceage.com)
-
+| | |
+|--|--|
+| Website | [getfaceage.com](https://getfaceage.com/) |
+| Dashboard | [panel.getfaceage.com](https://panel.getfaceage.com/) |
+| Email | [dev@getfaceage.com](mailto:dev@getfaceage.com) |