External Verification Feature

Introduction

The External Verification Feature allows brands to host their own verification experience when a user scans a TAGBASE-protected NFC tag. Instead of redirecting users to a TAGBASE-hosted verification page, the user is redirected directly to a page on the brand's own domain.

This gives brands complete control over the verification UX while still relying on TAGBASE’s secure backend to handle the verification logic.

---

How It Works

• When a user taps the NFC tag, they are redirected to a brand-owned URL.

• This URL must include the tagbase_id as a query parameter.

• The brand's page then requests verification data from TAGBASE servers using a small JavaScript snippet.

• Based on the returned verification data (valid, invalid, pending, etc.), the brand can customize the displayed content.

---

URL Definitions

Each product in TAGBASE can define three URLs:

• Valid URL: Shown when verification is successful.

• Invalid URL: Shown when verification fails.

• Pending URL: Shown when verification is still in progress (first scan).

Note: You can define the same URL for all three cases and handle the different verification states inside your page based on the API response.

---

Prerequisites

1. CNAME Setup

In your domain manager, create a CNAME entry pointing to external.tagbase.io.

Example:

Type: CNAME
Name: tagbase
Value: external.tagbase.io

Your URL will then look like:

https://tagbase.abc.com

2. JavaScript Integration

On the page where you want to handle the verification (e.g., your product page), insert the following JavaScript snippet:

<script type="text/javascript">
    async function fetchData() {
        const paramName = "tagbase_id";
        const params = new URLSearchParams(window.location.search);

        if (params.has(paramName)) {
            const url = `https://tagbase.abc.com/verifications/${params.get(paramName)}`;

            const response = await fetch(url, {
                method: "GET",
                headers: {
                    accept: "application/json",
                },
                credentials: "include",
            });

            if (!response.ok) {
                throw new Error(`Response status: ${response.status}`);
            } else {
                const json = await response.json();
                // Your logic here
            }
        }
    }

    window.addEventListener("load", () => {
        fetchData();
    });
</script>

Important: Replace abc.com with your actual domain.

---

Example Response

When the script requests the verification data, the TAGBASE server will return a JSON response similar to the following:

{
  "data": {
    "data" : "....", // custom data defined on the tag level
    "id": "vrf_ULPkD39Y5884BYJFsfw3evkzgWp",
    "status": "pending",
    "description": "...",
    "title": "",
    "inserted_at": "2025-04-26T15:34:20.454709Z",
    "website": "https://abc.com/products/p1",
    "image_urls": [
      "https://abc.com/products/p1/images/01.jpg"
    ],
    "on_device": true
  },
  "messages": [
    {
      "type": "info",
      "text": "Please scan again to complete the verification process"
    }
  ]
}

---

Field Explanations

Field	Description
status	The verification status: pending, valid, invalid, or valid_with_warnings.
on_device	Indicates if the verification occurred on this device (true) or elsewhere (false).
description	A product description provided by the brand.
image_urls	Array of image URLs related to the product.
messages	Messages (e.g., instructions) that should be shown to the user.

---

Status Logic

• Pending First scan always results in pending.

• Valid / Invalid / Valid with Warnings After the second scan, the verification is finalized and will either be:

  • valid

  • invalid

  • valid_with_warnings (meaning the item is verified but there are some minor inconsistencies).

---

Example Workflow

1. User taps an NFC tag.

2. Redirected to https://www.abc.com/products/p1?tagbase_id=....

3. Page loads and executes the JavaScript script.

4. Script fetches verification data from https://tagbase.abc.com/verifications/:id.

5. Page dynamically adjusts the display depending on the status field (pending, valid, etc.).

---

Summary

With the External Verification Feature, brands can deliver a seamless, on-brand verification experience while maintaining the security and reliability of TAGBASE’s backend. This offers a flexible integration that enhances customer trust without sacrificing control.