### Quick Start Installation

Source: https://github.com/soxft/busuanzi/wiki/usage

Include the script tag and use the provided span IDs to display visitor statistics on your page.

```html
<script defer src="https://busuanzi.9420.ltd/js"></script>

Total page views: <span id="busuanzi_page_pv"></span> times
Total visitors: <span id="busuanzi_page_uv"></span> people
Total site views: <span id="busuanzi_site_pv"></span> times
Total site visitors: <span id="busuanzi_site_uv"></span> people
```

--------------------------------

### Install Busuanzi Binary

Source: https://context7.com/soxft/busuanzi/llms.txt

Instructions for downloading the binary and creating the configuration file.

```bash
# Clone repository and download binary
git clone https://github.com/soxft/busuanzi && cd busuanzi
wget https://github.com/soxft/busuanzi/releases/download/v2.8.3/busuanzi-linux-amd64-v2.8.3 -O busuanzi
chmod +x busuanzi

# Edit configuration
cat > config.yaml << 'EOF'
Web:
  Address: 0.0.0.0:8080
  Cors: "*"
  Debug: false
  Log: true
Redis:
  Address: localhost:6379
  Password: ""
  Database: 0
  TLS: false
  Prefix: bsz
  MaxIdle: 25
  MaxActive: 100
  MinIdle: 25
  MaxRetries: 3
Bsz:
  Expire: 0
  Secret: "your-random-secret-key"
  Encrypt: "MD516"
  PathStyle: true
EOF

# Run the service
./busuanzi
```

--------------------------------

### Run Busuanzi with Docker

Source: https://github.com/soxft/busuanzi/wiki/install

Command to start the service using Docker Compose.

```shell
docker compose up -d
```

--------------------------------

### Configure via Environment Variables

Source: https://context7.com/soxft/busuanzi/llms.txt

Override default settings using environment variables before starting the service.

```bash
# Web server configuration
export WEB_ADDRESS="0.0.0.0:8080"
export WEB_CORS="https://example.com,https://www.example.com"
export WEB_DEBUG="false"
export WEB_LOG="true"

# Redis configuration
export REDIS_ADDRESS="localhost:6379"
export REDIS_PASSWORD="your-redis-password"
export REDIS_DATABASE="0"
export REDIS_TLS="false"
export REDIS_PREFIX="bsz"
export REDIS_MAXIDLE="25"
export REDIS_MAXACTIVE="100"
export REDIS_MINIDLE="25"
export REDIS_MAXRETRIES="3"

# Busuanzi settings
export BSZ_EXPIRE="0"           # 0 = never expires, otherwise seconds
export BSZ_SECRET="random-key"  # JWT signing secret
export BSZ_ENCRYPT="MD516"      # MD516 or MD532
export BSZ_PATHSTYLE="true"     # true for new path style, false for legacy

# Start with environment variables
./busuanzi
```

--------------------------------

### Manage Busuanzi Service

Source: https://context7.com/soxft/busuanzi/llms.txt

Commands to start the Docker service and verify connectivity.

```bash
# Start the service
docker compose up -d

# Verify the service is running
curl http://localhost:8080/ping
# Response: pong
```

--------------------------------

### GET /jsonp

Source: https://context7.com/soxft/busuanzi/llms.txt

Legacy JSONP endpoint for cross-origin script loading.

```APIDOC
## GET /jsonp

### Description
JSONP endpoint for legacy integrations that require cross-origin script loading.

### Method
GET

### Endpoint
/jsonp

### Parameters
#### Query Parameters
- **callback** (string) - Required - The name of the JavaScript callback function.

#### Request Headers
- **Referer** (string) - Required - The URL of the page being tracked.
```

--------------------------------

### GET /ping

Source: https://context7.com/soxft/busuanzi/llms.txt

Health check endpoint.

```APIDOC
## GET /ping

### Description
Simple health check endpoint for monitoring and load balancer configuration.

### Method
GET

### Endpoint
/ping

### Response
#### Success Response (200)
- Returns "pong"
```

--------------------------------

### Retrieve Statistics via GET

Source: https://context7.com/soxft/busuanzi/llms.txt

Retrieve current statistics without incrementing counters. Requires a referer header.

```bash
curl -X GET "https://busuanzi.9420.ltd/api" \
    -H "x-bsz-referer: https://example.com/blog/my-post"
```

--------------------------------

### GET /api

Source: https://context7.com/soxft/busuanzi/llms.txt

Retrieves current statistics without incrementing counters.

