The skin analysis API best practices that matter most are boring ones: get a usable photo, ask for consent before the camera opens, keep secret keys off the client, map your catalog to the concerns the API returns, and plan for the scan that fails. Teams that get those right ship a scan shoppers finish. Teams that skip them ship a camera demo.
I'll use the Face Age SDK for concrete examples, because that's the one we know in detail, but most of this applies to any vendor. If you haven't decided between an app and code yet, start with skin analysis API vs Shopify app.
Start with the job, not the endpoint
Before anyone writes code, agree on what the scan is for on your site. "Show three products after a selfie" is a different build from "let logged-in members track their skin for six months". The first needs capture, analysis and a catalog. The second also needs history storage, identity and a deletion process.
Write the answer down in one sentence. It decides which of the practices below you can skip.
Whatever you build, the output is a cosmetic analysis of visible skin for shopping guidance. Not a medical diagnosis; does not replace a dermatologist.
Keys: know which one goes where
Most skin analysis platforms use two kinds of credential, and mixing them up is the fastest way to leak access.
With Face Age, the Face Age ID (also called the Client ID) identifies your business in the SDK. It's meant for client-side code, and you can restrict it to your own domains. The secret authorization key is different. It authenticates calls to the management API as a Bearer token, it's valid for a year, it's shown once when you generate it, and it should never appear in browser or mobile app code. Put it in a secrets manager or an environment variable on your server.
If the key ever ends up in a public repo, generate a new one. You can regenerate it as often as needed.
Capture: the photo decides everything
No model reads a dark, tilted, filtered selfie well. Capture quality is the single biggest lever you control.
- Offer both camera and upload. Face Age's
showCameraandshowUploadboth default to on. Leave them that way; some shoppers won't open a camera on a laptop. - Keep the image quality warning on. The SDK can warn when lighting, angle or image quality may affect results (
disableImageAlertdefaults to false). Turning it off to "reduce friction" just produces worse results with no explanation. - Give one line of guidance before capture. Face the window, no filter, hair back. Our photo tips for a usable skin scan post has wording you can copy.
- Test on real phones in real rooms. A developer's desk under a ring light is not your customer's bathroom at 11pm.
Consent and disclosure before the camera opens
Ask before you capture, not after. Put a short sentence above the camera button saying what the photo is used for and whether anything is saved. Then link your privacy policy inside the flow. Face Age's SDK has a privacyUrl option for exactly this.
Be precise about retention. If you enable history, say where it lives. If your backend stores images, say so and say how people can delete them. Vague copy makes shoppers hesitate, and the ones who hesitate are the ones who read it.
Limit concerns to what you sell
By default the Face Age SDK analyzes all 13 concerns. If your catalog only covers eye care, the problems option lets you show only darkCircle, eyeBag and eyeWrinkles. Showing a shopper a high acne reading when you sell no acne products leaves them with a worry and nothing to buy.
The same logic applies with any vendor: display the concerns your range can actually address, and be honest in copy about what you don't cover.
Map the catalog with the exact concern keys
This is where most integrations go wrong. The scan works, and the product list is nonsense, because the catalog was pushed without concern targets or with keys that don't match.
With Face Age you can connect products in the dashboard, or push your own catalog from code with setCustomProducts after the analysis comes back. Each product needs an id, URL, image, title and price, and optionally problems (the concerns it targets), routineGroups (morning or night steps like cleanser or serum), a sale price and a size picker.
Practical rules I'd follow:
- Use the exact concern keys from the docs, such as
redness,fineWrinklesorpigment. A typo means a product that never matches. - Don't tag a product with every concern. A cleanser linked to all 13 shows up for everyone and pushes better matches down.
- Fill
routineGroupsif you show routines. Otherwise products appear in recommendations but routine steps stay empty. - Keep prices and URLs in sync with your store, ideally from the same feed your product pages use.
The WooCommerce, WordPress and custom website integration guide covers the plugin route, where products come from your store directly.
Wire events to your cart and analytics
A scan that can't add to cart is a dead end. The SDK fires callbacks you should connect on day one: onAddToCart and onCheckout for your cart, onClickProduct and onDisplayProducts for merchandising data, onClickProblem when a shopper taps a concern, onResetData when they start over, and onCloseModal when they leave.
For analytics, pass a GA4 Measurement ID or GTM container with the gtag option, or a Facebook Pixel ID with fbPixel, and the SDK reports each step as an event. Don't build your own parallel tracking unless you need to. Two sets of numbers that never match will cost you more time than they save.
To send results somewhere else, getAdvisorData returns the analysis and quiz answers in the browser, webhooks can post finished quizzes to your server, and submitSdkIntegration sends the full payload to the SDK integration endpoint. The integrations page lists the CRM and email connections.
History: decide where it lives
History is off unless you turn it on. With history: true, the Face Age SDK stores past scans in the browser's localStorage and cookies. That's private and simple, but it doesn't follow a shopper to a new device.
If you need cross-device history, save scans in your own backend and restore them with setHistoryData. Include the optional quality values (lighting, sharpness, blur, confidence) if you have them. The comparison treats small changes inside a noise band as stable, and quality data helps it flag low-confidence comparisons instead of reporting false changes. Use removeHistoryItem to delete a single entry or clear local history, and make sure your own backend can delete on request too.
Plan for the scan that fails
Some scans will fail. The camera permission gets denied, the face isn't detected, the network drops on a train. Decide in advance what the shopper sees.
- Camera denied: fall back to upload, with one sentence explaining how.
- Image rejected: show the quality warning and a retry button, not a blank screen.
- Network or service error: keep the page usable. Show your best-selling starter routine or a short skin-type quiz so the visit isn't wasted.
- Slow responses: a progress state that says what's happening beats a spinner with no text.
Check the vendor's status page as part of your monitoring. Face Age publishes one, linked from its site.
A skin analysis API best practices checklist before launch
Run through this once, on a phone:
- Secret key is server-side only; Client ID restricted to your domains.
- Consent line and privacy link visible before capture.
- Only concerns you sell are displayed.
- Every mapped product uses valid concern keys and has a routine group.
- Add to cart and checkout work from the results.
- Analytics events appear in GA4 or GTM debug view.
- History behaves as your privacy copy says it does.
- The failure states above all show something useful.
The full option list is in the Face Age developer docs. If you're comparing SDKs from different vendors before committing, our skin analysis SDK comparison looks at Banuba and Visage Technologies as well, and if the scan will carry your brand rather than the vendor's, read what to check in white label skin analysis software.
FAQ
What is the most common mistake when integrating a skin analysis API?
Forgetting the catalog. Most bad results come from products that aren't mapped to concerns, not from the analysis.
Can the Face Age client ID be used in the browser?
Yes. It's meant for client-side use and can be restricted to your domains. Keep the secret authorization key on the server.
Where is scan history stored when using the Face Age SDK?
It's off by default. With history: true it's stored in localStorage and cookies, or you can save scans in your own backend and restore them with setHistoryData.
Is the API result a medical result?
No. It's a cosmetic analysis of visible skin for product guidance. Not a medical diagnosis; does not replace a dermatologist.



