Event Import Guide

A guide to constructing JSON payloads for importing events, properties, categories, labels, and sources into your EventPanel workspace.

Overview

EventPanel allows you to import analytics events programmatically using JSON. You can import events along with their properties, categories, labels, and sources in a single operation. The system automatically handles duplicate detection and creates relationships between entities.

JSON Structure

The import payload is an array of event objects. Each event can include:

• Basic event information: name, description, screenshots
• Properties: Parameters that can be tracked with the event
• Categories: Groups for organizing related events
• Labels: Visual tags for filtering and organization
• Sources: Platforms where the event is used (iOS, Android, Web)

Basic Event Structure

Here's the basic structure of an event object:

{
  "externalId": "optional_external_id",
  "name": "Event Name",
  "description": "Optional description",
  "screenshots": ["https://example.com/screenshot.png"],
  "properties": [],
  "categories": [],
  "labels": [],
  "sources": []
}

Required Fields

• name (string) - The event name

Optional Fields

• externalId (string) - External identifier for duplicate prevention
• description (string) - Event description
• screenshots (string[]) - Array of screenshot URLs
• properties (array) - Event properties
• categories (array) - Event categories
• labels (array) - Event labels
• sources (string[]) - Array of source names

Properties

Properties define the parameters that can be tracked with an event.

Property Structure

{
  "externalId": "optional_external_id",
  "name": "Property Name",
  "description": "Optional description",
  "type": "STRING",
  "isRequired": true,
  "values": ["Option 1", "Option 2"]
}

Required Fields

• name (string) - Property name
• type (string) - Property type (see types below)
• isRequired (boolean) - Whether the property is required

Optional Fields

• externalId (string) - External identifier
• description (string) - Property description
• values (string[] | null) - Predefined values (only for STRING type)

Property Types

Available property types:

• STRING - Text values
• STRING_LIST - Array of text values
• INTEGER - Whole numbers
• INTEGER_LIST - Array of whole numbers
• FLOAT - Decimal numbers
• FLOAT_LIST - Array of decimal numbers
• BOOLEAN - True/false values
• BOOLEAN_LIST - Array of boolean values
• DATE - Date values
• DATE_LIST - Array of date values
• OBJECT - Complex object structures
• OBJECT_LIST - Array of object structures

Note: Only STRING type properties support predefined values. The values field is ignored for other property types.

Property Examples

Required string property:

{
  "name": "Order ID",
  "type": "STRING",
  "isRequired": true
}

Optional float property:

{
  "name": "Amount",
  "description": "Purchase amount",
  "type": "FLOAT",
  "isRequired": false
}

String property with predefined values:

{
  "name": "Currency",
  "type": "STRING",
  "isRequired": true,
  "values": ["USD", "EUR", "GBP", "JPY"]
}

List property:

{
  "name": "Product IDs",
  "description": "List of purchased product identifiers",
  "type": "STRING_LIST",
  "isRequired": false
}

Categories

Categories group related events together.

Category Structure

{
  "externalId": "optional_external_id",
  "name": "Category Name",
  "description": "Optional description"
}

Required Fields

• name (string) - Category name

Optional Fields

• externalId (string) - External identifier
• description (string) - Category description

Category Example

{
  "externalId": "cat_ecommerce",
  "name": "E-Commerce",
  "description": "E-commerce related events"
}

Labels

Labels provide visual organization and filtering.

Label Structure

{
  "name": "Label Name",
  "description": "Optional description",
  "color": "#FF5733"
}

Required Fields

• name (string) - Label name
• color (string) - Hex color code (e.g., "#FF5733")

Optional Fields

• description (string) - Label description

Label Example

{
  "name": "Revenue",
  "description": "Events that generate revenue",
  "color": "#00C853"
}

Color Format: Must be a valid hex color code (e.g., "#FF5733", "#00C853").

Sources

Sources specify which platforms use the event.

Source Structure

Sources are simply an array of source names:

{
  "sources": ["iOS", "Android", "Web"]
}

Important: Sources must already exist in your workspace. If a source name doesn't exist, the event will be created without that source link. Create sources separately before importing events.

Complete Examples

Example 1: E-Commerce Checkout Event