```APIDOC
## GET /api

### Description
Retrieves current statistics without incrementing any counters.

### Method
GET

### Endpoint
/api

### Parameters
#### Request Headers
- **x-bsz-referer** (string) - Required - The URL of the page being tracked.

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request.
- **data** (object) - Statistics object.

#### Error Response (400/Other)
- **success** (boolean) - false
- **message** (string) - Error description (e.g., "invalid referer")
```

--------------------------------

### Example Response for Increment and Retrieve Data

Source: https://github.com/soxft/busuanzi/wiki/api

This JSON structure represents a successful response when incrementing and retrieving website statistics. It includes counts for page views, unique page visitors, site-wide views, and unique site visitors.

```json
{
    "data": {
        "page_pv": 1,
        "page_uv": 1,
        "site_pv": 1,
        "site_uv": 1
    },
    "message": "ok",
    "success": true
}
```

--------------------------------

### GET /api - Retrieve Data Only

Source: https://github.com/soxft/busuanzi/wiki/api

This endpoint retrieves the current site and page view/visitor statistics without incrementing them.

```APIDOC
## GET /api - Retrieve Data Only

### Description
Retrieves the current site and page view/visitor statistics without incrementing them.

### Method
GET

### Endpoint
/api

### Parameters
#### Header Parameters
- **x-bsz-referer** (string) - Optional - none
- **Authorization** (string) - Optional - Identifies user

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)

#### Response Example
```json
{
    "data": {
        "page_pv": 1,
        "page_uv": 1,
        "site_pv": 1,
        "site_uv": 1
    },
    "message": "ok",
    "success": true
}
```
```

--------------------------------

### Compile Busuanzi from Source

Source: https://github.com/soxft/busuanzi/wiki/install

Steps to clone the repository and build the binary from the Go source code.

```shell
git clone https://github.com/soxft/busuanzi.git && cd busuanzi
```

```shell
go build -o busuanzi main.go
```

```shell
./busuanzi
```

--------------------------------

### Run Busuanzi via Binary

Source: https://github.com/soxft/busuanzi/wiki/install

Commands to download, set permissions, and execute the pre-compiled binary file.

```shell
$ git clone https://github.com/soxft/busuanzi && cd busuanzi

# Choose the binary file suitable for your system version from Releases (from v2.8.0 onwards, all binaries are automatically built by GitHub Actions)
$ wget https://github.com/soxft/busuanzi/releases/download/v2.8.3/busuanzi-linux-amd64-v2.8.3 -O busuanzi

$ chmod +x busuanzi

# Run busuanzi
$ ./busuanzi
```

--------------------------------

### Configure via config.yaml

Source: https://context7.com/soxft/busuanzi/llms.txt

Define all service settings using a YAML configuration file.

```yaml
Web:
  Address: 0.0.0.0:8080       # Listen address
  Cors: "https://example.com" # CORS allowed origins (comma-separated)
  Debug: false                 # Enable debug mode
  Log: true                    # Enable request logging

Redis:
  Address: redis:6379          # Redis server address
  Password: ""                 # Redis password (if required)
  Database: 0                  # Redis database number
  TLS: false                   # Enable TLS for Redis connection
  Prefix: bsz                  # Key prefix for all Redis keys
  MaxIdle: 25                  # Maximum idle connections
  MaxActive: 100               # Maximum active connections
  MinIdle: 25                  # Minimum idle connections
  MaxRetries: 3                # Maximum retry attempts

Bsz:
  Expire: 0                    # Data expiration (0 = never)
  Secret: "your-secret-key"    # JWT signing key
  Encrypt: "MD516"             # Hash algorithm: MD516 or MD532
  PathStyle: true              # Path style: true (new) or false (legacy)
```

--------------------------------

### Migrate Data from Original Busuanzi

Source: https://context7.com/soxft/busuanzi/llms.txt

Clone and execute the busuanzi-sync tool to import data from the legacy busuanzi.ibruce.info service.

```bash
# Clone the migration tool
git clone https://github.com/soxft/busuanzi-sync
cd busuanzi-sync

# Configure and run migration
# Follow instructions in the repository README
```

--------------------------------

### Configure Self-Hosted API

Source: https://context7.com/soxft/busuanzi/llms.txt

Point the SDK to a custom Busuanzi deployment.

```html
<!-- Point to your self-hosted API -->
<script defer
    data-api="https://your-busuanzi-server.com/api"
    src="https://your-busuanzi-server.com/js">
</script>

<p>Page Views: <span id="busuanzi_page_pv"></span></p>
<p>Unique Visitors: <span id="busuanzi_page_uv"></span></p>
```

