> ## Documentation Index
> Fetch the complete documentation index at: https://docs.satyakod.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Private Code scanning guide

> How to print, check and scan Satyakod Private Codes, for packaging, print line and brand protection teams.

A Satyakod Private Code is a 2D code in your brand's own design. Only Satyakod can read it, so
counterfeiters cannot copy its meaning or make new ones. Each code carries a unique, signed
serial: when someone scans it, Satyakod checks that the serial is yours, was issued, is not
revoked and is not being copied.

Generic barcode and camera apps cannot read Private Codes. This is intended. Every label
prints the address of your scanner page, and that page reads the code.

## How a scan works

```mermaid theme={null}
sequenceDiagram
  participant P as Person with a phone
  participant S as Scanner page (your verify address /scan)
  participant V as Satyakod
  P->>S: Opens the address printed under the code
  S->>P: Asks to use the camera
  P->>S: Points the camera at the code
  S->>V: Sends camera images
  V-->>S: Verdict: Genuine, Suspicious or Counterfeit
  S-->>P: Shows the verdict and the product
```

Nothing is installed: the scanner page works in the phone's browser. The page sends images
while the camera looks at the code and stops as soon as a code is read, usually within a
second.

### What the verdicts mean

| Verdict | Meaning | What to do |
| - | - | - |
| ✔ **Genuine** | Your code, issued in a batch, not revoked, no sign of copying | Nothing |
| ⚠ **Suspicious** | Your code, but scanned outside the batch's authorised region | Check the sales channel; it appears in Scans and may raise an alert |
| ✖ **Counterfeit** | Not a valid code of yours, revoked, or the same code scanned far apart within a few hours (a copied label) | Don't accept the product; the scan can raise an [alert](https://docs.satyakod.com/guides/alerts.md) for your brand protection team |

## Designing and approving a code

In **Code Studio**, start from a template and set colours, size and print method. Before a design
can go to production:

* the reliability score must be **90 or more**, and
* the **scan test** must read **12 of 12** test scans on each device class: low-end Android,
  iPhone and rugged scanners. Satyakod prints your design at its minimum size, photographs it
  as each device would and reads it.

Both a Brand admin and a Packaging engineer approve each version. Changing a setting creates
a new version, which needs a new scan test.

## Printing best practices

### Size

Use at least the sizes below. They are measured with the scan test on budget Android phones,
which are the hardest devices to read with.

| Template | Thermal transfer, offset, digital, laser | Continuous inkjet (CIJ) |
| - | - | - |
| Rings, Dot grid, Hex | 12 mm | 16 mm |
| Square frame, Orbit dots, Shield | 14 mm | 16 mm |
| Wordmark wrap | 16 mm | 16 mm |
| Radial bars | 16 mm | 18 mm |

Bigger is always easier to scan. If the space allows, 15–20 mm gives a comfortable margin.
On a standard 50 × 30 mm Zebra label, the code is printed at 25 mm.

### Colour and contrast

* **Dark code on a light background, always.** A light code on a dark label cannot be read.
* Aim for a contrast ratio of **7 : 1 or more**. Near-black on white is best. Avoid mid-tone
  brand colours such as light grey, yellow or pastel blue for the code itself.
* Don't print the code over a pattern, photo or gradient.

### Quiet zone

Keep at least **2 mm of plain background** all round the code. No text, borders, folds or
seams inside it.

### Surface and finish

* Matt finishes read best. Gloss and foil reflect light; if you must use them, test under
  shop lighting.
* Keep the code on a flat face. On caps and tubes, keep it small compared with the curve, or
  use a flat label.
* For laser etching on metal or plastic, check the etched marks are clearly darker than the
  surface around them.

### Logo

Studio's logo coverage should stay **at or under 20%** of the code. Larger logos reduce how
much damage the code survives.

## On the print line

```mermaid theme={null}
flowchart TD
  A[Batch signed: files ready] --> B[Download the proof sheet]
  B --> C[Line supervisor checks size, position and print quality]
  C --> D[Send to printer or download the printer job]
  D --> E[Scan the first labels at /scan with a phone]
  E --> F{All Genuine?}
  F -- yes --> G[Run the batch]
  F -- no --> H[Stop: check ribbon, darkness, speed and alignment]
  H --> D
  G --> I[Mark printed and record voided labels]
```

* **Scan the first labels of every run** with an ordinary phone, not only a rugged scanner. A
  print that reads on a budget phone reads everywhere.
* **Thermal printers:** a worn ribbon, low darkness or high speed thins the dots. If first
  labels fail, raise darkness one step or slow down, and scan again.
* **Inkjet:** clean the nozzles before the run; ink spread makes small codes unreadable.
* **Record voided labels** when you mark a batch printed, so scans of those serials can be
  flagged.
* **Never reprint a serial** on a second label. Two labels with one serial look like a copy
  and are reported as counterfeit when scanned far apart.

## Scanning tips

Share these with retailers, mechanics, distributors and consumers.

1. Open the address printed under the code, for example `verify.yourbrand.com/scan`, in the
   phone's browser, and allow the camera.
2. Hold the phone **10–20 cm** from the code, so the code fills about a third of the frame,
   with the **whole code in view**, including the four round marks around it. Move closer for
   small codes.
3. Hold the phone roughly **square-on**. A slight angle is fine.
4. Make sure there is **light on the code** and **no glare**. Tilt the pack a little to move a
   reflection off it.
5. Hold still for a moment. The verdict appears as soon as the code is read.

### Troubleshooting

| Problem | Try |
| - | - |
| The page doesn't ask for the camera, or shows it is blocked | Allow the camera for the site in the browser settings, then reload |
| Nothing happens while pointing at the code | Move closer or further away, add light, wipe the lens |
| A generic QR or barcode app says nothing | Expected: use the address printed on the label |
| The code is scratched, wet or partly covered | Private Codes correct a lot of damage; dry or uncover it and try again |
| Counterfeit on a product you believe is genuine | Note the serial printed next to the code and contact the brand; staff can check it in the dashboard |

## For your team: checking a code in the dashboard

Use **Verify a code** to check a Private Code with your computer's or phone's camera without
counting it as a scan; see [Overview and scans](https://docs.satyakod.com/guides/overview-and-scans.md#check-a-code-yourself).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.