ACCUZ® Brand Guard™ / SDK 1.3.3 / HTTP API v1

Website integration guide

Start here

Your server and the customer’s browser

The website receives the complete HTTPS NFC URL at the approved entry path. Capture it before a redirect or URL parser rewrites its query. Preserve case, parameter order and percent encoding. Configure trusted proxies to preserve the original origin and request target. Keep full tap URLs, raw IPs and authorization headers out of logs.

Place the verification token in your server’s secret store. Only your server calls the assigned API. The browser receives an opaque session-bound reference to the saved outcome. Protect result responses with Cache-Control: no-store and a no-referrer policy. Keep cookie and idempotency values out of analytics.

Submit and recover one operation

Atomically persist a random Idempotency-Key, exact request body, assigned API origin, encoding and routing configuration before the first POST. Send POST /api/customer/v1/verifications with Authorization: Bearer …, Content-Type: application/json and Idempotency-Key. The JSON requires encodingVersionId and tapUrl. Optional clientRequestId is a correlation label. The URL fits in 1024 UTF-8 bytes and the entire body in 4096 bytes.

Use the same origin, key and original body after lost responses and HTTP 202, 429 or 503. Honor Retry-After and bound retries by the operation’s lifetime. An expired pending lease is resumed by resubmitting the original POST. GET /api/customer/v1/verifications/{verificationId} retrieves an existing operation with verifications:read. An integration with only verifications:execute recovers using the original POST. A new physical tap starts its own operation.

Once a complete HTTP 200 body is received, an unreadable envelope, invalid required timestamps, untrusted identity, contradictory seal fields or mismatched encoding ID is terminal for this operation. Keep a safe support reference and diagnostic category. Clear raw tap data and stop automated retries. Validate acceptedAt and decidedAt independently; for accepted results their textual values may differ. Optional routing metadata can fall back to a generic result without changing a trustworthy decision.

Use an existing backend

Import the helper and pass only server-controlled, previously assigned configuration. In this example operation is already persisted, originalUrl is the exact captured URL, and token came from your secret store. Store the confirmed receipt before redirecting the browser. See the runnable adapter for storage, concurrent access and uncertain outcomes.

import { verifyTap } from './reference/verification-core.mjs';

const result = await verifyTap({
  baseUrl: operation.apiOrigin,
  approvedApiOrigin: settings.apiOrigin,
  originalApiOrigin: operation.apiOrigin,
  encodingVersionId: operation.encodingVersionId,
  tapUrl: operation.originalUrl,
  idempotencyKey: operation.idempotencyKey,
  token
});

Choose a product page

Read receipt.result first. A currently eligible valid receipt may select a product page. Use a confirmed Item-specific display path when present. In SKU mode look up the exact full SKU in your own catalog, preserving case and punctuation. Your site chooses the language and localized URL. In path mode accept only an approved same-origin relative path. In UID mode resolve an existing association through your controlled backend. Create or update such associations only in your authorized business process.

A missing or malformed optional SKU, an unsafe path or a catalog miss cannot erase a valid decision. Keep the true receipt on a generic result page. A previously confirmed Item-to-page association may be used by your own backend when it matches this verified tenant and Item. Initial configuration requires no Item list. Displaying a public catalog page alone never establishes a tap.

For a website-managed SKU, register its same-origin localized paths in the server catalog. On a new tap the reference server chooses a registered language using the entry request’s Accept-Language or the configured default. A manual language switch must preserve the opaque reference inside this site. Only paths frozen for the authenticated product may display its receipt. An Item-specific destination takes priority.

Embed the result in an existing page

Load the module and mount its custom element on the product template. Serve /bg/component.mjs, /bg/result, /bg/retry and /bg/presented from the same approved origin. Keep /v/result and each configured NFC entry available. Preserve the product page’s business query. __bg_receipt is the reserved, session-bound display reference.

The widget presents the original decision time and applicable count/seal evidence. A first confirmed response for an active tap can arrive by same-key recovery. Reopening or refreshing a displayed receipt shows the previous result. When current eligibility has changed, show the historical decision together with the current status. The locale can follow your product template.

The supplied component includes English, Chinese, Japanese and Korean. Use the template’s lang attribute. To add a language, call BrandGuardVerification.registerLocale(code, dictionary) after importing the module and before mounting the element.