--------------------------------

### Use Custom Tag Prefix

Source: https://context7.com/soxft/busuanzi/llms.txt

Configure a custom prefix for compatibility with existing implementations.

```html
<!-- Original busuanzi compatibility mode -->
<script defer data-prefix="busuanzi_value" src="https://busuanzi.9420.ltd/js"></script>

<!-- Use the original busuanzi ID format -->
<span id="busuanzi_value_page_pv"></span>
<span id="busuanzi_value_site_pv"></span>
```

--------------------------------

### Integrate Busuanzi JavaScript SDK

Source: https://context7.com/soxft/busuanzi/llms.txt

Basic implementation to display page and site statistics.

```html
<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
    <!-- Include Busuanzi script -->
    <script defer src="https://busuanzi.9420.ltd/js"></script>
</head>
<body>
    <div class="stats">
        <!-- Page-level statistics -->
        <p>Page Views: <span id="busuanzi_page_pv"></span></p>
        <p>Page Visitors: <span id="busuanzi_page_uv"></span></p>

        <!-- Site-level statistics -->
        <p>Total Site Views: <span id="busuanzi_site_pv"></span></p>
        <p>Total Site Visitors: <span id="busuanzi_site_uv"></span></p>
    </div>
</body>
</html>
```

--------------------------------

### Data Migration - Between Busuanzi Versions

Source: https://context7.com/soxft/busuanzi/llms.txt

Instructions for migrating data between different Busuanzi versions (e.g., 2.5.x-2.7.x to 2.8.x) using the transfer tool.

```APIDOC
## Data Migration - Between Busuanzi Versions

### Description
Migrate data from Busuanzi versions 2.5.x-2.7.x to version 2.8.x using the `busuanzi-transfer` tool.

### Steps
1. **Clone the transfer tool:**
   ```bash
   git clone https://github.com/soxft/busuanzi-transfer
   cd busuanzi-transfer
   ```
2. **Configure source and destination Redis:**
   Set up the connection details for both the source and destination Redis instances as required by the tool.
3. **Run migration:**
   Execute the migration process following the instructions outlined in the `busuanzi-transfer` repository's README file.
```

--------------------------------

### Integrate Legacy JSONP

Source: https://context7.com/soxft/busuanzi/llms.txt

Use the JSONP endpoint for cross-origin script loading in legacy environments.

```html
<!-- Legacy JSONP integration -->
<script>
function handleBusuanziData(data) {
    document.getElementById('pv').textContent = data.site_pv;
    document.getElementById('uv').textContent = data.site_uv;
}
</script>
<script src="https://busuanzi.9420.ltd/jsonp?callback=handleBusuanziData"></script>
```

```bash
curl "https://busuanzi.9420.ltd/jsonp?callback=myCallback" \
    -H "Referer: https://example.com/"
```

--------------------------------

### Query Page Statistics in Redis

Source: https://context7.com/soxft/busuanzi/llms.txt

Use PFCOUNT for unique visitor counts via HyperLogLog and ZRANGE for retrieving page view scores.

```redis
PFCOUNT bsz:page_uv:a1b2c3d4e5f6g7h8:b2c3d4e5f6g7h8i9
```

```redis
ZRANGE bsz:page_pv:a1b2c3d4e5f6g7h8 0 -1 WITHSCORES
```

--------------------------------

### Configure Tag Prefix

Source: https://github.com/soxft/busuanzi/wiki/usage

Use the data-prefix attribute to maintain compatibility with original Busuanzi HTML IDs.

```html
<script defer data-prefix="busuanzi_value" src="https://busuanzi.9420.ltd/js"></script>
```

--------------------------------

### Deploy Busuanzi with Docker Compose

Source: https://context7.com/soxft/busuanzi/llms.txt

Use this configuration to deploy the Busuanzi service alongside a Redis instance.

```yaml
# docker-compose.yaml
version: "3.8"

services:
  redis:
    image: "redis:alpine"
    volumes:
      - ./data/redis:/data

  bsz:
    image: "xcsoft/busuanzi:latest"
    ports:
      - "8080:8080"
    links:
      - redis
    depends_on:
      - redis
    environment:
      WEB_LOG: true
      WEB_DEBUG: false
      WEB_CORS: "*"
      BSZ_EXPIRE: 0                    # Data expiration in seconds (0 = never expires)
      BSZ_SECRET: "your-secret-key"    # JWT signing key - use random string
      API_SERVER: https://your-domain.com
      REDIS_ADDRESS: redis:6379
      BSZ_PATHSTYLE: true
      BSZ_ENCRYPT: MD516
```

