A-Track Python SDK

Analytics SDK for Python services and backend applications.

Features

• initialization with a public_key
• automatic uuid generation when one is not provided
• support for your own uuid during initialization
• user attribute create/update flow
• user event delivery
• in-memory storage by default, with pluggable storage support
• Python-friendly request context helpers
• no mandatory external dependencies

Geo-based API routing

The SDK sends requests to:

• https://api.a-track.io by default
• https://<geo>.api.a-track.io when geo is provided

Authentication/project routing header:

• x-a-track-key: <public_key>

Default endpoints:

• /init
• /attributes
• /event

Available geo values:

• nyc
• sfo
• ams
• sgp
• lon
• fra
• tor
• blr
• syd
• atl
• ric

Basic usage

from a_track_sdk import create_a_track_sdk

sdk = create_a_track_sdk(
    public_key="pub_xxxxx",
    geo="fra",
)

sdk.init({
    "user": {
        "uuid": "server-user-42",
    }
})

sdk.track({
    "event": "order_created",
    "attributes": {
        "order_id": "ord_123",
        "total": 149,
    },
})

Generated uuid and later tracking

You can initialize without passing a user uuid, let the SDK generate one, and then read it back:

result = sdk.init()
uuid_from_init = result["uuid"]
current_user = sdk.get_user()
same_uuid = current_user["uuid"] if current_user else None

Later, anywhere else in your code, you can track an event with that explicit uuid:

sdk.track({
    "uuid": uuid_from_init,
    "event": "job_processed",
    "attributes": {
        "source": "worker",
    },
})

Building init payload from request data

from a_track_sdk import build_python_init_payload, create_a_track_sdk

sdk = create_a_track_sdk(public_key="pub_xxxxx")

sdk.init(build_python_init_payload(
    url="/pricing?source=google",
    referer="https://google.com",
    ip_address="134.122.17.144",
    user_agent=request.headers.get("User-Agent"),
    locale="en-US",
    timezone="America/New_York",
    uuid="crm-user-42",
    user_attributes={
        "plan": "pro",
    },
))

Updating user attributes

Merge:

sdk.set_attributes({
    "plan": "business",
    "seats": 12,
})

Replace:

sdk.set_attributes(
    {
        "plan": "free",
    },
    replace=True,
)

set_attributes() sends data to /attributes.

Attributes can also be included during init() if you want to initialize the user and attach attributes in the same call.

You can also read the current initialized user at any time:

current_user = sdk.get_user()

Events

sdk.track({
    "event": "invoice_paid",
    "attributes": {
        "invoice_id": "inv_123",
        "amount": 499,
    },
})

The SDK sends at least:

• sdkVersion
• uuid
• event
• attributes
• timestamp
• context

Suggested backend contract

POST /init

{
  "sdkVersion": "0.1.0",
  "uuid": "0d54...",
  "isNewUser": true,
  "mode": "merge",
  "context": {},
  "attributes": {},
  "profile": {}
}

POST /attributes

{
  "sdkVersion": "0.1.0",
  "uuid": "0d54...",
  "mode": "merge",
  "attributes": {
    "plan": "business"
  },
  "profile": {}
}

POST /event

{
  "sdkVersion": "0.1.0",
  "uuid": "0d54...",
  "event": "invoice_paid",
  "attributes": {},
  "timestamp": "2026-04-08T12:00:00.000Z",
  "context": {}
}

Header example:

x-a-track-key: pub_xxxxx