Event Properties

Event properties allow you to add structured, typed data to your events. Properties must match your dashboard schema exactly, or the event will be rejected.

Basic Usage

Enrichment

Common Patterns

Supported Types

EventProperties can contain the following types:

Type	Kotlin/Java Type	Example
Boolean	`Boolean`	`true`, `false`
Integer	`Int`, `Long`	`42`, `1000L`
String	`String`	`"Technology"`
Float	`Float`, `Double`	`99.99`, `3.14f`
DateTime	`java.util.Date`	`Date()`
Nested Object	`EventProperties`	Nested properties
List	`List<T>`	List of any supported type

Nullable Values

The API accepts nullable types. Properties with null values will be automatically filtered and not sent with the event.

EventProperties.from(
    "optional_field" to null  // This will be filtered out automatically
)

Creating Event Properties

import com.permutive.android.EventProperties

val properties = EventProperties.from(
    "article_id" to 12345,
    "title" to "Breaking News",
    "category" to "Technology",
    "price" to 9.99,
    "is_premium" to true,
    "published_at" to Date(),
    "tags" to listOf("tech", "mobile", "android")
)

import com.permutive.android.EventProperties;

EventProperties properties = new EventProperties.Builder()
    .with("article_id", 12345)
    .with("title", "Breaking News")
    .with("category", "Technology")
    .with("price", 9.99)
    .with("is_premium", true)
    .with("published_at", new Date())
    .withStrings("tags", Arrays.asList("tech", "mobile", "android"))
    .build();

Nested Properties

Use nested EventProperties to represent hierarchical data structures:

val properties = EventProperties.from(
    "article_id" to 12345,
    "user" to EventProperties.from(
        "type" to "premium",        // user.type
        "premium" to true,           // user.premium
        "subscription_tier" to "gold" // user.subscription_tier
    ),
    "metadata" to EventProperties.from(
        "source" to "mobile_app",
        "version" to "2.1.0"
    )
)

EventProperties userProps = new EventProperties.Builder()
    .with("type", "premium")
    .with("premium", true)
    .with("subscription_tier", "gold")
    .build();

EventProperties metadataProps = new EventProperties.Builder()
    .with("source", "mobile_app")
    .with("version", "2.1.0")
    .build();

EventProperties properties = new EventProperties.Builder()
    .with("article_id", 12345)
    .with("user", userProps)
    .with("metadata", metadataProps)
    .build();

Complete Example

Here’s a complete example matching a typical Pageview event schema:

Schema Definition

Name	Type
id	Long
description	String
tags	List of String
published_at	DateTime
user.type	String
user.premium	Boolean

private fun pageProperties(
    id: Long,
    description: String,
    tags: List<String>,
    published: Date,
    userType: String,
    userIsPremium: Boolean
): EventProperties =
    EventProperties.from(
        "isp_info" to EventProperties.ISP_INFO,
        "geo_info" to EventProperties.GEO_INFO,
        "id" to id,
        "description" to description,
        "tags" to tags,
        "published_at" to published,
        "user" to EventProperties.from(
            "type" to userType,      // user.type
            "premium" to userIsPremium // user.premium
        )
    )

// Usage
val properties = pageProperties(
    id = 12345L,
    description = "Article about Android development",
    tags = listOf("android", "mobile", "development"),
    published = Date(),
    userType = "subscriber",
    userIsPremium = true
)

pageTracker = permutive.trackPage(
    title = "Article Title",
    url = Uri.parse("https://example.com/article"),
    eventProperties = properties
)

private EventProperties pageProperties(
    Long id,
    String description,
    List<String> tags,
    Date published,
    String userType,
    Boolean userIsPremium
) {
    return new EventProperties.Builder()
        .with("isp_info", EventProperties.getISP_INFO())
        .with("geo_info", EventProperties.getGEO_INFO())
        .with("id", id)
        .with("description", description)
        .withStrings("tags", tags)
        .with("published_at", published)
        .with("user", new EventProperties.Builder()
            .with("type", userType)      // user.type
            .with("premium", userIsPremium) // user.premium
            .build()
        )
        .build();
}

// Usage
EventProperties properties = pageProperties(
    12345L,
    "Article about Android development",
    Arrays.asList("android", "mobile", "development"),
    new Date(),
    "subscriber",
    true
);

PageTracker pageTracker = permutive.trackPage(
    properties,
    "Article Title",
    Uri.parse("https://example.com/article"),
    null
);

Event Enrichment

Events can be enriched with additional information automatically by using special constants.

Location and ISP Enrichment

Add location and ISP data to events using these constants:

EventProperties.from(
    "isp_info" to EventProperties.ISP_INFO,        // ISP information
    "geo_info" to EventProperties.GEO_INFO,        // Geographic location
    "ip_address" to EventProperties.IP_ADDRESS_HASH // Hashed IP address
)

This enriches events with:

ISP_INFO: Internet Service Provider details
GEO_INFO: Geographic location (country, region, city)
IP_ADDRESS_HASH: Hashed IP address for privacy

Contact Technical Services for configuration details.

Watson NLP Enrichment

Add IBM Watson Natural Language Understanding data:

EventProperties.from(
    "watson_concepts" to EventProperties.ALCHEMY_CONCEPTS,
    "watson_entities" to EventProperties.ALCHEMY_ENTITIES,
    "watson_keywords" to EventProperties.ALCHEMY_KEYWORDS,
    "watson_taxonomy" to EventProperties.ALCHEMY_TAXONOMY,
    "watson_emotion" to EventProperties.ALCHEMY_DOCUMENT_EMOTION,
    "watson_sentiment" to EventProperties.ALCHEMY_DOCUMENT_SENTIMENT,
    "watson_taxonomy_labels" to EventProperties.ALCHEMY_TAXONOMY_LABELS,
    "watson_entity_names" to EventProperties.ALCHEMY_ENTITY_NAMES
)