--------------------------------

### Migrate Between Busuanzi Versions

Source: https://context7.com/soxft/busuanzi/llms.txt

Use the busuanzi-transfer tool to migrate data from versions 2.5.x-2.7.x to 2.8.x.

```bash
# Clone the transfer tool
git clone https://github.com/soxft/busuanzi-transfer
cd busuanzi-transfer

# Configure source and destination Redis
# Run migration following repository instructions
```

--------------------------------

### List all pages for a site

Source: https://context7.com/soxft/busuanzi/llms.txt

Retrieves a list of all pages tracked for a given site, along with their respective page view counts.

```APIDOC
## GET /api/site_pages

### Description
Retrieves a list of all pages tracked for a given site, along with their respective page view counts.

### Method
GET

### Endpoint
`/api/site_pages`

### Parameters
#### Query Parameters
- **key_prefix** (string) - Required - The prefix for the page view keys. Format: `bsz:page_pv:{md5(host)}`

### Response
#### Success Response (200)
- **pages** (array) - An array of objects, where each object contains the page path and its view count.
  - **path** (string) - The path of the page.
  - **views** (integer) - The total number of views for the page.

#### Response Example
```json
{
  "pages": [
    {
      "path": "/index.html",
      "views": 1500
    },
    {
      "path": "/about.html",
      "views": 300
    }
  ]
}
```
```

--------------------------------

### Data Migration - Original Busuanzi

Source: https://context7.com/soxft/busuanzi/llms.txt

Instructions for migrating data from the original Busuanzi service using the provided migration tool.

```APIDOC
## Data Migration - Original Busuanzi

### Description
Use the `busuanzi-sync` tool to migrate data from the original `busuanzi.ibruce.info` service.

### Steps
1. **Clone the migration tool:**
   ```bash
   git clone https://github.com/soxft/busuanzi-sync
   cd busuanzi-sync
   ```
2. **Configure and run migration:**
   Follow the instructions provided in the `busuanzi-sync` repository's README file for detailed configuration and execution steps.
```

--------------------------------

### Increment and Retrieve Statistics via POST

Source: https://context7.com/soxft/busuanzi/llms.txt

Use this endpoint to increment counters and receive current statistics. Requires a valid referer header and authorization token.

```bash
curl -X POST "https://busuanzi.9420.ltd/api" \
    -H "x-bsz-referer: https://example.com/blog/my-post" \
    -H "Authorization: Bearer <user-identity-token>"
```

--------------------------------

### Configure Custom API Endpoint

Source: https://github.com/soxft/busuanzi/wiki/usage

Use the data-api attribute to point the script to a custom backend API address.

```html
<script defer data-api="https://busuanzi.9420.ltd/api" src="https://busuanzi.9420.ltd/js"></script>
```

--------------------------------

### Perform Health Check

Source: https://context7.com/soxft/busuanzi/llms.txt

Simple endpoint for monitoring and load balancer health checks.

```bash
curl https://busuanzi.9420.ltd/ping
```

--------------------------------

### Configure Display Style

Source: https://github.com/soxft/busuanzi/wiki/usage

Use the data-style attribute to change how numbers are formatted, such as 'short' or 'comma'.

```html
<script defer data-style="short" src="https://busuanzi.9420.ltd/js"></script>
```

--------------------------------

### POST /api

Source: https://context7.com/soxft/busuanzi/llms.txt

Increments visitor counters and returns current statistics.

```APIDOC
## POST /api

### Description
Increments the site and page counters and returns the current statistics.

### Method
POST

### Endpoint
/api

### Parameters
#### Request Headers
- **x-bsz-referer** (string) - Required - The URL of the page being tracked.
- **Authorization** (string) - Required - Bearer <user-identity-token>.

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request.
- **message** (string) - Status message.
- **data** (object) - Statistics object containing site_pv, site_uv, page_pv, and page_uv.

### Response Example
{
    "success": true,
    "message": "ok",
    "data": {
        "site_pv": 15234,
        "site_uv": 8721,
        "page_pv": 142,
        "page_uv": 89
    }
}
```

--------------------------------

### Enable PJAX Support

Source: https://github.com/soxft/busuanzi/wiki/usage

Add the pjax attribute to the script tag to support automatic count updates on sites using PJAX.

```html
<script defer pjax src="https://busuanzi.9420.ltd/js"></script>
```

