mkStats

https://mkstats.mk69.su/wiki
Admin
mkStats is a private statistics API for plugins that tracks metrics and events with anti-abuse...
Tokens:4,592
Snippets:19
Trust Score:4.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### API v1 Handshake Request Example

Source: https://mkstats.mk69.su/wiki/index

Example of a POST request to the /api/v1/handshake endpoint to obtain an install_token. This is the initial step for client integration.

```json
POST /api/v1/handshake
{
  "plugin_id": "my_plugin",
  "version": "1.2.0",
  "client_name": "exteraGram",
  "client_version": "11.12.0",
  "user_hash": "sha256...",
  "device_fingerprint": "sha256_device..."
}
```

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

### API v1 Data Ping Request Example

Source: https://mkstats.mk69.su/wiki/index

Example of a POST request to the /api/v1/data endpoint for activity pinging. Requires a timestamp and optionally a device_fingerprint.

```json
POST /api/v1/data
{
  "plugin_id": "my_plugin",
  "version": "1.2.0",
  "client_name": "exteraGram",
  "client_version": "11.12.0",
  "user_hash": "sha256...",
  "device_fingerprint": "sha256_device...",
  "install_token": "token",
  "timestamp": 1700000000
}
```

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

### API v1 Event Tracking Request Example

Source: https://mkstats.mk69.su/wiki/index

Example of a POST request to the /api/v1/event endpoint for tracking events. Includes event details, count, and timestamp.

```json
POST /api/v1/event
{
  "plugin_id": "my_plugin",
  "version": "1.2.0",
  "client_name": "exteraGram",
  "client_version": "11.12.0",
  "user_hash": "sha256...",
  "device_fingerprint": "sha256_device...",
  "install_token": "token",
  "event": "feature_used",
  "count": 3,
  "timestamp": 1700000000
}
```

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

### Python Client: Event Tracking

Source: https://mkstats.mk69.su/wiki/index

This Python function allows tracking events sent to the mkstats API. It requires the `post_json` function from the handshake example to be available. It sends event name and an optional count, along with other required client details.

```python
# Assumes post_json, plugin_id, plugin_version, client_name, client_version, user_hash, device_fingerprint, install_token are defined from the handshake example.
# def post_json(path, payload):
#     ...

def send_event(event_name, count=1):
    post_json("/event", {
        "plugin_id": plugin_id,
        "version": plugin_version,
        "client_name": client_name,
        "client_version": client_version,
        "user_hash": user_hash,
        "device_fingerprint": device_fingerprint,
        "install_token": install_token,
        "event": event_name,
        "count": count,
        "timestamp": int(time.time()),
    })

# Example usage:
send_event("search_used")
send_event("context_menu_opened", count=5)

```

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

### POST /api/v1/handshake

Source: https://mkstats.mk69.su/wiki/index

Obtain an install_token for your plugin. This endpoint may require solving a Proof-of-Work challenge.

```APIDOC
## POST /api/v1/handshake

### Description
Obtain an install_token for your plugin. This endpoint may require solving a Proof-of-Work challenge.

### Method
POST

### Endpoint
/api/v1/handshake

### Parameters
#### Request Body
- **plugin_id** (string) - Required - Your plugin's unique identifier.
- **version** (string) - Required - The version of your plugin.
- **client_name** (string) - Required - The name of your client application (e.g., "AyuGram", "exteraGram").
- **client_version** (string) - Required - The version of your client application.
- **user_hash** (string) - Required - A hashed representation of the user.
- **device_fingerprint** (string) - Recommended - A unique identifier for the device.

### Request Example
```json
{
  "plugin_id": "my_plugin",
  "version": "1.2.0",
  "client_name": "exteraGram",
  "client_version": "11.12.0",
  "user_hash": "sha256...",
  "device_fingerprint": "sha256_device..."
}
```

### Response
#### Success Response (200)
- **install_token** (string) - The token required for subsequent requests.
- **pow_required** (boolean) - Indicates if a Proof-of-Work challenge is required.
- **challenge** (object) - The Proof-of-Work challenge details (if pow_required is true).

#### Response Example
```json
{
  "install_token": "your_install_token",
  "pow_required": false
}
```
```

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

### POST /api/v1/data

Source: https://mkstats.mk69.su/wiki/index

Send an activity ping to report user activity. Requires an install_token and timestamp.

