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

# Ground Truth

> How NFC-verified user behavior improves recommendations

# Ground Truth Data

Ground Truth is PriveTag's unique advantage - real, verified user behavior data that proves what users actually do, not just what they click or book.

## What is Ground Truth?

<Info>
  **Ground Truth** = Data verified by real-world action (NFC scan or QR verification at venue)

  Unlike web analytics that track clicks, Ground Truth captures when a user **actually visited** a venue.
</Info>

## The Problem with Traditional Data

Most recommendation systems rely on:

| Data Type    | Weakness                         |
| ------------ | -------------------------------- |
| **Clicks**   | Users browse but don't visit     |
| **Bookings** | Users book but don't show up     |
| **Reviews**  | Selection bias, fake reviews     |
| **Surveys**  | Recall bias, social desirability |

### Result: Recommendation Drift

```mermaid theme={null}
graph LR
    A[Users Click] --> B[System Learns]
    B --> C[Recommends Clicked Items]
    C --> D[Users Click More]
    D --> B

    style A fill:#ff6b6b
    style B fill:#ff6b6b
    style C fill:#ff6b6b
    style D fill:#ff6b6b
```

This creates a **feedback loop of assumptions**, not reality.

## PriveTag's Ground Truth Approach

### How It Works

```mermaid theme={null}
sequenceDiagram
    participant User
    participant AI Agent
    participant PriveTag
    participant Venue

    Note over AI Agent,PriveTag: Recommendation Phase
    AI Agent->>PriveTag: POST /recommend
    PriveTag-->>AI Agent: Activities + context_log_id

    Note over AI Agent,User: Booking Phase
    AI Agent->>PriveTag: POST /execute_booking (context_log_id)
    PriveTag->>User: Voucher with QR

    Note over User,Venue: Verification Phase (Ground Truth)
    User->>Venue: Shows QR / Scans NFC
    Venue->>PriveTag: POST /verify
    PriveTag->>PriveTag: Record Ground Truth

    Note over PriveTag: Links context_log_id to actual visit
```

### The Verification Moment

When a user visits a venue:

1. **NFC Tap** - User taps their hotel NFC card at venue
2. **QR Scan** - Venue scans voucher QR code
3. **Check-in** - User checks in at venue reception

Each verification creates a Ground Truth record:

```json theme={null}
{
  "id": "gt_xyz789",
  "booking_id": "bkg_abc123",
  "context_log_id": "ctx_def456",
  "activity_id": "act_safari",
  "verified_at": "2025-12-15T10:30:00Z",
  "verification_method": "nfc_tap",
  "user_profile": {
    "travel_type": "family",
    "nationality": "KR"
  }
}
```

## Feedback Loop

Ground Truth creates a **virtuous cycle**:

```mermaid theme={null}
graph TD
    A[Similar Profile Requests Recommendations] --> B[System Uses Ground Truth]
    B --> C[Recommends Verified Favorites]
    C --> D[User Books & Visits]
    D --> E[New Ground Truth Created]
    E --> B

    style A fill:#51cf66
    style B fill:#51cf66
    style C fill:#51cf66
    style D fill:#51cf66
    style E fill:#51cf66
```

### Real Example

| Profile                  | Without Ground Truth          | With Ground Truth                    |
| ------------------------ | ----------------------------- | ------------------------------------ |
| Korean Family in Bangkok | Safari World (popular online) | Safari World (85% verified visits)   |
|                          | Dream World (high click rate) | SEA LIFE (78% verified visits)       |
|                          | Night Market (cheap)          | ❌ Night Market (12% verified visits) |

The Night Market appears in traditional recommendations because it's cheap and gets clicks, but families rarely actually visit. Ground Truth deprioritizes it.

## Data Quality

### Verification Rate

| Metric                     | Value |
| -------------------------- | ----- |
| Bookings with Ground Truth | 85%+  |
| NFC Verification           | 60%   |
| QR Verification            | 35%   |
| Manual Check-in            | 5%    |

### Why High Verification?

* **Hotel Integration**: NFC cards issued to all guests
* **Incentive Structure**: Venues earn commission on verification
* **Seamless UX**: Tap or scan takes \< 3 seconds

## Using Ground Truth in Your App

### Recommendation Quality

