# External Verification (TEV)

### Overview

The External Verification feature enables brands to utilize their own domain for NFC verification experiences while leveraging TAGBASE's secure backend infrastructure. Instead of directing NFC tags to TAGBASE domains, the brand's domain is written directly onto the tags, ensuring a seamless, branded URL experience without compromising security or verification integrity.

### Why Use External Verification?

This feature is ideal when you want to use TAGBASE as a **complete white-label solution** for your product verification. Your customers will never see the TAGBASE brand—everything appears as your own infrastructure.

For example, you can set up `verify.brand.com` as your verification domain (we'll use this example throughout this guide). This domain is what gets written to the NFC tags and is the URL your customers see when they tap. Behind the scenes, it points to TAGBASE's infrastructure via a simple CNAME record.

**Benefits:**

* **Full brand control**: Your domain, your branding, your customer experience
* **No TAGBASE branding visible**: End users only interact with your domain
* **Customizable verification pages**: Build your own UI that matches your brand identity
* **Enterprise-grade security**: TAGBASE handles all cryptographic verification behind the scenes
* **Simple setup**: Just a DNS record and a JavaScript snippet

### How It Works

#### Initial Setup

1. You configure a verification domain (e.g., `verify.brand.com`) as a CNAME pointing to `external.tagbase.io`
2. TAGBASE validates and activates the domain for external verification
3. NFC tags are programmed with your domain instead of TAGBASE URLs

#### User Flow

1. User taps an NFC tag pointing to your domain
2. The request is handled by TAGBASE behind your CNAME
3. TAGBASE performs the secure verification process
4. The user is redirected to your external verification page with a tag identifier (`tid`) appended as a query parameter
5. Your page requests verification results from TAGBASE and renders a fully customized user experience

### Setup

#### 1. CNAME Configuration

Create a CNAME record in your DNS with the following values:

* **Type:** CNAME
* **Name:** `verify`
* **Value:** `external.tagbase.io`

This will make `https://verify.brand.com` route to TAGBASE's verification infrastructure.

#### 2. JavaScript Integration

Add this snippet to your verification page to fetch and display verification results:

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

    if (params.has(paramName)) {
      const url = `https://verify.brand.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();
        // Handle the verification response
        // If status is "pending", optionally collect geolocation
        if (json.data.status === "pending") {
          updateLocation(); // see geolocation section below
        }
      }
    }
  }

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

#### 3. API Response

Use this response to render information about the product on your verification page. The `data` field contains all custom data you've configured for this product and tag. The `messages` array contains helpful messages that should be displayed to the user.

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

**Field Reference**

| Field         | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| `status`      | Verification state: `pending`, `valid`, `invalid`, or `valid_with_warnings` |
| `on_device`   | Boolean indicating if verification occurred on current device               |
| `description` | Product description provided by the brand                                   |
| `image_urls`  | Array of product-related image URLs                                         |
| `data`        | Custom data defined at the tag level                                        |
| `messages`    | Instructions or messages to display to end users                            |

**Status Values**

* **pending**: First scan always returns this state
* **valid**: Verification successful
* **invalid**: Verification failed
* **valid\_with\_warnings**: Verified but with minor inconsistencies

#### 4. Geolocation Tracking (Optional)

To capture user location, you must collect it during the first scan (when `status` is `pending`). This is because the verification is only finalized on the second scan, and the geolocation data needs to be available before that happens.

```javascript
function updateLocation() {
  navigator.geolocation.getCurrentPosition(
    ({ coords }) => {
      const locationData = {
        latitude: coords.latitude,
        longitude: coords.longitude,
        accuracy: coords.accuracy,
      };

      document.cookie = `tagbase_geolocation=${encodeURIComponent(
        JSON.stringify(locationData)
      )}; path=/; SameSite=Lax; domain=.brand.com; max-age=${60 * 10};`; // expires in 10 minutes

    },
    (error) => {
      console.error(error);
    }
  );
}
```