After the result appears, the component posts an internal same-origin acknowledgement to /bg/presented. Keep the entire /bg/* route available. A lost result response can still be displayed as the first result on recovery.

Use the original decision timestamp with its time zone. The component formats it according to the page language and the configured display time zone (default UTC). The same receipt keeps its instant and count across language changes. Show seal evidence separately from the authenticity decision. A reading reporting no opening cannot guarantee lifetime integrity.

<script type="module" src="/bg/component.mjs"></script>
<brandguard-verification lang="en"></brandguard-verification>

Run the adapters

Start with config/site.example.json: one entryPath /v, one encodingVersionId and the server environment secret BRANDGUARD_VERIFICATION_TOKEN. Copy the example to a private, ignored config/site.local.json, set BG_SITE_CONFIG to that file path through your server configuration, and run node reference/node-server.mjs --live only behind the approved HTTPS origin. Do not put the token in source code, browser code or shell arguments. The default node reference/node-server.mjs is a credential-free local simulator. File storage is single-process.

For Cloudflare follow docs/cloudflare.html and the actual default wrangler.toml. It declares the SQLite Durable Object, the /v*, /v/result* and /bg/* routes, and required SITE_CONFIG and BRANDGUARD_VERIFICATION_TOKEN secrets. The private setup helper validates and creates a secrets file without displaying values. A pinned Wrangler deploy uploads code and required secrets together; missing required secrets fail deployment. The maintainer runs local tests and dry-run only, not a real deployment.

Run npm test for dependency-free offline checks. Use Node ≥22.12 (validated with 24.16) for full tests and Wrangler. Node 20 supports only the dependency-free reference. With Node and npm installed and access to the package registry on the first run, npm run test:full installs the locked native tooling and runs all suites, including genuine workerd/SQLite. Reports default to test-output/ inside the unpacked SDK. Set BG_SDK_QA_DIR for a different location.

Advanced only: when separate approved paths truly require separate encoding/credential bindings, use config/advanced-multi-entry.example.json with wrangler.advanced.toml. Its second neutral example path is /scan/verify. Compatible products may share the default single entry. Changing path may require compatible written tags; an SDK upgrade does not rewrite them.

Capability and upgrade notes

This SDK uses HTTP API v1. SKU and same-origin display-path snapshots are optional and depend on the verified Item, routing mode and platform capability. Older saved receipts can lack both. Check support with the operator for your assigned environment.

From 1.2.3 or 1.3, retain existing approved NFC entries and the environment of any pending operation. Replacing the SDK alone does not rotate tokens, migrate a customer or re-encode tags. Retain a credential only when its tenant, integration, environment, expiry and required scope still match. Confirm the encoding ID for the tags you will test. A new product using the same approved encoding can share it. A changed template or entry often requires a new immutable encoding.

A standard NTAG 424 DNA provides authentication. Only a supported tamper-evident chip and encoding can provide electronic seal evidence. If seal.supported is false, explicitly state that this tag does not support an electronic seal. This is not a missing seal reading. For a new exact NFC path, confirm the written NDEF record and the first request on both iPhone and Android.

Several SKUs may share one website connection and compatible encoding. Your server chooses its credential and encoding before it can read a receipt SKU. When two independent connections use one website, configure a reliable way to distinguish their incoming taps, for example a separate approved entry path with compatible tags and Writer support. Keep the settings for older tags available.

Migration from 1.3 / 1.3.1: an older integration may retain the original body and idempotency key after 401 or 403 for manual resubmission. In 1.3.3 the reference flow ends the affected submission and clears sensitive pending request data. Update custom retry queues and support runbooks. Diagnose missing, expired, revoked or wrong-environment tokens for 401; for 403 check integration status, environment binding and execute/read scopes. After correction perform a fresh physical tap. For an existing known verification ID, an authorized read can inspect its original receipt. Transient delivery uncertainty, 202, 429 and 503 keep their original operation and retry rules.

Optional visitor region

Keep visitor region disabled unless the operator has enabled it and the website has the necessary notice and authority. Only a trusted ingress may supply the visitor IP. The backend’s own IP or an untrusted forwarded header is unsuitable. Freeze the optional context on the first operation. Show the estimated location only when available, with the attribution provided in the response. Region availability never changes the authenticity decision.

The component displays available city/country information in its page language where a country code is available, with a readable fallback for unavailable data. It does not display source codes, reason codes, coordinates or IP addresses. Whenever a region estimate or unavailable message is shown, the component uses fixed clickable DB-IP and CC BY 4.0 links.

Record acceptance

For two distinct physical Items, record the package and platform versions, verificationId, itemId, decidedAt with timezone, result, accepted count and actual page path. Include SKU or routing mode and electronic seal status when supported. Test another SKU, missing mapping, direct product visits, refresh, original-key recovery, a replay under a new key, revoked or insufficient credentials and another browser. Check access through the deployed backend or Worker. A 401 confirms an anonymous request reached authentication; a new successful live receipt requires the assigned settings and a real tap.

Record three outcomes separately. The SDK maintainer verifies Node, native workerd/SQLite, translations, language switching, multi-entry routing and misconfigured credentials. The customer engineer verifies the contract, issued settings, actual site and physical taps using their own implementation. For a first-time usability sign-off, ask an engineer who has not taken part in the integration to start from the unopened ZIP and record where they needed help.

Style the existing component

The component is a custom element with Shadow DOM. Use inherited font/color and CSS ::part() on its published parts: heading, time, details, region, support, languages, language-link, attribution, provider-link, license-link, retry. Text size, spacing and link colors can match your website without editing vendor JavaScript. Do not hide decision text, seal evidence or attribution. Test four languages, long text and narrow screens.

The API optional receipt field is visitorLocation with state, city, country, countryCode, source, unavailableReason and attribution. The reference view model exposes it as location plus regionEnabled. Keep server-supplied snapshots; never accept visitor-provided location or call a public lookup from the browser. Country names are localized from countryCode; source/reason codes and IPs are not displayed.

brandguard-verification { font: inherit; color: #172923; }
brandguard-verification::part(heading) { font-size: 1.25rem; }
brandguard-verification::part(details) { font: inherit; white-space: pre-wrap; }
brandguard-verification::part(region) { margin-block: .75rem; }
brandguard-verification::part(languages) { display: flex; gap: .75rem; flex-wrap: wrap; }
brandguard-verification::part(language-link),
brandguard-verification::part(provider-link),
brandguard-verification::part(license-link) { color: #115e59; }

HTTP errors and verification results · OpenAPI v1