Higher Ground Truth coverage = better recommendations:

```json theme={null}
{
  "recommendations": [
    {
      "id": "act_safari",
      "relevance_score": 95,
      "ground_truth_score": 92,
      "verified_visits": 1250,
      "similar_profile_visits": 340
    }
  ]
}
```

### Webhook Events

Receive Ground Truth events via webhook:

```json theme={null}
{
  "event": "qr_verified",
  "data": {
    "booking_id": "bkg_abc123",
    "context_log_id": "ctx_def456",
    "verified_at": "2025-12-15T10:30:00Z"
  }
}
```

### Analytics

Track your recommendation effectiveness:

```bash theme={null}
# Your AI agent's performance
GET /api/analytics/ground-truth?api_key=pk_xxx

# Response
{
  "period": "last_30_days",
  "recommendations_made": 5420,
  "bookings_created": 892,
  "ground_truth_verified": 758,
  "verification_rate": 85%,
  "recommendation_accuracy": 78%
}
```

## Ground Truth Score

Activities are scored based on Ground Truth:

### Calculation

```
GT_Score = (verified_visits / recommended_count) * profile_similarity_weight
```

### Factors

| Factor                 | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| **Verified Visits**    | How many times users actually visited                    |
| **Recommended Count**  | How many times activity was recommended                  |
| **Profile Similarity** | How similar visiting users' profiles are to current user |
| **Recency**            | More recent visits weighted higher                       |

### Example

Safari World for Korean Families:

* Recommended 1000 times to Korean families
* 850 bookings created
* 720 verified visits (Ground Truth)
* **GT Score: 72%** (720/1000)

Night Market for Korean Families:

* Recommended 500 times to Korean families
* 180 bookings created
* 60 verified visits (Ground Truth)
* **GT Score: 12%** (60/500)

## Privacy & Data Handling

<Warning>
  **Privacy First**: We collect Ground Truth data with user consent and anonymize for aggregate analysis.
</Warning>

### What We Store

| Data             | Purpose                 | Retention |
| ---------------- | ----------------------- | --------- |
| Visit timestamp  | Aggregate patterns      | 24 months |
| Profile type     | Segment recommendations | 24 months |
| Activity visited | Improve scoring         | Permanent |

### What We DON'T Store

* Personal identification details
* Exact location tracking
* Session recordings
* Financial information

### Anonymization

Individual records are anonymized for ML training:

```json theme={null}
// Raw record
{
  "user_id": "usr_abc123",
  "name": "John Doe",
  "activity": "Safari World"
}

// Anonymized for ML
{
  "profile_hash": "a1b2c3",
  "profile_type": "family_kr_mid",
  "activity_id": "act_safari"
}
```

## Improving Your Ground Truth

### Best Practices

<AccordionGroup>
  <Accordion title="Always pass context_log_id">
    When booking, include the `context_log_id` from recommendations. This links the recommendation to the eventual visit.

    ```json theme={null}
    {
      "activity_id": "act_safari",
      "context_log_id": "ctx_abc123"  // Don't forget this!
    }
    ```
  </Accordion>

  <Accordion title="Enable webhooks for qr_verified">
    Track when your recommendations lead to actual visits:

    ```json theme={null}
    {
      "webhook_url": "https://your-server.com/webhooks",
      "webhook_events": ["qr_verified"]
    }
    ```
  </Accordion>

  <Accordion title="Encourage voucher usage">
    Remind users to use their voucher at the venue. Higher verification = better future recommendations.
  </Accordion>
</AccordionGroup>

## Metrics Dashboard

Track Ground Truth metrics for your integration:

| Metric                      | Description                                  | Good Target |
| --------------------------- | -------------------------------------------- | ----------- |
| **Verification Rate**       | % of bookings verified                       | > 80%       |
| **Recommendation Accuracy** | % of verified visits that matched top 3 recs | > 60%       |
| **Profile Match Rate**      | How well visits match profile predictions    | > 70%       |
| **Time to Visit**           | Days between booking and visit               | \< 3 days   |

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/authentication/webhooks">
    Receive Ground Truth events
  </Card>

  <Card title="Context Pipeline" icon="diagram-project" href="/b2a-platform/context-pipeline">
    How context affects recommendations
  </Card>
</CardGroup>