> For the complete documentation index, see [llms.txt](https://astroport-1.gitbook.io/astroport.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://astroport-1.gitbook.io/astroport.one/docs/reference/analytics.readme.md).

# UPlanet Analytics System Documentation

## Overview

> Analytics events use **kind 10600**. Kind 10000 is reserved by NIP-51 for mute lists.

The UPlanet Analytics System (`astro.js`) provides a standardized way to collect and send analytics data in the UPlanet ecosystem. It supports multiple modes of operation depending on which libraries are loaded, from simple HTTP-based analytics to decentralized NOSTR events with optional encryption.

**Related NIPs:**

* [NIP-10600: UPlanet Analytics Events](https://github.com/papiche/Astroport.ONE/blob/master/papiche/nostr-nips/blob/NIP-101/10600-analytics-extension.md) - Analytics events use **kind 10600** (encrypted/non-encrypted determined by content). Kind 10000 is reserved by [NIP-51](https://nips.nostr.com/51) for mute lists.
* Note: Kind 10001 is reserved for NIP-51 pin list

***

## Modes of Operation

### Mode 1: Standalone (astro.js only)

When `astro.js` is loaded **alone**, it provides basic HTTP-based analytics functionality.

#### Available Functions

* **`uPlanetAnalytics.send(data, includeContext)`**
  * Sends analytics data via HTTP POST to `/ping` endpoint
  * Automatically calculates uSPOT URL from current page URL
  * Handles URL transformations (ipfs.domain → u.domain, localhost → localhost:54321)
  * Returns `Promise<boolean>`
* **`uPlanetAnalytics.sendWithContext(data)`**
  * Convenience method that automatically includes page context
  * Includes: URL, viewport, user agent, referer, timestamp
  * Returns `Promise<boolean>`
* **`uPlanetAnalytics.autoSend(data, includeContext)`**
  * Automatically sends analytics when DOM is ready
  * Useful for page view tracking
  * Returns `void`
* **`uPlanetAnalytics.getUSPOTBaseURL()`**
  * Calculates the correct uSPOT base URL
  * Handles URL transformations automatically
  * Returns `string`
* **`uPlanetAnalytics.getPageContext()`**
  * Gathers automatic page context data
  * Returns `Object` with timestamp, URL, viewport, user agent, referer

#### Example Usage

```html
<!-- Load astro.js -->
<script src="https://ipfs.copylaradio.com/ipns/copylaradio.com/astro.js"></script>

<script>
  // Basic analytics
  uPlanetAnalytics.send({
    type: 'page_view',
    source: 'email',
    email: 'user@example.com'
  });

  // With automatic page context
  uPlanetAnalytics.sendWithContext({
    type: 'multipass_card_usage',
    email: 'user@example.com',
    g1pubnostr: 'G1PUB...'
  });

  // Auto-send on page load
  uPlanetAnalytics.autoSend({
    type: 'page_view',
    source: 'web'
  });
</script>
```

#### Data Flow

```
User Action → uPlanetAnalytics.send()
    ↓
Calculate uSPOT URL (ipfs.domain → u.domain)
    ↓
HTTP POST to /ping endpoint
    ↓
Backend stores analytics
```

#### Limitations

* ❌ No NOSTR integration (no decentralized storage)
* ❌ No encryption support
* ❌ Analytics stored on centralized server only
* ✅ Simple and lightweight
* ✅ Works everywhere (no dependencies)

#### Web2 Compatibility Note

**This HTTP-based mode (`/ping` endpoint) is designed for web2 sites** that are not yet compatible with:

* MULTIPASS card scanning
* NOSTR browser extensions (NOSTR Connect, Alby, nos2x)
* Native NOSTR integration

**Use case**: Legacy websites, traditional web applications, or sites that need analytics without requiring users to have NOSTR capabilities.

**However**, a **pure NOSTR approach (kind 10600 events)** is **more robust and flexible** because:

* ✅ **Decentralized**: Data stored on user-controlled relays (not centralized server)
* ✅ **Verifiable**: Cryptographically signed by user
* ✅ **Queryable**: Can query analytics via standard NOSTR filters
* ✅ **User ownership**: User controls which relays store their data
* ✅ **No single point of failure**: No dependency on `/ping` endpoint availability
* ✅ **Privacy**: Optional encryption (kind 10600 with encrypted content) for sensitive analytics
* ✅ **Interoperable**: Works with any NOSTR client or relay

**Recommendation**: For new projects or sites that can require NOSTR, prefer **Mode 2** (NOSTR events) or **Mode 3** (Encrypted NOSTR events) over HTTP `/ping`. Use HTTP `/ping` only as a fallback or for web2 compatibility.

**See**: `/ping` endpoint implementation in `UPassport/54321.py` for server-side processing details.

***

### Mode 2: With common.js (NOSTR Integration)

When `astro.js` is loaded **after** `common.js`, it gains NOSTR integration capabilities.

#### Additional Functions Available

* **`uPlanetAnalytics.isNostrAvailable()`**
  * Checks if NOSTR connection is available
  * Returns `boolean`
* **`uPlanetAnalytics.sendAsNostrEvent(data, includeContext)`**
  * Sends analytics as NOSTR event (kind 10600)
  * Requires: `common.js` loaded + NOSTR connected
  * Falls back to HTTP `/ping` if NOSTR unavailable
  * Returns `Promise<boolean>`
  * **See:** [NIP-10600](https://github.com/papiche/Astroport.ONE/blob/master/papiche/nostr-nips/blob/NIP-101/10600-analytics-extension.md)
* **`uPlanetAnalytics.smartSend(data, includeContext, preferNostr, preferEncrypted, preferIPFS)`**
  * Automatically selects best available method
  * Tries encrypted NOSTR → unencrypted NOSTR → HTTP `/ping`
  * Returns `Promise<boolean>`

#### Example Usage

```html
<!-- Load common.js first (for NOSTR connection) -->
<script src="https://ipfs.copylaradio.com/ipns/copylaradio.com/common.js"></script>
<!-- Then load astro.js -->
<script src="https://ipfs.copylaradio.com/ipns/copylaradio.com/astro.js"></script>

<script>
  // Smart send: automatically uses NOSTR if available
  uPlanetAnalytics.smartSend({
    type: 'page_view',
    source: 'email',
    email: 'user@example.com'
  });

  // Force NOSTR event (requires NOSTR connection)
  uPlanetAnalytics.sendAsNostrEvent({
    type: 'button_click',
    button_id: 'myButton'
  });
</script>
```

#### Data Flow

```
User Action → uPlanetAnalytics.smartSend()
    ↓
Check if NOSTR available (via common.js)
    ↓
YES → Send as NOSTR event (kind 10600)
    ↓
NOSTR Relay stores event
    ↓
NO → Fallback to HTTP POST /ping
```

#### Benefits

* ✅ **Decentralized storage**: Analytics stored on NOSTR relays
* ✅ **Verifiable**: Cryptographically signed by user
* ✅ **Queryable**: Can query analytics via NOSTR filters
* ✅ **User control**: User chooses which relays store data
* ✅ **Graceful fallback**: Falls back to HTTP if NOSTR unavailable

#### NOSTR Event Structure (kind 10600)

```json
{
  "kind": 10600,
  "content": "{\"type\":\"page_view\",\"source\":\"email\",...}",
  "tags": [
    ["t", "analytics"],
    ["t", "page_view"],
    ["source", "email"],
    ["email", "user@example.com"]
  ],
  "created_at": 1704110400,
  "pubkey": "user_pubkey_hex",
  "id": "event_id_hex",
  "sig": "signature"
}
```

**See:** [NIP-10600: UPlanet Analytics Events](https://github.com/papiche/Astroport.ONE/blob/master/papiche/nostr-nips/blob/NIP-101/nostr-nips/10600-analytics-extension.md)

***

### Mode 3: With common.js + nostr.bundle.js (Encrypted Analytics)

When `astro.js` is loaded **after** `common.js` and `nostr.bundle.js`, it gains encryption capabilities.

#### Additional Functions Available

* **`uPlanetAnalytics.isEncryptionAvailable()`**
  * Checks if encryption is available (NostrTools + user private key)
  * Returns `boolean`
* **`uPlanetAnalytics.sendEncryptedAsNostrEvent(data, includeContext, useIPFS)`**
  * Sends encrypted analytics as NOSTR event (kind 10600 with encrypted content)
  * Requires: `nostr.bundle.js` + `common.js` + user private key
  * Uses NIP-44 encryption (ChaCha20-Poly1305)
  * Only user can decrypt their own analytics
  * Returns `Promise<boolean>`
  * **See:** [NIP-10600](https://github.com/papiche/Astroport.ONE/blob/master/papiche/nostr-nips/blob/NIP-101/10600-analytics-extension.md)
* **`uPlanetAnalytics.sendEncryptedAsNostrEventWithIPFS(data, includeContext)`**
  * Uploads analytics to IPFS, encrypts only CID
  * Useful for large data (> 50 KB)
  * Returns `Promise<boolean>`

#### Example Usage

```html
<!-- Load nostr.bundle.js (for encryption) -->
<script src="https://ipfs.copylaradio.com/ipns/copylaradio.com/nostr.bundle.js"></script>
<!-- Load common.js (for NOSTR connection) -->
<script src="https://ipfs.copylaradio.com/ipns/copylaradio.com/common.js"></script>
<!-- Load astro.js -->
<script src="https://ipfs.copylaradio.com/ipns/copylaradio.com/astro.js"></script>

<script>
  // Encrypted analytics (Approach A: Direct encryption - default)
  uPlanetAnalytics.sendEncryptedAsNostrEvent({
    type: 'page_view',
    source: 'web',
    current_url: window.location.href
  });

  // Encrypted analytics (Approach B: IPFS + CID)
  uPlanetAnalytics.sendEncryptedAsNostrEvent({
    type: 'page_view',
    source: 'web'
  }, true, true);  // includeContext=true, useIPFS=true

  // Smart send with encryption preference
  uPlanetAnalytics.smartSend({
    type: 'navigation_history',
    source: 'web'
  }, true, true, true);  // includeContext, preferNostr, preferEncrypted
</script>
```

#### Data Flow

```
User Action → uPlanetAnalytics.sendEncryptedAsNostrEvent()
    ↓
Separate public and sensitive data
    ↓
Encrypt sensitive data with NIP-44 (user's own pubkey)
    ↓
Send as NOSTR event (kind 10600 with encrypted content)
    ↓
NOSTR Relay stores encrypted event
    ↓
Only user can decrypt (with their private key)
```

#### Benefits

* ✅ **Privacy**: Only user can decrypt their analytics
* ✅ **Self-ownership**: User controls encrypted data on their relays
* ✅ **History**: Complete encrypted navigation history
* ✅ **Performance**: Hybrid approach (public data in tags, sensitive data encrypted)
* ✅ **10x faster decryption**: Only encrypts sensitive data (\~500 bytes - 2 KB)

#### Encryption Approaches

**Approach A: Direct Encryption** (default, recommended for analytics \~3-5 KB)

* Encrypts sensitive data directly in NOSTR event content
* No IPFS needed
* Simpler and faster

**Approach B: IPFS + CID** (for large data > 50 KB)

* Uploads data to IPFS, encrypts only CID
* Same technique as [NIP-A0 Encryption Extension](https://github.com/papiche/Astroport.ONE/blob/master/papiche/nostr-nips/blob/NIP-101/A0-encryption-extension.md)
* Ultra-fast decryption (CID only)

**See:** [NIP-10600: UPlanet Analytics Events](https://github.com/papiche/Astroport.ONE/blob/master/papiche/nostr-nips/blob/NIP-101/10600-analytics-extension.md) (encrypted/non-encrypted determined by content)

***

## Function Reference

### Core Functions (Available in all modes)

| Function                         | Description                 | Returns            |
| -------------------------------- | --------------------------- | ------------------ |
| `getUSPOTBaseURL()`              | Calculate uSPOT base URL    | `string`           |
| `getPageContext()`               | Get automatic page context  | `Object`           |
| `send(data, includeContext)`     | Send analytics via HTTP     | `Promise<boolean>` |
| `sendWithContext(data)`          | Send with automatic context | `Promise<boolean>` |
| `autoSend(data, includeContext)` | Auto-send on page load      | `void`             |

### NOSTR Functions (Requires common.js)

| Function                                                                    | Description                      | Returns            |
| --------------------------------------------------------------------------- | -------------------------------- | ------------------ |
| `isNostrAvailable()`                                                        | Check if NOSTR is available      | `boolean`          |
| `sendAsNostrEvent(data, includeContext)`                                    | Send as NOSTR event (kind 10600) | `Promise<boolean>` |
| `smartSend(data, includeContext, preferNostr, preferEncrypted, preferIPFS)` | Auto-select best method          | `Promise<boolean>` |

### Encryption Functions (Requires nostr.bundle.js + common.js)

| Function                                                   | Description                                        | Returns            |
| ---------------------------------------------------------- | -------------------------------------------------- | ------------------ |
| `isEncryptionAvailable()`                                  | Check if encryption is available                   | `boolean`          |
| `sendEncryptedAsNostrEvent(data, includeContext, useIPFS)` | Send encrypted (kind 10600 with encrypted content) | `Promise<boolean>` |
| `sendEncryptedAsNostrEventWithIPFS(data, includeContext)`  | Send encrypted via IPFS                            | `Promise<boolean>` |

***

## URL Transformations

The system automatically transforms URLs to find the correct uSPOT endpoint:

* `https://ipfs.domain.tld` → `https://u.domain.tld`
* `u.domain.tld` → `u.domain.tld` (unchanged)
* `http://127.0.0.1:8080` → `http://127.0.0.1:54321`
* `http://localhost:8080` → `http://localhost:54321`

***

## Data Format

All analytics data follows this structure:

```json
{
  "type": "page_view|button_click|multipass_card_usage|...",
  "source": "email|web|api|...",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "email": "user@example.com",  // optional
  "current_url": "https://...",
  "user_agent": "...",
  "viewport": {
    "width": 1920,
    "height": 1080
  },
  "referer": "https://...",
  "uspot_url": "https://u.domain.tld",
  // ... custom fields
}
```

***

## Error Handling

* All errors are silently caught and logged to `console.debug`
* Analytics system never blocks page functionality
* Graceful fallback: NOSTR → HTTP, encrypted → unencrypted → HTTP
* User experience is never interrupted

***

## Use Cases

### 1. Simple Page Tracking (Standalone)

```html
<script src="astro.js"></script>
<script>
  uPlanetAnalytics.autoSend({
    type: 'page_view',
    source: 'web'
  });
</script>
```

### 2. Email Analytics (Standalone)

```html
<script src="astro.js"></script>
<script>
  uPlanetAnalytics.sendWithContext({
    type: 'multipass_card_usage',
    source: 'email',
    email: 'user@example.com'
  });
</script>
```

### 3. Decentralized Analytics (With common.js)

```html
<script src="common.js"></script>
<script src="astro.js"></script>
<script>
  uPlanetAnalytics.smartSend({
    type: 'page_view',
    source: 'web'
  });
</script>
```

### 4. Private Navigation History (With nostr.bundle.js + common.js)

```html
<script src="nostr.bundle.js"></script>
<script src="common.js"></script>
<script src="astro.js"></script>
<script>
  uPlanetAnalytics.sendEncryptedAsNostrEvent({
    type: 'navigation_history',
    source: 'web',
    current_url: window.location.href
  });
</script>
```

***

## Comparison Table

| Feature                                          | Standalone | + common.js | + nostr.bundle.js           |
| ------------------------------------------------ | ---------- | ----------- | --------------------------- |
| HTTP `/ping`                                     | ✅          | ✅           | ✅                           |
| NOSTR events (kind 10600)                        | ❌          | ✅           | ✅                           |
| Encrypted events (kind 10600, encrypted content) | ❌          | ❌           | ✅                           |
| Decentralized storage                            | ❌          | ✅           | ✅                           |
| User control                                     | ❌          | ✅           | ✅                           |
| Privacy (encryption)                             | ❌          | ❌           | ✅                           |
| Dependencies                                     | None       | common.js   | nostr.bundle.js + common.js |

***

## References

* **Implementation**: `UPlanet/astro.js`
* **NIP-10600**: [UPlanet Analytics Events](https://github.com/papiche/Astroport.ONE/blob/master/papiche/nostr-nips/blob/NIP-101/10600-analytics-extension.md) (supports both encrypted and unencrypted analytics)
* **NIP-A0**: [Encryption Extension](https://github.com/papiche/Astroport.ONE/blob/master/papiche/nostr-nips/blob/NIP-101/A0-encryption-extension.md) (uses same IPFS+CID technique)

***

## Architecture Decision: HTTP vs NOSTR

### When to Use HTTP `/ping` (Mode 1)

Use HTTP `/ping` endpoint when:

* ✅ **Web2 compatibility required**: Site doesn't support NOSTR or MULTIPASS
* ✅ **Legacy integration**: Existing web2 infrastructure that can't be modified
* ✅ **Fallback mechanism**: Backup when NOSTR is unavailable
* ✅ **Simple deployment**: No NOSTR dependencies needed

**Trade-offs**:

* ❌ Centralized storage (single point of failure)
* ❌ No user control over data storage
* ❌ Not queryable via NOSTR filters
* ❌ Requires `/ping` endpoint to be available

### When to Use Pure NOSTR (Mode 2/3)

Use NOSTR events (kind 10600) when:

* ✅ **Decentralization priority**: Want user-controlled data storage
* ✅ **Verifiability needed**: Cryptographically signed analytics
* ✅ **Queryability required**: Need to query analytics via NOSTR filters
* ✅ **User ownership**: Users should control their analytics data
* ✅ **Privacy concerns**: Sensitive data requires encryption (kind 10600 with encrypted content)
* ✅ **Interoperability**: Want to work with any NOSTR client/relay

**Trade-offs**:

* ❌ Requires NOSTR connection (browser extension or native support)
* ❌ Slightly more complex setup (needs `common.js` or `nostr.bundle.js`)
* ✅ More robust and flexible long-term

**Recommendation**: For new projects, prefer **pure NOSTR** (Mode 2/3). Use HTTP `/ping` only for web2 compatibility or as a fallback.

## Best Practices

1. **Start simple**: Use standalone mode for basic analytics (web2 compatibility)
2. **Add NOSTR**: Load `common.js` for decentralized storage (preferred for new projects)
3. **Add encryption**: Load `nostr.bundle.js` for private analytics
4. **Use smartSend**: Let the system choose the best method automatically
5. **Include context**: Use `sendWithContext()` for automatic page data
6. **Handle errors gracefully**: System already does this, but be aware of fallbacks
7. **Prefer NOSTR**: For new projects, use pure NOSTR events (kind 10600) over HTTP `/ping` when possible

***

**Last Updated**: 2024\
**Status**: Production\
**Version**: 1.0.0
