Scanning barcodes

Tutorial: Implementing a World-Class Barcode Scan Experience for Your App#

Creating a seamless barcode scanning feature is more than just decoding a barcode; it's about crafting a user experience that feels fast, intuitive, and reliable. This guide covers how to build that experience for the entire Open "Everything" Facts ecosystem, including Food, Beauty, Pet Food, and general Products.

1. Choose the Right Barcode Scanning SDK#

The choice of SDK is the foundation of the experience. Here's a breakdown of the main options:

SDK / Library	Platform(s)	Cost	Pros ✅	Cons ❌
ZXing ("Zebra Crossing")	Java, with ports for many languages	Free (Open Source)	Truly Open. No reliance on Google/Apple services. Battle-tested over many years.	Can be less performant than modern native SDKs, especially in poor lighting.
Google ML Kit	Android & iOS	Free	Modern Standard. Excellent performance, on-device processing, part of a larger ML ecosystem. No data harvesting for ads.	Part of the Google ecosystem, which might be a concern for some projects.
Apple Vision	iOS	Free	Native & Optimized. The best performance on iOS. Seamlessly integrated into the OS (`VNDetectBarcodesRequest`).	iOS only.
Scandit	Android & iOS	Paid	Premium Performance. Often superior in challenging conditions (glare, damaged barcodes, distance). Dedicated support.	Expensive. Their business model involves data collection.

For Cross-Platform Frameworks (React Native, Flutter, etc.): Developers using these frameworks will interact with an abstraction library. The key is to choose a package that is well-maintained and uses the native SDKs (ZXING and/or ML Kit and Apple Vision) under the hood.

Recommendation: For most new apps, while not open, using Google ML Kit on Android and Apple Vision on iOS (or a cross-platform wrapper that uses them) provides the best balance of performance, features, and cost.

2. Design an "Insanely Great" Scan UI/UX#

This is where you turn a functional feature into a delightful one. It's all about the details you build around the scanner.

💡 The Viewfinder & Guidance#

The user should know exactly what to do.

Clear Target Area: Display a semi-transparent overlay on the camera feed with a clear, rectangular cutout in the center. A laser-like line or crosshairs can help guide the user's aim.
Helpful Text: Add a simple instruction like "Center the barcode in the frame."
Automatic Focus: Ensure tap-to-focus is enabled, or even better, continuous auto-focus.

🔦 Handle Poor Lighting#

A significant portion of scan failures happen in poorly lit kitchens or stores.

Manual Torch Button: Always include an easily accessible button to toggle the device's flashlight.
(Advanced) Automatic Torch: You can even use the ambient light sensor to detect low-light conditions and proactively display a message like, "It's dark, want to turn on the light?"

✅ Provide Instant Feedback#

The user needs immediate confirmation that a scan was successful.

Haptic Feedback: A short vibration is a powerful, non-intrusive signal.
Auditory Cue: A quick, pleasant "beep" sound.
Visual Confirmation: Briefly freeze the frame or animate the viewfinder box (e.g., it flashes green). Follow this immediately with a loading indicator so the user knows the app is fetching data.

✍️ The Escape Hatch: Manual Entry#

Sometimes a barcode is damaged, or the camera fails. Always provide a fallback.

Include a button on the scanner screen labeled "Enter barcode manually." This builds user trust and handles edge cases gracefully.

3. Master the API Interaction#

Once you have a barcode string, you must normalize it before querying the correct database.

✔️ Step 3.1: Pre-process the Barcode (Normalization)#

Barcode scanners can return codes in various formats (EAN-8, EAN-13, UPC-A, UPC-E). To ensure a match in the database, the Open Food Facts server will normalize the barcode on your behalf. You should not try to normalize barcodes**

Padding with Zeros: If the scanned barcode has fewer than 13 digits, the Open Food Facts server will pad it with leading zeros until it reaches 13 digits. For example, 12345678 (EAN-8) becomes 0000012345678.
Calculate the Check Digit: to ensure your barcode is valid, you can calculate the check digits (instructions here, you will find the algorithm in many places, including Open Food Facts SDKs, barcode scanning SDKs…). Please note that -sometimes- some producers make up barcodes without knowing about this (to avoid buying barcode ranges), and you may stump on edge cases.

🌍 Step 3.2: Choose the Right Database Endpoint#

The Open "Everything" Facts platform uses the same API structure across different domains. Simply change the domain in the URL to query the database you need. You can also make a universal call that will call all 4 databases for an answer, and you can display results however you like, mention you don't support specific data types, and help users add missing products by taking photos.

Project	Domain for API Calls
Open Food Facts	`https://world.openfoodfacts.org`
Open Beauty Facts	`https://world.openbeautyfacts.org`
Open Pet Food Facts	`https://world.openpetfoodfacts.org`
Open Products Facts	`https://world.openproductsfacts.org`

📡 Step 3.3: Make the API Call#

Make a simple GET request to the appropriate v2 API endpoint with your normalized barcode: GET https://{domain}/api/v2/product/{normalized_barcode}.json

Crucial Best Practice:

Set a Proper User-Agent: This is essential for API etiquette. Use the format: User-Agent: MyAppName - Android - Version 2.1 - https://example.com - scan

📥 Step 3.4: Handle the API Response#

Product Found ("status": 1): The product exists. Parse the "product" object for the data you need (e.g., product_name, image_front_url, nutriments, nutriscore_grade, etc.).
Product Not Found ("status": 0): The barcode is valid, but the product isn't in the database. * Do not show an error! Display a friendly screen: "Product Not Found." * 🚀 Empower the User: Add a button: "Be the first to add this product!" This can link to the appropriate Open Facts product creation form, turning a dead-end into a powerful contribution.
Network Errors: Wrap your API call in a try/catch block to handle connection issues and show a clear error message to the user.
Server Errors: Prepare for the case our or your servers are down, and handle those cases gracefully as well.

4. The Complete Flow from Start to Finish#

User taps the "Scan" button in your app.
The camera view opens instantly with the viewfinder UI and help text.
The native SDK detects a barcode and returns a string.
The app gives immediate feedback (vibration + sound).
The app normalizes the barcode string (pads with zeros, calculates check digit if necessary).
A loading spinner is displayed while the app makes the API call to the correct domain (Food, Beauty, etc.) with the normalized barcode and a proper User-Agent.
The API response is received. * If found: The app navigates to a beautifully formatted product page. * If not found: The app shows a "Product not found" screen with a call-to-action to add it. * If network error: The app shows a "Connection error" message.

Bonus: I am doing a "AI" app, how can I handle barcodes as well ?#

Add a barcode button beyond your AI viewfinder, that will start the barcode decoder. Benefits of using barcodes: reducing the cost of a query to 0 and a much faster answer.
Make sure you allow users to send us photos so that the database stays competitive (more comprehensive) compared to purely AI solutions.