opentrace 1.2.7

Official Python SDK for OpenTrace Analytics (https://github.com/del4pp/opentrace)

OpenTrace Python SDK

Official Python client for OpenTrace Analytics. Built for performance, privacy, and full marketing attribution.

Installation

pip install opentrace

Quick Start (Telegram Bot)

from opentrace import OpenTrace

ot = OpenTrace(host="https://your-analytics.com", project_id="ot_web_123")

# Track sub with auto-UTM resolution
ot.track_event(
    name="bot_start",
    bot_param=command.args, # Extracts metadata from ?start=utm_XXXX
    session_id=ot.get_user_hash(user_id) # Persistent privacy-first ID
)

User Identity & Persistence

To track a user’s journey over time (User Timeline), use a consistent session_id. For Telegram bots, we recommend hashing the User ID:

# Generate a short anonymous hash (e.g. 'a1b2c3d4e5f6')
user_hash = ot.get_user_hash(message.from_user.id)

# Every event sent with this hash will be linked in the dashboard
ot.track_event("purchase", session_id=user_hash, payload={"price": 10})

API Reference

OpenTrace(host, project_id=None, debug=False)

Initialize the client.

• host: URL of your OpenTrace instance.
• project_id: Default Resource UID for all events.
• debug: Enable verbose logging.

---

.track_event(...)

Recommended for Server-side actions and Bots.

Parameter	Type	Description
name	str	Required. Event name.
bot_param	str	The start parameter from Telegram. Auto-resolves UTMs.
session_id	str	Unique user identity for Timeline tracking.
project_id	str	Resource UID (overrides default).
payload	dict	Custom metadata.
utm_source	str	Manual UTM Source.
utm_medium	str	Manual UTM Medium.
utm_campaign	str	Manual UTM Campaign.

---

.get_user_hash(user_id)

Creates a persistent 16-char anonymous hash for a raw ID.

---

.resolve_bot_param(param)

Manually fetch campaign metadata from the server.

---

Technical Features

• Asynchronous Execution: Network requests are handled in background threads.
• Zero Dependencies: Requires only the requests library.
• Privacy First: Tools included to anonymize sensitive IDs before tracking.

License

MIT