[
  {
    "externalId": "evt_checkout_completed",
    "name": "Checkout Completed",
    "description": "Fired when a user completes a purchase",
    "screenshots": [
      "https://example.com/screenshots/checkout-1.png"
    ],
    "properties": [
      {
        "externalId": "prop_order_id",
        "name": "Order ID",
        "description": "Unique identifier for the order",
        "type": "STRING",
        "isRequired": true
      },
      {
        "externalId": "prop_amount",
        "name": "Amount",
        "description": "Total purchase amount",
        "type": "FLOAT",
        "isRequired": true
      },
      {
        "externalId": "prop_currency",
        "name": "Currency",
        "description": "Currency code",
        "type": "STRING",
        "isRequired": true,
        "values": ["USD", "EUR", "GBP"]
      },
      {
        "externalId": "prop_product_ids",
        "name": "Product IDs",
        "description": "List of purchased product identifiers",
        "type": "STRING_LIST",
        "isRequired": false
      }
    ],
    "categories": [
      {
        "externalId": "cat_ecommerce",
        "name": "E-Commerce",
        "description": "E-commerce related events"
      }
    ],
    "labels": [
      {
        "name": "Revenue",
        "description": "Events that generate revenue",
        "color": "#00C853"
      },
      {
        "name": "Critical",
        "description": "Critical business events",
        "color": "#FF1744"
      }
    ],
    "sources": ["iOS", "Android", "Web"]
  }
]

Example 2: Simple Product View Event

[
  {
    "name": "Product Viewed",
    "description": "Fired when a user views a product detail page",
    "properties": [
      {
        "name": "Product ID",
        "description": "Identifier of the viewed product",
        "type": "STRING",
        "isRequired": true
      },
      {
        "name": "Category",
        "description": "Product category",
        "type": "STRING",
        "isRequired": false,
        "values": ["Electronics", "Clothing", "Books", "Home"]
      }
    ],
    "categories": [
      {
        "name": "E-Commerce"
      }
    ],
    "sources": ["Web"]
  }
]

Example 3: User Authentication Event

[
  {
    "externalId": "evt_user_signed_in",
    "name": "User Signed In",
    "description": "Fired when a user successfully signs in",
    "properties": [
      {
        "name": "User ID",
        "type": "STRING",
        "isRequired": true
      },
      {
        "name": "Sign In Method",
        "type": "STRING",
        "isRequired": true,
        "values": ["Email", "Google", "Apple", "Facebook"]
      },
      {
        "name": "Is First Time",
        "type": "BOOLEAN",
        "isRequired": false
      }
    ],
    "categories": [
      {
        "name": "Authentication"
      }
    ],
    "labels": [
      {
        "name": "User Activity",
        "color": "#2196F3"
      }
    ],
    "sources": ["iOS", "Android"]
  }
]

Best Practices

Use External IDs

Always provide externalId fields when available. This helps prevent duplicate creation and enables idempotent import operations:

{
  "externalId": "evt_checkout_completed",
  "name": "Checkout Completed"
}

Organize with Categories

Use categories to group related events:

{
  "categories": [
    {
      "externalId": "cat_ecommerce",
      "name": "E-Commerce"
    }
  ]
}

Mark Required Properties

Clearly distinguish between required and optional properties:

{
  "properties": [
    {
      "name": "Order ID",
      "type": "STRING",
      "isRequired": true
    },
    {
      "name": "Discount Code",
      "type": "STRING",
      "isRequired": false
    }
  ]
}

Use Predefined Values for Enums

For properties with a limited set of values, use the values field:

{
  "name": "Payment Method",
  "type": "STRING",
  "isRequired": true,
  "values": ["Credit Card", "PayPal", "Apple Pay", "Google Pay"]
}

Consistent Source Naming

Use consistent source names across your workspace:

{
  "sources": ["iOS", "Android", "Web"]
}

Common Issues

Duplicate Entities

The import system automatically handles duplicates:

• Properties, categories, and labels are matched by externalId or name
• If a match is found, the existing entity is reused
• If no match is found, a new entity is created

Missing Sources

If a source name doesn't exist:

• The source won't be created automatically
• The event will be created without that source link
• Create sources separately before importing events

Invalid Property Values

• Only STRING type properties support predefined values
• The values field is ignored for other property types
• Set values to null or omit it for non-STRING properties

Invalid Label Colors

Label colors must be valid hex codes:

• ✅ Valid: "#FF5733", "#00C853"
• ❌ Invalid: "red", "rgb(255, 87, 51)"