See IBM Watson Integration for details.

Complete Enrichment Example

pageTracker = permutive.trackPage(
    eventProperties = EventProperties.from(
        "isp_info" to EventProperties.ISP_INFO,
        "geo_info" to EventProperties.GEO_INFO,
        "ip_address" to EventProperties.IP_ADDRESS_HASH,
        "article_id" to 12345,
        "category" to "technology"
    ),
    title = "Tech Article",
    url = Uri.parse("https://www.example.com/article"),
    referrer = Uri.parse("https://www.example.com/home")
)

pageTracker = permutive.trackPage(
    new EventProperties.Builder()
        .with("isp_info", EventProperties.getISP_INFO())
        .with("geo_info", EventProperties.getGEO_INFO())
        .with("ip_address", EventProperties.getIP_ADDRESS_HASH())
        .with("article_id", 12345)
        .with("category", "technology")
        .build(),
    "Tech Article",
    Uri.parse("https://www.example.com/article"),
    Uri.parse("https://www.example.com/home")
);

Type-Specific Methods (Java)

When building properties in Java, use type-specific methods for lists:

EventProperties properties = new EventProperties.Builder()
    .withStrings("tags", Arrays.asList("tech", "mobile"))     // List<String>
    .withIntegers("scores", Arrays.asList(1, 2, 3))           // List<Integer>
    .withLongs("ids", Arrays.asList(100L, 200L))              // List<Long>
    .withBooleans("flags", Arrays.asList(true, false))        // List<Boolean>
    .withDoubles("prices", Arrays.asList(9.99, 19.99))        // List<Double>
    .build();

Common Patterns

E-Commerce Properties

val purchaseProperties = EventProperties.from(
    "order_id" to "ORD-12345",
    "total_amount" to 149.99,
    "currency" to "USD",
    "item_count" to 3,
    "items" to listOf(
        EventProperties.from(
            "product_id" to "PROD-001",
            "name" to "Widget",
            "price" to 49.99,
            "quantity" to 1
        ),
        EventProperties.from(
            "product_id" to "PROD-002",
            "name" to "Gadget",
            "price" to 99.99,
            "quantity" to 2
        )
    ),
    "payment_method" to "credit_card",
    "shipping_method" to "express"
)

Content Properties

val contentProperties = EventProperties.from(
    "article_id" to 12345,
    "title" to "Article Title",
    "author" to "John Doe",
    "category" to "Technology",
    "subcategories" to listOf("Mobile", "Android"),
    "word_count" to 1500,
    "published_at" to Date(),
    "is_premium" to true,
    "tags" to listOf("android", "sdk", "mobile"),
    "isp_info" to EventProperties.ISP_INFO,
    "geo_info" to EventProperties.GEO_INFO
)

User Context Properties

val userContextProperties = EventProperties.from(
    "user" to EventProperties.from(
        "id" to "user_12345",
        "type" to "premium",
        "subscription_tier" to "gold",
        "is_logged_in" to true,
        "account_age_days" to 365
    ),
    "session" to EventProperties.from(
        "id" to "session_abc123",
        "duration_seconds" to 120,
        "page_views" to 5
    )
)

Validation and Errors

Schema Validation

Properties are validated against your event schema in the Permutive dashboard: ✅ Valid:

Property names match exactly (case-sensitive)
Property types match schema
All required properties included

❌ Invalid:

Misspelled property names
Wrong property types
Missing required properties

Common Validation Errors

Problem: Event rejected with “Schema validation failed” Causes:

Property name doesn’t match dashboard (case-sensitive)
Property type doesn’t match schema
Required property missing

Solutions:

Verify property names in dashboard
Check property types match
Include all required properties

Example of incorrect types:

// ❌ WRONG - Sending string where number expected
EventProperties.from(
    "article_id" to "12345"  // Schema expects Long, got String
)

// ✅ CORRECT
EventProperties.from(
    "article_id" to 12345L   // Matches schema
)

Best Practices

Do
Don't

Match property names and types exactly with your schema
Use enrichment constants when available
Create reusable property builder functions
Use nested properties for related data
Include relevant context properties
Validate against your schema before deploying

Never send unhashed PII:

// ❌ WRONG - Sending raw email
EventProperties.from("email" to "user@example.com")

// ✅ CORRECT - Hash before sending
EventProperties.from("email_sha256" to hashSHA256("user@example.com"))

Troubleshooting

Properties not appearing in dashboard

Solutions:

Check property names match schema exactly
Verify property types are correct
Ensure event is being accepted (check logs)
Confirm properties are defined in dashboard schema

Type conversion errors / App crashes

Cause: Incompatible type passed to builder.Solution: Ensure types match:

// ❌ WRONG
EventProperties.from("count" to "10")  // String instead of number

// ✅ CORRECT
EventProperties.from("count" to 10)    // Number

Nested properties not recognized

Solution: Ensure nested properties are defined in your dashboard schema:

user.type
user.premium
user.subscription_tier

Page Tracking

Using properties with PageTracker

Event Tracking

Using properties with EventTracker

Identity Management

Hashing PII

Issues

Solutions to common issues

API Reference

For complete API documentation, see the Javadocs.