```APIDOC
## POST /api/v1/data

### Description
Send an activity ping to report user activity. Requires an install_token and timestamp.

### Method
POST

### Endpoint
/api/v1/data

### Parameters
#### Request Body
- **plugin_id** (string) - Required - Your plugin's unique identifier.
- **version** (string) - Required - The version of your plugin.
- **client_name** (string) - Required - The name of your client application.
- **client_version** (string) - Required - The version of your client application.
- **user_hash** (string) - Required - A hashed representation of the user.
- **device_fingerprint** (string) - Recommended - A unique identifier for the device.
- **install_token** (string) - Required - The token obtained from the /handshake endpoint.
- **timestamp** (integer) - Required - The Unix timestamp of the activity.

### Request Example
```json
{
  "plugin_id": "my_plugin",
  "version": "1.2.0",
  "client_name": "exteraGram",
  "client_version": "11.12.0",
  "user_hash": "sha256...",
  "device_fingerprint": "sha256_device...",
  "install_token": "token",
  "timestamp": 1700000000
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

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

### POST /api/v1/event

Source: https://mkstats.mk69.su/wiki/index

Send custom events with counts. Requires an install_token, event name, count, and timestamp.

```APIDOC
## POST /api/v1/event

### Description
Send custom events with counts. Requires an install_token, event name, count, and timestamp.

### Method
POST

### Endpoint
/api/v1/event

### Parameters
#### Request Body
- **plugin_id** (string) - Required - Your plugin's unique identifier.
- **version** (string) - Required - The version of your plugin.
- **client_name** (string) - Required - The name of your client application.
- **client_version** (string) - Required - The version of your client application.
- **user_hash** (string) - Required - A hashed representation of the user.
- **device_fingerprint** (string) - Recommended - A unique identifier for the device.
- **install_token** (string) - Required - The token obtained from the /handshake endpoint.
- **event** (string) - Required - The name of the event.
- **count** (integer) - Required - The number of occurrences for this event (1-1000).
- **timestamp** (integer) - Required - The Unix timestamp of the event.

### Request Example
```json
{
  "plugin_id": "my_plugin",
  "version": "1.2.0",
  "client_name": "exteraGram",
  "client_version": "11.12.0",
  "user_hash": "sha256...",
  "device_fingerprint": "sha256_device...",
  "install_token": "token",
  "event": "feature_used",
  "count": 3,
  "timestamp": 1700000000
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

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

### Python Client: Handshake and Ping with Proof-of-Work

Source: https://mkstats.mk69.su/wiki/index

This Python code demonstrates a minimal client for mkstats API. It handles the initial handshake, including solving a Proof-of-Work challenge if required, and then sends a data ping. Dependencies include hashlib, json, time, and urllib.request.

```python
import hashlib
import json
import time
import urllib.request

API_BASE = "https://mkstats.mk69.su/api/v1"
POW_SOLVE_SECONDS = 6

def post_json(path, payload):
    data = json.dumps(payload).encode("utf-8")
    req = urllib.request.Request(
        f"{API_BASE}{path}",
        data=data,
        headers={"Content-Type": "application/json"},
    )
    with urllib.request.urlopen(req, timeout=10) as resp:
        return json.loads(resp.read().decode("utf-8"))

def build_user_hash(device_id, plugin_id):
    payload = f"{device_id}:{plugin_id}:mkstats:v1"
    return hashlib.sha256(payload.encode("utf-8")).hexdigest()

def build_device_fingerprint(device_id):
    payload = f"{device_id}:mkstats:device:v1"
    return hashlib.sha256(payload.encode("utf-8")).hexdigest()

def solve_pow(challenge, difficulty, max_seconds=POW_SOLVE_SECONDS):
    difficulty = max(1, int(difficulty or 0))
    deadline = time.time() + max_seconds
    nonce = 0
    prefix = "0" * difficulty
    while time.time() < deadline:
        candidate = format(nonce, "x")
        digest = hashlib.sha256(f"{challenge}:{candidate}".encode("utf-8")).hexdigest()
        if digest.startswith(prefix):
            return candidate
        nonce += 1
    return None

def handshake_with_pow(payload):
    resp = post_json("/handshake", payload)
    if resp.get("install_token"):
        return resp
    if resp.get("pow_required") and resp.get("pow_challenge"):
        difficulty = int(resp.get("pow_difficulty") or 0)
        nonce = solve_pow(resp["pow_challenge"], difficulty)
        if nonce:
            payload = dict(payload)
            payload["pow_challenge"] = resp["pow_challenge"]
            payload["pow_nonce"] = nonce
            resp = post_json("/handshake", payload)
    return resp

# Example usage (assuming device_id, plugin_id, plugin_version, client_name, client_version are defined)
# user_hash = build_user_hash(device_id, plugin_id)
# device_fingerprint = build_device_fingerprint(device_id)

# payload = {
#     "plugin_id": plugin_id,
#     "version": plugin_version,
#     "client_name": client_name,
#     "client_version": client_version,
#     "user_hash": user_hash,
#     "device_fingerprint": device_fingerprint,
# }

# handshake = handshake_with_pow(payload)
# install_token = handshake["install_token"]

# post_json("/data", {
#     "plugin_id": plugin_id,
#     "version": plugin_version,
#     "client_name": client_name,
#     "client_version": client_version,
#     "user_hash": user_hash,
#     "device_fingerprint": device_fingerprint,
#     "install_token": install_token,
#     "timestamp": int(time.time()),
# })

```

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

### Handshake and Data Submission API

Source: https://mkstats.mk69.su/wiki/index

This section details the handshake process, which may involve Proof-of-Work, and subsequent data submission.

```APIDOC
## POST /api/v1/handshake

### Description
Initiates a connection with the MKStats server. May require solving a Proof-of-Work challenge.

### Method
POST

### Endpoint
/api/v1/handshake

### Parameters
#### Request Body
- **plugin_id** (string) - Required - Identifier for the plugin.
- **version** (string) - Required - Version of the plugin.
- **client_name** (string) - Required - Name of the client application.
- **client_version** (string) - Required - Version of the client application.
- **user_hash** (string) - Required - A hash representing the user, generated from device_id and plugin_id.
- **device_fingerprint** (string) - Required - A fingerprint for the device.
- **pow_challenge** (string) - Optional - The challenge string provided by the server if PoW is required.
- **pow_nonce** (string) - Optional - The solution (nonce) to the PoW challenge.

### Request Example
```json
{
  "plugin_id": "example_plugin",
  "version": "1.0.0",
  "client_name": "exampleClient",
  "client_version": "1.0.0",
  "user_hash": "a1b2c3d4e5f6...",
  "device_fingerprint": "f1e2d3c4b5a6..."
}
```

### Response
#### Success Response (200)
- **install_token** (string) - A token for subsequent authenticated requests.
- **pow_required** (boolean) - Indicates if Proof-of-Work is required.
- **pow_challenge** (string) - The challenge string for Proof-of-Work.
- **pow_difficulty** (integer) - The difficulty level for Proof-of-Work.

#### Response Example
```json
{
  "install_token": "your_install_token_here"
}
```

## POST /api/v1/data

### Description
Submits collected data to the MKStats server.

### Method
POST

### Endpoint
/api/v1/data

### Parameters
#### Request Body
- **plugin_id** (string) - Required - Identifier for the plugin.
- **version** (string) - Required - Version of the plugin.
- **client_name** (string) - Required - Name of the client application.
- **client_version** (string) - Required - Version of the client application.
- **user_hash** (string) - Required - A hash representing the user.
- **device_fingerprint** (string) - Required - A fingerprint for the device.
- **install_token** (string) - Required - The token obtained from the handshake.
- **timestamp** (integer) - Required - Unix timestamp of the data submission.

### Request Example
```json
{
  "plugin_id": "example_plugin",
  "version": "1.0.0",
  "client_name": "exampleClient",
  "client_version": "1.0.0",
  "user_hash": "a1b2c3d4e5f6...",
  "device_fingerprint": "f1e2d3c4b5a6...",
  "install_token": "your_install_token_here",
  "timestamp": 1678886400
}
```

### Response
#### Success Response (200)
(No specific fields mentioned, typically an acknowledgment of receipt)

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### Event Tracking API

Source: https://mkstats.mk69.su/wiki/index

Endpoint for tracking specific events occurring within the client application.

```APIDOC
## POST /api/v1/event

### Description
Logs a specific event with an optional count.

### Method
POST

### Endpoint
/api/v1/event

### Parameters
#### Request Body
- **plugin_id** (string) - Required - Identifier for the plugin.
- **version** (string) - Required - Version of the plugin.
- **client_name** (string) - Required - Name of the client application.
- **client_version** (string) - Required - Version of the client application.
- **user_hash** (string) - Required - A hash representing the user.
- **device_fingerprint** (string) - Required - A fingerprint for the device.
- **install_token** (string) - Required - The token obtained from the handshake.
- **event** (string) - Required - The name of the event being tracked.
- **count** (integer) - Optional - The number of times the event occurred (defaults to 1).
- **timestamp** (integer) - Required - Unix timestamp of the event.

### Request Example
```json
{
  "plugin_id": "example_plugin",
  "version": "1.0.0",
  "client_name": "exampleClient",
  "client_version": "1.0.0",
  "user_hash": "a1b2c3d4e5f6...",
  "device_fingerprint": "f1e2d3c4b5a6...",
  "install_token": "your_install_token_here",
  "event": "search_used",
  "count": 1,
  "timestamp": 1678886400
}
```

### Response
#### Success Response (200)
(No specific fields mentioned, typically an acknowledgment of receipt)

#### Response Example
```json
{
  "status": "success"
}
```
```
Tokens:
Raw