Skip to main content

​
How to Send a Custom Event

JSONObject eventProperties = new JSONObject();
eventProperties.put("orderId", "P450");
eventProperties.put("productName", "Headphones"); // Optional
eventProperties.put("currency", "USD");           // Optional
eventProperties.put("amount", 249.99);            // Optional

// You can add more properties like userId, paymentMethod, etc.
Analytics.Companion.setCustomEvent("purchaseCompleted", eventProperties);
Data TypeExample KeyExample Value
String”productName""Headphones”
Int / Long”quantity”2
Boolean”isNewUser”true
Double / Float”price”199.99
JSONArray”tags”[“electronics”, “audio”]
JSONObject”userInfo”{ “id”: “u123”, “age”: 28 }
null”discount”null
(Not allowed. Avoid using null in eventProperties. Use "0", "unknown", or remove the key.)
📝 Note
Only primitive types, JSONArray, and JSONObject are allowed inside eventProperties.
Avoid passing complex objects or custom class instances directly. Convert them to JSON first.

💡 All properties must be JSON-serializable. Also, avoid passing null values.

​
Example of Custom Event Payload: Supported Data Types

Understand the types of data you can pass inside eventProperties and how to structure complex objects. 
val eventProps = JSONObject().apply {
    put("event", "add_to_cart") // String
    put("productId", "PRD-9021") // String
    put("productName", "Bluetooth Speaker X10") // String
    put("price", 129.99) // Number (Double)
    put("currency", "USD") // String
    put("quantity", 2) // Number (Int)
    put("category", "Audio Equipment") // String
    put("isInStock", true) // Boolean

    val tags = JSONArray().apply {
        put("bluetooth") // String
        put("portable")  // String
        put("bass")      // String
    }
    put("tags", tags) // Array[String]

    val userInfo = JSONObject().apply {
        put("userId", "user_456789") // String
        put("membershipLevel", "Platinum") // String
    }
    put("userInfo", userInfo) // Object
}

// Trigger the event with all custom properties
Analytics.Companion.setCustomEvent("ProductAddedToCart", eventProps)
Follow these guidelines to help users name, structure, and send custom events effectively.
  1. Naming Guidelines
    • Use camelCase or snake_case for event names (e.g., purchaseCompleted, user_logged_in)
    • Keep names short and descriptive
    • Avoid spaces or special characters
  2. Event Structure
    • Use consistent keys (e.g., always use "productId")
    • Include only relevant attributes
    • Skip redundant or unused properties
  3. Avoid These Mistakes
    • Don’t send raw classes — always serialize to JSON
    • Avoid high-cardinality keys (e.g., UUIDs, timestamps)
    • Never pass null — use "unknown" or remove the key