--------------------------------

### Customize Display Styles

Source: https://context7.com/soxft/busuanzi/llms.txt

Control number formatting using the data-style attribute.

```html
<!-- Short format: 1024 displays as "1k" -->
<script defer data-style="short" src="https://busuanzi.9420.ltd/js"></script>

<!-- Comma-separated: 1024 displays as "1,024" -->
<script defer data-style="comma" src="https://busuanzi.9420.ltd/js"></script>

<!-- Default: Shows full number -->
<script defer data-style="default" src="https://busuanzi.9420.ltd/js"></script>
```

--------------------------------

### Inspect Redis Data

Source: https://context7.com/soxft/busuanzi/llms.txt

Commands to inspect Busuanzi data directly within Redis.

```bash
# Connect to Redis
redis-cli -h localhost -p 6379

# Site-level Page Views (String)
# Key format: {prefix}:site_pv:{md5(host)}
GET bsz:site_pv:a1b2c3d4e5f6g7h8
# Returns: "15234"

# Site-level Unique Visitors (HyperLogLog)
# Key format: {prefix}:site_uv:{md5(host)}
PFCOUNT bsz:site_uv:a1b2c3d4e5f6g7h8
# Returns: (integer) 8721

# Page-level Page Views (Sorted Set)
# Key format: {prefix}:page_pv:{md5(host)}
# Member: {md5(path)}
ZSCORE bsz:page_pv:a1b2c3d4e5f6g7h8 b2c3d4e5f6g7h8i9
# Returns: "142"
```

--------------------------------

### Page-level Unique Visitors (HyperLogLog)

Source: https://context7.com/soxft/busuanzi/llms.txt

Retrieves the count of unique visitors for a specific page using the HyperLogLog data structure.

```APIDOC
## GET /api/page_uv

### Description
Retrieves the count of unique visitors for a specific page using the HyperLogLog data structure.

### Method
GET

### Endpoint
`/api/page_uv`

### Parameters
#### Query Parameters
- **key** (string) - Required - The Redis key for the page's unique visitor count. Format: `{prefix}:page_uv:{md5(host)}:{md5(path)}`

### Response
#### Success Response (200)
- **count** (integer) - The number of unique visitors.

#### Response Example
```json
{
  "count": 89
}
```
```

--------------------------------

### POST /api - Increment and Retrieve Data

Source: https://github.com/soxft/busuanzi/wiki/api

This endpoint increments the site and page view/visitor counts and returns the current statistics.

```APIDOC
## POST /api - Increment and Retrieve Data

### Description
Increments the site and page view/visitor counts and returns the current statistics.

### Method
POST

### Endpoint
/api

### Parameters
#### Header Parameters
- **x-bsz-referer** (string) - Optional - Referrer URL
- **Authorization** (string) - Optional - Identifies user

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **Set-bsz-identity** (string) - Optional - Sets user identity

#### Response Example
```json
{
    "data": {
        "page_pv": 1,
        "page_uv": 1,
        "site_pv": 1,
        "site_uv": 1
    },
    "message": "ok",
    "success": true
}
```
```

--------------------------------

### PUT /api - Submit Data Only

Source: https://github.com/soxft/busuanzi/wiki/api

This endpoint submits data, likely for updating or setting statistics, but does not return content.

```APIDOC
## PUT /api - Submit Data Only

### Description
Submits data, likely for updating or setting statistics, but does not return content.

### Method
PUT

### Endpoint
/api

### Parameters
#### Header Parameters
- **x-bsz-referer** (string) - Optional - none
- **Authorization** (string) - Optional - Identifies user

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (204)

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Increment Statistics via PUT

Source: https://context7.com/soxft/busuanzi/llms.txt

Increment counters without receiving a response body. This is a fire-and-forget operation.

```bash
curl -X PUT "https://busuanzi.9420.ltd/api" \
    -H "x-bsz-referer: https://example.com/blog/my-post" \
    -H "Authorization: Bearer <user-identity-token>"
```

--------------------------------

### PUT /api

Source: https://context7.com/soxft/busuanzi/llms.txt

Increments counters without returning a response body.

```APIDOC
## PUT /api

### Description
Increments counters without receiving a response body (fire-and-forget).

### Method
PUT

### Endpoint
/api

### Parameters
#### Request Headers
- **x-bsz-referer** (string) - Required - The URL of the page being tracked.
- **Authorization** (string) - Required - Bearer <user-identity-token>.

### Response
#### Success Response (204)
- No content returned.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.