{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://www.topadroi.com/schema/mobile-event-v1.json",
  "title": "topadroi Mobile Events API — request schema v1",
  "description": "Body for POST /v1/mobile/events. Either a single event or { events: [...] }.",
  "type": "object",
  "oneOf": [
    { "$ref": "#/definitions/batch" },
    { "$ref": "#/definitions/event" }
  ],
  "definitions": {
    "batch": {
      "type": "object",
      "required": ["events"],
      "properties": {
        "events": {
          "type": "array",
          "minItems": 1,
          "maxItems": 100,
          "items": { "$ref": "#/definitions/event" }
        }
      }
    },
    "event": {
      "type": "object",
      "required": ["site_id", "event_name", "event_id", "event_time"],
      "properties": {
        "site_id": { "type": "string", "maxLength": 100 },
        "event_name": { "type": "string", "maxLength": 100, "examples": ["Purchase", "AddToCart", "CompleteRegistration", "AppOpen"] },
        "event_id": { "type": "string", "maxLength": 100, "description": "Unique UUID; dedup key. Persist client-side so retries reuse it." },
        "event_time": { "type": "integer", "description": "Unix seconds. Clamped server-side if implausible." },
        "user_data": { "$ref": "#/definitions/user_data" },
        "event_data": { "$ref": "#/definitions/event_data" },
        "app_metadata": { "$ref": "#/definitions/app_metadata" },
        "consent": { "$ref": "#/definitions/consent" }
      }
    },
    "user_data": {
      "type": "object",
      "description": "Send what you have. em/ph normalized + hashed server-side (send cleartext over TLS, do NOT pre-hash). Device IDs routed per-platform automatically.",
      "properties": {
        "em": { "type": "string", "description": "Email" },
        "ph": { "type": "string", "description": "Phone, E.164 preferred" },
        "external_id": { "type": "string", "description": "Your own user/CRM id" },
        "idfa": { "type": "string", "description": "iOS Advertising ID (only when ATT authorized)" },
        "gaid": { "type": "string", "description": "Android Advertising ID" },
        "idfv": { "type": "string", "description": "iOS Identifier for Vendor" },
        "app_user_id": { "type": "string" },
        "anon_id": { "type": "string" },
        "fn": { "type": "string" }, "ln": { "type": "string" },
        "ct": { "type": "string" }, "st": { "type": "string" },
        "zp": { "type": "string" }, "country": { "type": "string" },
        "ge": { "type": "string" }, "db": { "type": "string" },
        "fbp": { "type": "string" }, "fbc": { "type": "string" },
        "gclid": { "type": "string" }, "ttclid": { "type": "string" }
      }
    },
    "event_data": {
      "type": "object",
      "properties": {
        "value": { "type": "number" },
        "currency": { "type": "string" },
        "content_ids": { "type": "array", "items": { "type": "string" } },
        "content_type": { "type": "string" },
        "order_id": { "type": "string" },
        "num_items": { "type": "integer" },
        "contents": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "quantity": { "type": "integer" },
              "item_price": { "type": "number" }
            }
          }
        }
      }
    },
    "app_metadata": {
      "type": "object",
      "description": "platform is important: routes device id to each platform's correct iOS/Android field.",
      "properties": {
        "platform": { "type": "string", "enum": ["ios", "android"] },
        "app_version": { "type": "string" },
        "os_version": { "type": "string" },
        "device_model": { "type": "string" },
        "locale": { "type": "string" },
        "timezone": { "type": "string", "description": "IANA name, e.g. Asia/Taipei" },
        "network_type": { "type": "string", "enum": ["wifi", "cellular", "unknown"] },
        "install_referrer": { "type": "string", "description": "Android Play Install Referrer" },
        "asa_attribution": { "type": "string", "description": "iOS Apple Search Ads token" }
      }
    },
    "consent": {
      "type": "object",
      "properties": {
        "ad_tracking": { "type": "boolean", "description": "iOS: from ATT status. Drives advertiser_tracking_enabled." },
        "analytics": { "type": "boolean" }
      }
    }
  }
}